Re: Issues in man pages of GNU_inetutils

[Erik Auerswald]

Hi Helge,

On Sun, Sep 29, 2024 at 10:02:30AM +0000, Helge Kreutzmann wrote:
> 
> Dear inetutils maintainer,

While I am not a maintainer of the GNU Inetutils project, I am involved
in its maintenance.

> the manpage-l10n project maintains a large number of translations of
> man pages both from a large variety of sources (including inetutils) 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.

I think that you are attempting to report only "conventions not held up".

> 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.

All your reported issues seem to pertain to text style, i.e., missing
"bold" font attributes, I think.

> 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: dnsdomainname.1
> Issue:    -? → B<-?>
> 
> "-?, B<--help>"

The man pages are created using the "help2man" program
<https://www.gnu.org/software/help2man/>.  help2man seems not to recognize
"-?" as an option, thus it does not add the "bold" font attribute.

I'd assume this to be a help2man issue.  I have reported it, together
with a possible fix, to bug-help2man@gnu.org.

> --
> Man page: dnsdomainname.1
> Issue:    gethostname(2), getaddrinfo(3) → B<gethostname>(2), 
> B<getaddrinfo>(3)
> 
> "gethostname(2), getaddrinfo(3)"

This seems to pertain to the "see also" section.  There seem to be
different conventions for this section.  GNU Coreutils, for example,
does not use "bold" (or any other attribute) for program names in this
section, similar to what is done in GNU Inetutils.  GNU Bash, for example,
uses "italics" instead of "bold".  GNU find uses "bold", similar to your
suggestion.  It seems to me as if there is no common convention in this
case.  I would not like to change to your preferred style just to have
someone else report issues because their preferred style is different.

> --
> Man page: ftp.1
> Issue:    -? → B<-?>
> 
> "-?, B<--help>"

See above.

> --
> Man page: ftp.1
> Issue:    ftpd(1) → B<ftpd>(1)
> 
> "ftpd(1)"

See above.

> --
> Man page: rcp.1
> Issue:    -? → B<-?>
> 
> "-?, B<--help>"

See above.

> --
> Man page: rlogin.1
> Issue:    -? → B<-?>
> 
> "-?, B<--help>"

See above.

> --
> Man page: rlogin.1
> Issue:    rlogind(1) → B<rlogind>(1)
> 
> "rlogind(1)"

See above.

> --
> Man page: rsh.1
> Issue:    setsockopt(2) → B<setsockopt>(2>)
> 
> "turns on socket debugging (see setsockopt(2))"

This is similar to your "see also" section reports, but as part of the
option description generated by help2man.  If one would want to change
this, one would preferably adjust help2man, I'd think.  But then, again,
there seem to be different conventions.

> --
> Man page: rsh.1
> Issue:    -? → B<-?>
> 
> "-?, B<--help>"

See above.

> --
> Man page: rsh.1
> Issue:    rshd(1) → B<rshd>(1)
> 
> "rshd(1)"

See above.

> --
> Man page: rsh.1
> Issue:    B<info> → B<info>(1)
> 
> "The full documentation for B<rsh> is maintained as a Texinfo manual.  If the 
> "
> "B<info> and B<rsh> programs are properly installed at your site, the command"

This text is generated by help2man.  It is similar for every man page of
GNU Inetutils.  Neither help2man nor the man page of the GNU info program
use section numbers appended to program names.  Thus GNU Inetutils seems
to already follow the current convention.

> --
> Man page: telnet.1
> Issue:    telnetd(1) → B<telnetd>(1)
> 
> "telnetd(1)"

See above.

Best regards,
Erik