Re: Errors in ncurses man pages

[Thomas Dickey]

On Thu, Dec 23, 2021 at 09:40:18AM +0100, Helge Kreutzmann wrote:
> 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.

actually, "error" appears 3 times (counting the subject line), and "issue" 5.
 
> If you are deliberately not following this practice then I notice this
> and will try to avoid this in future bug reports. 

It's not deliberate, but a matter of where the time/effort is spent.
Besides xterm (mentioned in several manpages without a linkage, I see...)
there are several other topics that could have manpage-links.  Finding
those automatically seems like a lot of work, but having a (short!) list
of topics to link would be a suggestion for improvement.

For instance, most of the manpage-links are in see-also sections,
with some done inline as well (for the linkages within ncurses).

The script which constructs the webpage relies upon consistent markup to
recognize the links (and I made a script to report inconsistent bold vs
italics), so I've been fairly consistent about the use of bold versus
italics where a manpage link is intended.

But remembering to mark (or not) each term that might have a manpage
link isn't as easy to script.  In a quick count, there are 20984 lines,
115,981 "words" in the manpages, with 1230 lines having a manpage-link. 
Only 21 lines are for section-1 links.  If I indexed all of the words
to make a list of candidates, that would be work, and without going in
that route, I'll get occasional reports that it would be nice to link
certain terms.
 
> (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.)

probably - but I see some examples on the system where I'm working
(xsel.1x, xzoom.1x)

-- 
Thomas E. Dickey <dickey@invisible-island.net>
https://invisible-island.net
ftp://ftp.invisible-island.net

signature.asc
Description: PGP signature