bug-ncurses
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: Errors in ncurses man pages


From: Helge Kreutzmann
Subject: Re: Errors in ncurses man pages
Date: Thu, 23 Dec 2021 10:48:00 +0100
User-agent: Mutt/1.10.1 (2018-07-13)

Hello Thomas,
On Thu, Dec 23, 2021 at 04:22:14AM -0500, Thomas Dickey wrote:
> On Thu, Dec 23, 2021 at 09:40:18AM +0100, Helge Kreutzmann wrote:
> > 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.

Then take my apologies, when I phrased that text I did not put it on
the gold weight, the intent is "issues".

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

Please understand this report (and possible future ones) as a
courtesy. If you agree with the points raised (which could also be
regarding the content), then include them, if not, then discard them.

Translators tend to read the man pages very carefully (and they read
it completely), so they are able to notice quite a few "issues". What
I found sad was that in the past many issues were corrected in the
translation but the authors of the upstream text was not made aware of
them. Therefor I encourage our translators (of manpages-l10n) to mark
possible issues and I'll report them asynchonly.

If I learn that upstream disagrees with certain issues (which is
perfectly fine), then I mark those locally as "WONTFIX" and try to
avoid reporting issues like these in the future. This is what I did for
linking/markup issues for ncurses now.

One thing I'd like to point out, however:
We are very few people tracking over > 100 upstream sources, and thus
I might occasionally miss something.

That said, I do not know if (and if so, when) further ncurses man
pages are translated and if (and if so, when) further issues might be
found and reported, we'll see.

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/

Attachment: signature.asc
Description: PGP signature


reply via email to

[Prev in Thread] Current Thread [Next in Thread]