GNU bug report logs - #43107
Errors in man pages

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 43107 in the body.
You can then email your comments to 43107 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Helge Kreutzmann <debian <at> helgefjell.de>
To: bug-gzip <at> gnu.org
Subject: Errors in man pages
Date: Sun, 30 Aug 2020 07:39:36 +0200

[Message part 1 (text/plain, inline)]

Dear gzip maintainer,
the manpage-l10n project maintains a large number of translations of
man pages both from a large variety of sources (including gzip) as
well for a large variety of target languages.

During their work translators notice different possible issues in the
original (english) man pages. Sometimes this is a straightforward
typo, sometimes a hard to read sentence, sometimes this is a
convention not held up and sometimes we simply do not understand the
original.

We use several distributions as sources and update regularly (at
least every 2 month). This means we are fairly recent (some
distributions like archlinux also update frequently) but might miss
the latest upstream version once in a while, so the error might be
already fixed. We apologize and ask you to close the issue immediately
if this should be the case, but given the huge volume of projects and
the very limited number of volunteers we are not able to double check
each and every issue.

Secondly we translators see the manpages in the neutral po format,
i.e. converted and harmonized, but not the original source (be it man,
groff, xml or other). So we cannot provide a true patch (where
possible), but only an approximation which you need to convert into
your source format.

Finally the issues I'm reporting have accumulated over time and are
not always discovered by me, so sometimes my description of the
problem my be a bit limited - do not hesitate to ask so we can clarify
them.

I'm now reporting the errors for your project. If future reports
should use another channel, please let me know.

Man page: gzip.1
Issue: Wrong order of entries

"znew(1), zcmp(1), zmore(1), zforce(1), gzexe(1), zip(1), unzip(1), "
"compress(1)"
--
Man page: zgrep.1
Issue: Wrong markup of command names, i.e. I<> instead of the proper B<>

"I<Zgrep> invokes I<grep> on compressed or gzipped files.  All options "
"specified are passed directly to I<grep>.  If no file is specified, then the "
"standard input is decompressed if necessary and fed to grep.  Otherwise the "
"given files are uncompressed if necessary and fed to I<grep>."

"If the GREP environment variable is set, I<zgrep> uses it as the I<grep> "
"program to be invoked."

"I<Zgrep> invokes I<grep> on compressed, xz'ed, lzma'ed, bzip2'ed or gzipped "
"files.  All options specified are passed directly to I<grep>.  If no file is "
"specified, then the standard input is decompressed if necessary and fed to "
"grep.  Otherwise the given files are uncompressed if necessary and fed to "
"I<grep>."

-- 
      Dr. Helge Kreutzmann                     debian <at> helgefjell.de
           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 (application/pgp-signature, inline)]

Message #8 received at 43107 <at> debbugs.gnu.org (full text, mbox):

From: Paul Eggert <eggert <at> cs.ucla.edu>
To: Helge Kreutzmann <debian <at> helgefjell.de>, 43107 <at> debbugs.gnu.org
Subject: Re: bug#43107: Errors in man pages
Date: Sun, 30 Aug 2020 15:14:31 -0700

On 8/29/20 10:39 PM, Helge Kreutzmann wrote:
> Man page: gzip.1 Issue: Wrong order of entries
>
> "znew(1), zcmp(1), zmore(1), zforce(1), gzexe(1), zip(1), unzip(1),"
> "compress(1)"

In what senice is that the wrong order?

Message #11 received at 43107 <at> debbugs.gnu.org (full text, mbox):

From: Paul Eggert <eggert <at> cs.ucla.edu>
To: Helge Kreutzmann <debian <at> helgefjell.de>
Cc: 43107 <at> debbugs.gnu.org
Subject: Re: bug#43107: Errors in man pages
Date: Sun, 30 Aug 2020 15:16:21 -0700

