Subject: Re: bug#72914: Issues in man pages of GNU Coreutils
From: Pádraig Brady <[email-masked]>
To: Helge Kreutzmann <[email-masked]>, [email-masked]
Date: Mon, 23 Sep 2024 22:16:50 +0100
List-Id: <debbugs-submit.debbugs.gnu.org>

On 31/08/2024 12:19, Helge Kreutzmann wrote:
> Dear Coreutils maintainer,
> the manpage-l10n project maintains a large number of translations of
> man pages both from a large variety of sources (including coreutils) 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: chgrp.1
> Issue:    values → values.
> 
> "use RFILE's ownership rather than specifying values RFILE is always"
> "dereferenced if a symbolic link."
 > --
 > Man page: chown.1
 > Issue:    values → values.
 >
 > "use RFILE's ownership rather than specifying values RFILE is always"
 > "dereferenced if a symbolic link."
 > --

Above already fixed (but not yet released) in:
https://github.com/coreutils/coreutils/commit/e8c2b921c

> --
> Man page: chgrp.1
> Issue:    '-P' → B<-P>
> 
> "The following options modify how a hierarchy is traversed when the B<-R>"
> "option is also specified.  If more than one is specified, only the final one"
> "takes effect. '-P' is the default."
> --
> Man page: chmod.1
> Issue:    '-H' → B<-H>
> 
> "The following options modify how a hierarchy is traversed when the B<-R>"
> "option is also specified.  If more than one is specified, only the final one"
> "takes effect. '-H' is the default."
> --
> Man page: chown.1
> Issue:    '-P' → B<-P>
> 
> "The following options modify how a hierarchy is traversed when the B<-R>"
> "option is also specified.  If more than one is specified, only the final one"
> "takes effect. '-P' is the default."

Fixed in the just pushed:
https://github.com/coreutils/coreutils/commit/afab48f23

> --
> Man page: echo.1
> Issue:    'printf' → B<printf>(1)
> 
> "Consider using the 'printf' command instead, as it avoids problems when"
> "outputting option-like strings."

Fixed in the just pushed:
https://github.com/coreutils/coreutils/commit/7337076ec

> --
> Man page: env.1
> Issue:    Missing line break before "usage"
> 
> "-S/--split-string usage in scripts"

I think this is OK, however,
the confusion probably stems from the section header [OPTIONS].
I've adjusted this to the more descriptive: [SCRIPT OPTION HANDLING],
and also removed some overly detailed info from the man page.
https://github.com/coreutils/coreutils/commit/4da7daa01

> --
> Man page: expand.1
> Issue:   Missing full stop
> 
> "use comma separated list of tab positions.  The last specified position can"
> "be prefixed with '/' to specify a tab size to use after the last explicitly"
> "specified tab stop.  Also a prefix of '+' can be used to align remaining tab"
> "stops relative to the last specified tab stop instead of the first column"
> --
> Man page: unexpand.1
> Issue:    Missing full stop
> 
> "use comma separated list of tab positions.  The last specified position can"
> "be prefixed with '/' to specify a tab size to use after the last explicitly"
> "specified tab stop.  Also a prefix of '+' can be used to align remaining tab"
> "stops relative to the last specified tab stop instead of the first column"

These follows the pattern of the last sentence in an option description
_not_ having a full stop.  There were a few cases where we weren't
consistent with that pattern actually, which are now fixed up in:
https://github.com/coreutils/coreutils/commit/ac5213acb

 > --
 > Man page: sort.1.po
 > Issue:    "manual" is very vague, this is the manual? Be more precise, e.g. B<name>(1)
 >
 > "compare according to string numerical value; see manual for which strings"
 > "are supported"

Fixed in the just pushed:
https://github.com/coreutils/coreutils/commit/9e5274cd1be

Marking this as done.

Many thanks!

Pádraig.