Re: Errors in ncurses man pages

[Helge Kreutzmann]

Hello Thomas,
On Thu, Dec 23, 2021 at 03:34:10AM -0500, Thomas Dickey wrote:
> On Thu, Dec 23, 2021 at 08:43:42AM +0100, Helge Kreutzmann wrote:
> > On Wed, Dec 22, 2021 at 04:15:52PM -0500, Thomas Dickey wrote:
> > > ----- Original Message -----
> > > | From: "Helge Kreutzmann" <debian@helgefjell.de>
> > > | To: "Ncurses Mailing List" <bug-ncurses@gnu.org>
> > > | Sent: Wednesday, December 22, 2021 4:50:41 AM
> > > | Subject: Errors in ncurses man pages
> > > 
> > > | Dear ncurses maintainer,
> > > | the manpage-l10n project maintains a large number of translations of
> > > | man pages both from a large variety of sources (including ncurses) 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: clear.1
> > > | Issue: xterm → B<xterm>(1)
> > > | 
> > > | "In June 1999, xterm provided an extension to the standard control 
> > > sequence "
> > > | "for clearing the screen.  Rather than clearing just the visible part 
> > > of the "
> > > | "screen using"
> > > 
> > > You left something out.  See formatted page
> > > 
> > > https://invisible-island.net/ncurses/man/clear.1.html
> > 
> > The paragraph on this web page is also missing the markup, so I'm not
> > sure what exactly I "left out". Of course, I did not cite the entire
> > man page, only the relevant paragraph.
> 
> Perhaps you're referring to the fact that there's no section-number given,
> which that markup could render as a hyperlink to a relevant manpage.
> I wouldn't refer to that as an error report, but a suggestion for improvement.
> 
> Almost all of the linkages in ncurses' manpages are within the set of
> manpages since among other reasons, the section-number is known.  For
> instance, xterm might be in "1" or "1x" or "x" depending on the system
> where it is installed -- with some effort I might find examples of those.

It is customary to refer to other manpages in bold font and with the
section number given. Hence our translators notice when this is not
the case and flag this issue.

I deliberately used the word "issue" in my e-mail and avoided the term
"error". I'm not a native speaker, but I intended to express that this
is not necessarily "wrong" but could also indicate a deviation from
common practices.

If you are deliberately not following this practice then I notice this
and will try to avoid this in future bug reports. 

(My personal (however, Linux only in the last 15 years) experience is
that in most times the "x" variants of man page sections is on the
decline. But I might be wrong on this.)

Greetings

          Helge



-- 
      Dr. Helge Kreutzmann                     debian@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
Description: PGP signature