On 8/30/20 3:14 PM, Paul Eggert wrote:
> On 8/29/20 10:39 PM, Helge Kreutzmann wrote:
>  > Man page: gzip.1 Issue: Wrong order of entries
>  >
>  > "znew(1), zcmp(1), zmore(1), zforce(1), gzexe(1), zip(1), unzip(1),"
>  > "compress(1)"
> 
> In what senice is that the wrong order?

Sorry, meant to write "sense", not "senice".

Message #14 received at 43107 <at> debbugs.gnu.org (full text, mbox):

From: Helge Kreutzmann <debian <at> helgefjell.de>
To: Paul Eggert <eggert <at> cs.ucla.edu>
Cc: 43107 <at> debbugs.gnu.org
Subject: Re: bug#43107: Errors in man pages
Date: Mon, 31 Aug 2020 18:36:50 +0200

[Message part 1 (text/plain, inline)]

Hello Paul,
On Sun, Aug 30, 2020 at 03:16:21PM -0700, Paul Eggert wrote:
> On 8/30/20 3:14 PM, Paul Eggert wrote:
> > On 8/29/20 10:39 PM, Helge Kreutzmann wrote:
> >  > Man page: gzip.1 Issue: Wrong order of entries
> >  >
> >  > "znew(1), zcmp(1), zmore(1), zforce(1), gzexe(1), zip(1), unzip(1),"
> >  > "compress(1)"
> > 
> > In what senice is that the wrong order?
> 
> Sorry, meant to write "sense", not "senice".

If you read man-pages(7) you can find a section regarding SEE ALSO,
where a certain order is prescribed. This is what this comment refers
to.

Greetings

          Helge

         


-- 
      Dr. Helge Kreutzmann                     debian <at> helgefjell.de
           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 (application/pgp-signature, inline)]

Message #17 received at 43107 <at> debbugs.gnu.org (full text, mbox):

From: Paul Eggert <eggert <at> cs.ucla.edu>
To: Helge Kreutzmann <debian <at> helgefjell.de>
Cc: 43107 <at> debbugs.gnu.org
Subject: Re: bug#43107: Errors in man pages
Date: Mon, 31 Aug 2020 10:26:09 -0700

On 8/31/20 9:36 AM, Helge Kreutzmann wrote:
> If you read man-pages(7)

What's 'man-pages(7)', and what order does it suggest for gzip's man pages?

Message #20 received at 43107 <at> debbugs.gnu.org (full text, mbox):

From: Helge Kreutzmann <debian <at> helgefjell.de>
To: Paul Eggert <eggert <at> cs.ucla.edu>
Cc: 43107 <at> debbugs.gnu.org
Subject: Re: bug#43107: Errors in man pages
Date: Mon, 31 Aug 2020 19:37:26 +0200

[Message part 1 (text/plain, inline)]

Hello Paul,
On Mon, Aug 31, 2020 at 10:26:09AM -0700, Paul Eggert wrote:
> On 8/31/20 9:36 AM, Helge Kreutzmann wrote:
> > If you read man-pages(7)
> 
> What's 'man-pages(7)', and what order does it suggest for gzip's man pages?

The description how a man page should look like. Usually your system
should have a package called "manpages" or similar. This package
contains the basic set of man pages. One of them is the man page
called man-pages[1]. So on the console you issue

man man-pages

And you get the description of how a man page should look like. 

Most likely it works already out of the box. If not, you might want to
search with your package manager.

Greetings

       Helge

[1] Actually, this page is translated in many languages already. So in
    case you have loclized man pages installed, this page might even
    come in your favorite language as well …

-- 
      Dr. Helge Kreutzmann                     debian <at> helgefjell.de
           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 (application/pgp-signature, inline)]

Message #23 received at 43107 <at> debbugs.gnu.org (full text, mbox):

From: Paul Eggert <eggert <at> cs.ucla.edu>
To: Helge Kreutzmann <debian <at> helgefjell.de>
Cc: 43107 <at> debbugs.gnu.org
Subject: Re: bug#43107: Errors in man pages
Date: Mon, 31 Aug 2020 11:20:00 -0700

