More man page improvements

classic Classic list List threaded Threaded
9 messages Options
Reply | Threaded
Open this post in threaded view
|

More man page improvements

Helge Kreutzmann-2
Hello Guillem,
I see that you are working on the man pages. I updated de.po
accordingly.

During the recent proofreading we discovered some possible
improvements to the original pages as well, which I list for you to
consider and implement (where you agree):


#  bug report numbers → bug report numbers of bugs
#. type: Plain text
#: deb-changes.man
msgid ""
"A space-separated list of bug report numbers that have been resolved with "
"this upload.  The distribution archive software might use this field to "
"automatically close the referred bug numbers in the distribution bug "
"tracking system."


#  debian/changelog → I<debian/changelog>
#. type: Plain text
#: deb-src-control.man
msgid ""
"The value of this field is the name of the source package, and should match "
"the name of the source package in the debian/changelog file. A package name "
"must consist only of lowercase letters (a-z), digits (0-9), plus (+) and "
"minus (-) signs, and periods (.). Package names must be at least two "
"characters long and must start with a lowercase alphanumeric character (a-"
"z0-9)."


#  libgcc → B<libgcc> or quotes?
#. type: Plain text
#: deb-src-symbols.man
msgid ""
"dpkg-gensymbols has an internal blacklist of symbols that should not appear "
"in symbols files as they are usually only side-effects of implementation "
"details of the toolchain. If for some reason, you really want one of those "
"symbols to be included in the symbols file, you should tag the symbol with "
"B<ignore-blacklist>. It can be necessary for some low level toolchain "
"libraries like libgcc."


#  markup of "eval"?
#. type: Plain text
#: dpkg-architecture.man
msgid ""
"Print an export command. This can be used to set the environment variables "
"using eval."


#  Why is this bold but not the others?
#. type: TP
#: dpkg-buildflags.man
#, no-wrap
msgid "B<lfs>"


#  debian/chagelog → I<debian/changelog>
#. type: Plain text
#: dpkg-gensymbols.man
msgid ""
"Define the package version. Defaults to the version extracted from debian/"
"changelog. Required if called outside of a source package tree."


#  debian/changelog → B<debian/changelog>
#. type: Plain text
#: dpkg-mergechangelogs.man
msgid ""
"Then you have to setup the merge attribute for the debian/changelog file "
"either in B<.gitattributes> in the repository itself, or in B<.git/info/"
"attributes>:"


#  apt → B<apt>
#. type: Plain text
#: dselect.man
msgid ""
"The built in access methods can no longer stand up to current quality "
"standards. Use the access method provided by apt, it is not only not broken, "
"it is also much more flexible than the built in access methods."


And in general, sometimes file names are marked up, sometimes not.

Greetings

          Helge
--
      Dr. Helge Kreutzmann                     [hidden email]
           Dipl.-Phys.                   http://www.helgefjell.de/debian.php
        64bit GNU powered                     gpg signed mail preferred
           Help keep free software "libre": http://www.ffii.de/

