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: Thomas Dickey
Subject: Re: Errors in ncurses man pages
Date: Fri, 24 Dec 2021 15:51:01 -0500
User-agent: Mutt/1.10.1 (2018-07-13)

On Thu, Dec 23, 2021 at 10:48:00AM +0100, Helge Kreutzmann wrote:
> 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.

thanks - I'll try to address the issues which you reported.
 
> 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.

I miss things too :-)

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

Attachment: signature.asc
Description: PGP signature


reply via email to

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