On 8/31/20 10:37 AM, Helge Kreutzmann wrote:
>> What's 'man-pages(7)', and what order does it suggest for gzip's man
>> pages?
> The description how a man page should look like. Usually your system should
> have a package called "manpages" or similar.

But different systems have different versions of this man page. Which one's
right and why?

And what, specifically, should be changed for gzip's man pages? Why should
some of its man pages be changed, and not others? A patch (in 'git
format-patch' format) would make your request clearer.

Please bear in mind that for the GNU project, man pages are only a secondary
form of documentation and are low priority. I've already spent more time on
this topic than I'd like.

Message #26 received at 43107 <at> debbugs.gnu.org (full text, mbox):

From: Helge Kreutzmann <debian <at> helgefjell.de>
To: Paul Eggert <eggert <at> cs.ucla.edu>
Cc: 43107 <at> debbugs.gnu.org
Subject: Re: bug#43107: Errors in man pages
Date: Mon, 31 Aug 2020 21:13:34 +0200

[Message part 1 (text/plain, inline)]

Hello Paul,
On Mon, Aug 31, 2020 at 11:20:00AM -0700, Paul Eggert wrote:
> On 8/31/20 10:37 AM, Helge Kreutzmann wrote:
> >> What's 'man-pages(7)', and what order does it suggest for gzip's man
> >> pages?
> > The description how a man page should look like. Usually your system should
> > have a package called "manpages" or similar.
> 
> But different systems have different versions of this man page. Which one's
> right and why?

I don't think this man page has changed over many years. (at least not
much).

> And what, specifically, should be changed for gzip's man pages? Why should
> some of its man pages be changed, and not others? A patch (in 'git
> format-patch' format) would make your request clearer.

We (i.e. some translators) noticed some possible errors but we did not
search for them systematically. 

So the right order probably would be:
compress(1), gzexe(1), unzip(1), zcmp(1), zforce(1), zip(1), zmore(1), znew(1), 

But, actually, personally I would not change it, I think the previous
order looks better.

As stated in my e-mail, we (i.e. myself) are unable to provide a true
patch.

> Please bear in mind that for the GNU project, man pages are only a secondary
> form of documentation and are low priority. I've already spent more time on
> this topic than I'd like.

This list from us is just a suggestion for possible fixes. Those you
agree with, please apply, those you don't, keep out (it would be nice,
if you could inform us, so we can mark them). So for this specific
issue I think we both tend to agree that the fix is probably not worth
the effort.

Regarding priorization: Translators think your pages are quite
important. For example, gzip is translated into at least 9 languages, so at
least this part of your user base thinks differently. But each project
has it's own prioritys, and for myself at least man pages are the
primary source of information, especially for console-based tools.

In conclusion: it would be nice if you could fix at least the other
points and tell me how you handled them so I (or some other
translator) avoids reporting them again in a few years time.

Greetings and thanks for developing and maintaining gzip!

         Helge


-- 
      Dr. Helge Kreutzmann                     debian <at> helgefjell.de
           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 (application/pgp-signature, inline)]

Message #31 received at 43107-done <at> debbugs.gnu.org (full text, mbox):

From: Paul Eggert <eggert <at> cs.ucla.edu>
To: Helge Kreutzmann <debian <at> helgefjell.de>
Cc: 43107-done <at> debbugs.gnu.org
Subject: Re: bug#43107: Errors in man pages
Date: Mon, 31 Aug 2020 16:14:17 -0700

[Message part 1 (text/plain, inline)]

On 8/31/20 12:13 PM, Helge Kreutzmann wrote:
> But, actually, personally I would not change it, I think the previous
> order looks better.

OK, let's leave that alone then.

The remaining proposed changes are to use bold rather than italics for command 
names so I installed the attached to do that. Closing the bug report.

[0001-doc-prefer-bold-to-italics-for-command-names.patch (text/x-patch, attachment)]

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.