signature.asc (849 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: More man page improvements

Guillem Jover
Hi!

On Tue, 2020-05-05 at 21:09:05 +0200, Helge Kreutzmann wrote:
> During the recent proofreading we discovered some possible
> improvements to the original pages as well, which I list for you to
> consider and implement (where you agree):

Perfect thanks!

> #  bug report numbers → bug report numbers of bugs
> #. type: Plain text
> #: deb-changes.man
> msgid ""
> "A space-separated list of bug report numbers that have been resolved with "
> "this upload.  The distribution archive software might use this field to "
> "automatically close the referred bug numbers in the distribution bug "
> "tracking system."

I think the original is correct here. This is a list of bug-report
numbers. Maybe hyphenating here would make this more clear? Otherwise
could you say what seems wrong?

> #  libgcc → B<libgcc> or quotes?
> #. type: Plain text
> #: deb-src-symbols.man

Done.

> #  markup of "eval"?
> #. type: Plain text
> #: dpkg-architecture.man
> msgid ""
> "Print an export command. This can be used to set the environment variables "
> "using eval."

Done, and clarified that eval is a POSIX shell command.

> #  apt → B<apt>
> #. type: Plain text
> #: dselect.man

Done. I've corrected all apt and aptitude instances, updated them to
apt instead of apt-get when appropriate and fixed the section numbers.

> #  Why is this bold but not the others?
> #. type: TP
> #: dpkg-buildflags.man
> #, no-wrap
> msgid "B<lfs>"

Hmm the other feature names are in bold too. Or are you referring to
something else here?

> #  debian/changelog → I<debian/changelog>
> #. type: Plain text
> #: deb-src-control.man
>
> #  debian/chagelog → I<debian/changelog>
> #. type: Plain text
> #: dpkg-gensymbols.man
>
> #  debian/changelog → B<debian/changelog>
> #. type: Plain text
> #: dpkg-mergechangelogs.man
>
> And in general, sometimes file names are marked up, sometimes not.

Right, I've got an unfinished patch laying around fixing pathnames to
be in italic, but I think I'll postpone this one for now until the
switch to POD, so that I can use F<> instead of I<>. There's also the
problem with pathnames that contain variable parts, which up to now
were represented as B</some/pathname/>I<variable-part>B</rest>, and
with all pathnames in italics gets rather cumbersome.

The «man groff_man» convention appears to be to use mathematical
typography (use italics for the static parts in pathnames and roman
for the variable parts), but of course this does not even seem
consistent with other conventions such as «man man-pages». :/


I'll push later today.

Thanks,
Guillem

Reply | Threaded
Open this post in threaded view
|

Re: More man page improvements

Helge Kreutzmann-2
Hello Guillem,
On Sat, May 09, 2020 at 10:19:18PM +0200, Guillem Jover wrote:

> On Tue, 2020-05-05 at 21:09:05 +0200, Helge Kreutzmann wrote:
> > #  bug report numbers → bug report numbers of bugs
> > #. type: Plain text
> > #: deb-changes.man
> > msgid ""
> > "A space-separated list of bug report numbers that have been resolved with "
> > "this upload.  The distribution archive software might use this field to "
> > "automatically close the referred bug numbers in the distribution bug "
> > "tracking system."
>
> I think the original is correct here. This is a list of bug-report
> numbers. Maybe hyphenating here would make this more clear? Otherwise
> could you say what seems wrong?
Well, you don't resolve bug report numbers, you resolve bugs. So the
list is of course the numbers, but afterwards you actually close the
bugs themselves.

> > #  Why is this bold but not the others?
> > #. type: TP
> > #: dpkg-buildflags.man
> > #, no-wrap
> > msgid "B<lfs>"
>
> Hmm the other feature names are in bold too. Or are you referring to
> something else here?

In the po file the others are not all bold:
msgid "qa"

msgid "B<bug>"

msgid "B<canary>"

msgid "sanitize"

and so on. I suppose they all should be bold?

> Right, I've got an unfinished patch laying around fixing pathnames to
> be in italic, but I think I'll postpone this one for now until the
> switch to POD, so that I can use F<> instead of I<>. There's also the
> problem with pathnames that contain variable parts, which up to now
> were represented as B</some/pathname/>I<variable-part>B</rest>, and
> with all pathnames in italics gets rather cumbersome.

I see.

Hopefully the transition to pod keeps the fuzzy strings to a minimum.

> I'll push later today.

Thanks

        Helge

--
      Dr. Helge Kreutzmann                     [hidden email]
           Dipl.-Phys.                   http://www.helgefjell.de/debian.php
        64bit GNU powered                     gpg signed mail preferred
           Help keep free software "libre": http://www.ffii.de/

signature.asc (849 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: More man page improvements

Guillem Jover
On Sun, 2020-05-10 at 12:43:19 +0200, Helge Kreutzmann wrote:

> On Sat, May 09, 2020 at 10:19:18PM +0200, Guillem Jover wrote:
> > On Tue, 2020-05-05 at 21:09:05 +0200, Helge Kreutzmann wrote:
> > > #  bug report numbers → bug report numbers of bugs
> > > #. type: Plain text
> > > #: deb-changes.man
> > > msgid ""
> > > "A space-separated list of bug report numbers that have been resolved with "
> > > "this upload.  The distribution archive software might use this field to "
> > > "automatically close the referred bug numbers in the distribution bug "
> > > "tracking system."
> >
> > I think the original is correct here. This is a list of bug-report
> > numbers. Maybe hyphenating here would make this more clear? Otherwise
> > could you say what seems wrong?
>
> Well, you don't resolve bug report numbers, you resolve bugs. So the
> list is of course the numbers, but afterwards you actually close the
> bugs themselves.

Ah! I've changed this now to:

  A space-separated list of bug report numbers for bug reports that
  have been resolved with this upload.

> > > #  Why is this bold but not the others?
> > > #. type: TP
> > > #: dpkg-buildflags.man
> > > #, no-wrap
> > > msgid "B<lfs>"
> >
> > Hmm the other feature names are in bold too. Or are you referring to
> > something else here?
>
> In the po file the others are not all bold:
> msgid "qa"
> …
> msgid "B<bug>"
> …
> msgid "B<canary>"
> …
> msgid "sanitize"
> …
> and so on. I suppose they all should be bold?

Ah right. These are implicitly bold as they are within a .SS title
(the same applies to .SH titles). The same will happen with POD where
=head1 and =head2 titles are implicitly bold.

> > Right, I've got an unfinished patch laying around fixing pathnames to
> > be in italic, but I think I'll postpone this one for now until the
> > switch to POD, so that I can use F<> instead of I<>. There's also the
> > problem with pathnames that contain variable parts, which up to now
> > were represented as B</some/pathname/>I<variable-part>B</rest>, and
> > with all pathnames in italics gets rather cumbersome.
>
> I see.
>
> Hopefully the transition to pod keeps the fuzzy strings to a minimum.

Yeah, I have that in mind to try to reduce it as much as possible.

Thanks,
Guillem

Reply | Threaded
Open this post in threaded view
|

Re: More man page improvements

Helge Kreutzmann-2
Hello Guillem,
after your recent push the man pages no longer build, i.e.
git clean -d -X -f
autoreconf -f -i
./configure
make -C man update-po

fails with:
Fehler: »msginit -i po/dpkg-man.pot --locale add_de -o ?po/de.add --no-translator« endete mit dem Wert 1.

If I remove the "?", this line suceedes:

helge@samd:/tmp/dpkg/man$ msginit -i po/dpkg-man.pot --locale add_de -o po/de.add --no-translator
po/de.add wurde erstellt.

I'm workin on stable, if this matters.

Greetings

          Helge
--
      Dr. Helge Kreutzmann                     [hidden email]
           Dipl.-Phys.                   http://www.helgefjell.de/debian.php
        64bit GNU powered                     gpg signed mail preferred
           Help keep free software "libre": http://www.ffii.de/

signature.asc (849 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: More man page improvements

Guillem Jover
Hi!

On Tue, 2020-05-12 at 19:42:02 +0200, Helge Kreutzmann wrote:

> after your recent push the man pages no longer build, i.e.
> git clean -d -X -f
> autoreconf -f -i
> ./configure
> make -C man update-po
>
> fails with:
> Fehler: »msginit -i po/dpkg-man.pot --locale add_de -o ?po/de.add --no-translator« endete mit dem Wert 1.
>
> If I remove the "?", this line suceedes:
>
> helge@samd:/tmp/dpkg/man$ msginit -i po/dpkg-man.pot --locale add_de -o po/de.add --no-translator
> po/de.add wurde erstellt.
>
> I'm workin on stable, if this matters.

Hmm, right that would not work entirely. :/ The latest po4a release
changed the default for the --porefs option, and removed the old way
to change that default, so code that changed the default cannot
specify it in a way that is backwards compatible. This should mostly
affect wrapping, so I guess I could also relax the Build-Depends, but
I assume we'll get flip-flops in the .po depending on where it got
updated.

I'm also wondering about the addenda, which I refactored to specify
them only once in the config, but that only works in testing/sid. We
removed references to man page authors some time ago, so was
considering whether to do the same for the addenda and remove them to
match the upstream part, which would also remove that problem entirely.
Not sure how that would fly with translators though?

Thanks,
Guillem

Reply | Threaded
Open this post in threaded view
|

Re: More man page improvements

Helge Kreutzmann-2
Hello Guillem,
On Fri, May 15, 2020 at 02:57:28PM +0200, Guillem Jover wrote:

> On Tue, 2020-05-12 at 19:42:02 +0200, Helge Kreutzmann wrote:
> > after your recent push the man pages no longer build, i.e.
> > git clean -d -X -f
> > autoreconf -f -i
> > ./configure
> > make -C man update-po
> >
> > fails with:
> > Fehler: »msginit -i po/dpkg-man.pot --locale add_de -o ?po/de.add --no-translator« endete mit dem Wert 1.
> >
> > If I remove the "?", this line suceedes:
> >
> > helge@samd:/tmp/dpkg/man$ msginit -i po/dpkg-man.pot --locale add_de -o po/de.add --no-translator
> > po/de.add wurde erstellt.
> >
> > I'm workin on stable, if this matters.
>
> Hmm, right that would not work entirely. :/ The latest po4a release
> changed the default for the --porefs option, and removed the old way
> to change that default, so code that changed the default cannot
> specify it in a way that is backwards compatible. This should mostly
> affect wrapping, so I guess I could also relax the Build-Depends, but
> I assume we'll get flip-flops in the .po depending on where it got
> updated.
Ok, then I run this in a sid chroot.

> I'm also wondering about the addenda, which I refactored to specify
> them only once in the config, but that only works in testing/sid. We
> removed references to man page authors some time ago, so was
> considering whether to do the same for the addenda and remove them to
> match the upstream part, which would also remove that problem entirely.
> Not sure how that would fly with translators though?

I would rather keep the translators, because when translation issues
arise they should be known as first point of contact. Also translation
is a significant effort often overlooked so having the names there is
also a way to acknowledge that effort and saying "thank you".

(And except this hopefully temporary issue the maintenance effort for
your side is almost zero).

Greetings

                 Helge

P.S. I'll start working on updateing the German man page translation
     tomorrow, might take a few days.

--
      Dr. Helge Kreutzmann                     [hidden email]
           Dipl.-Phys.                   http://www.helgefjell.de/debian.php
        64bit GNU powered                     gpg signed mail preferred
           Help keep free software "libre": http://www.ffii.de/

signature.asc (849 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: More man page improvements

Guillem Jover
On Fri, 2020-05-15 at 22:04:36 +0200, Helge Kreutzmann wrote:

> On Fri, May 15, 2020 at 02:57:28PM +0200, Guillem Jover wrote:
> > On Tue, 2020-05-12 at 19:42:02 +0200, Helge Kreutzmann wrote:
> > > I'm workin on stable, if this matters.
> >
> > Hmm, right that would not work entirely. :/ The latest po4a release
> > changed the default for the --porefs option, and removed the old way
> > to change that default, so code that changed the default cannot
> > specify it in a way that is backwards compatible. This should mostly
> > affect wrapping, so I guess I could also relax the Build-Depends, but
> > I assume we'll get flip-flops in the .po depending on where it got
> > updated.
>
> Ok, then I run this in a sid chroot.

I've improved this now in master, and the --porefs value will be
selected based on what is needed, so it should be safe to run it on
stable again.

You'll not get addenda in translations in stable though, but it should
otherwise be fine for testing that the .po files are good, and
translated man pages build. So feel free to keep working in a stable
system if you want, and please let me know of similar regressions in
the future.

> > I'm also wondering about the addenda, which I refactored to specify
> > them only once in the config, but that only works in testing/sid. We
> > removed references to man page authors some time ago, so was
> > considering whether to do the same for the addenda and remove them to
> > match the upstream part, which would also remove that problem entirely.
> > Not sure how that would fly with translators though?
>
> I would rather keep the translators, because when translation issues
> arise they should be known as first point of contact.

Ok, that makes sense. More so because with the switch to POD, the
copyright header (for now) does not end up in the generated man pages,
so even checking the source would not give any such indication.

> Also translation
> is a significant effort often overlooked so having the names there is
> also a way to acknowledge that effort and saying "thank you".

Oh I'm completely aware, I've done translation stuff too and I know
it's an endless ton of work and time, so please do not take this as
undervaluing that work!

I also think documentation is important, but personally I tend to find
AUTHOR sections in man pages distracting (even when I'm one of them :).
First because it's usually not clear whether this is about the
program or the man page, then because it tends to get out of sync with
the copyright header, and finally because it feels like details that
if interested in can be checked in the source code.

> (And except this hopefully temporary issue the maintenance effort for
> your side is almost zero).

Sure, it's not a big deal, and I'm fine with keeping them, so let's do
that then.

Thanks,
Guillem

Reply | Threaded
Open this post in threaded view
|

Re: More man page improvements

Helge Kreutzmann-2
Hello Guillem,
On Sun, May 17, 2020 at 12:59:02AM +0200, Guillem Jover wrote:

> On Fri, 2020-05-15 at 22:04:36 +0200, Helge Kreutzmann wrote:
> > On Fri, May 15, 2020 at 02:57:28PM +0200, Guillem Jover wrote:
> > > On Tue, 2020-05-12 at 19:42:02 +0200, Helge Kreutzmann wrote:
> > > > I'm workin on stable, if this matters.
> > >
> > > Hmm, right that would not work entirely. :/ The latest po4a release
> > > changed the default for the --porefs option, and removed the old way
> > > to change that default, so code that changed the default cannot
> > > specify it in a way that is backwards compatible. This should mostly
> > > affect wrapping, so I guess I could also relax the Build-Depends, but
> > > I assume we'll get flip-flops in the .po depending on where it got
> > > updated.
> >
> > Ok, then I run this in a sid chroot.
>
> I've improved this now in master, and the --porefs value will be
> selected based on what is needed, so it should be safe to run it on
> stable again.
No, it does not work:
make: Entering directory '/tmp/dpkg/man'
  PO4A   update-po
 (3149 entries)
Error: 'msgmerge -U po/de.add po/dpkg-man.pot --add-location=file --previous --backup=none' exited with value 1.
make: *** [Makefile:893: update-po] Error 1
make: Leaving directory '/tmp/dpkg/man'

But again, I can use a sid chroot.

> > > I'm also wondering about the addenda, which I refactored to specify
> > > them only once in the config, but that only works in testing/sid. We
> > > removed references to man page authors some time ago, so was
> > > considering whether to do the same for the addenda and remove them to
> > > match the upstream part, which would also remove that problem entirely.
> > > Not sure how that would fly with translators though?
> >
> > I would rather keep the translators, because when translation issues
> > arise they should be known as first point of contact.
>
> Ok, that makes sense. More so because with the switch to POD, the
> copyright header (for now) does not end up in the generated man pages,
> so even checking the source would not give any such indication.
>
> > Also translation
> > is a significant effort often overlooked so having the names there is
> > also a way to acknowledge that effort and saying "thank you".
>
> Oh I'm completely aware, I've done translation stuff too and I know
> it's an endless ton of work and time, so please do not take this as
> undervaluing that work!
>
> I also think documentation is important, but personally I tend to find
> AUTHOR sections in man pages distracting (even when I'm one of them :).
> First because it's usually not clear whether this is about the
> program or the man page, then because it tends to get out of sync with
> the copyright header, and finally because it feels like details that
> if interested in can be checked in the source code.
>
> > (And except this hopefully temporary issue the maintenance effort for
> > your side is almost zero).
>
> Sure, it's not a big deal, and I'm fine with keeping them, so let's do
> that then.
Great, thanks.

Greetings

         Helge
--
      Dr. Helge Kreutzmann                     [hidden email]
           Dipl.-Phys.                   http://www.helgefjell.de/debian.php
        64bit GNU powered                     gpg signed mail preferred
           Help keep free software "libre": http://www.ffii.de/

signature.asc (849 bytes) Download Attachment