Re: [bug #59962] soelim(1) man page uses pic diagram--should it?

[Helge Kreutzmann]

Hello Branden,
hello Dave,
I hope switching to a much better medium for for discussion of
fundamental issues is appropriate. I think the bug itself can be
closed for now, the content below is out of scope of this bug.

First of all, thank you very much for your detailed and long reply. It
is highly appreciated.

I quoted only some parts, but this is to make this (long) e-mail more
readable. It does not mean I valuae the rest of the text less.

On Tue, May 04, 2021 at 05:08:35PM -0400, Dave wrote:
> Follow-up Comment #5, bug #59962 (project groff):
>
> [comment #4 comment #4:]
> > 1. The headings of soelim are now all lower case instead of
> > upper case (e.g. Name, Synopsis, Description instead of NAME,
> > SYNOPSIS, DESCRIPTION)
>
> The rationale for this change is documented in the release's NEWS
> <http://git.savannah.gnu.org/cgit/groff.git/tree/NEWS> file; see the item
> beginning "The an (man) and doc (mdoc) macro packages support new CS and CT
> registers..."  In short, you can preserve historical all-caps section headings
> by passing "-r CS=1" to groff.

Thanks, I'll discuss with Mario if and how we can integrate this in
our workflow.

On Tue, May 04, 2021 at 07:10:34PM -0400, G. Branden Robinson wrote:
> Follow-up Comment #6, bug #59962 (project groff):
> 
> Thanks for following up.  I apologize that this response is lengthy.  You've
> stumbled into some controversial topics.

Indeed.

> [comment #4 comment #4:]
> > 1. The headings of soelim are now all lower case instead of upper case (e.g.
> Name, Synopsis, Description instead of NAME, SYNOPSIS, DESCRIPTION)
> 
> To further elaborate on Dave's helpful comment, all of groff's man pages have
> migrated to mixed-case section and subsection headings.
> 
> (And some day I'll get them all migrated to sentence case instead of title
> case as well.)

I see three ways to look at this.

1. From an esthetical point of view
   If man pages were "ordinary" text, I agree having this all CAPS is
   ugly. In the German translation even more so, because by default it
   is supposed to be an abbreviation, we do not use (per general
   rules) all CAPS text at all. Still, in the man pages both in the
   original and the translation it is valid.

2. From readers point of view
   Both as reader as well as translator (which is a special kind of
   reader) I do not look at the entire page at once, at least usually.
   I want to navigate quickly to the point where I'm interested. Here
   all CAPS help, because they are visually striking to enable quick
   navigation. 

   I might be interested in the SYNOPSIS. I can quickly find (or
   search) it. If "synopsis" is written elsehwere, I would not find it
   (nor am I usally interested in those matches). Similarly if I look
   for OPTIONS, or FILES, or … 
   
   So efficiency in using these documents (and their every repeating
   same structure with the CAPS headings) is very helpful. It does not
   matter how which programm - if it has a man pages, it most likely
   follows man-pages(7). (Hopefully it follows man(7) at least in
   spirit, see below). And I can quickly read and navigate. 

3. From a tools POV
   Ideally, all tools would start from source. But often they don't.
   Again, having a clear structure (like CAPS headings) makes tools
   navigate in online manpages (plain HTML) or dump output generated
   much better. Maybe AI will supersede this in the future, I don't
   know.

> > 2. The markup is partially strange. Usually program names are in B<>, but
> now they are in I<>
> 
> Please excuse me--I'm not upset with you at all, but you raise an issue that
> provokes me into a rant, which I offer for the record and possible contention
> of other groff contributors.

I'm not much into groffs details myself, but I thank you for the good
explanation.

I think if I understood you correctly, the problem stems from the fact
that visual and logical markup is intertwined to the point that
visual appareance cause logical meaning. This is, by itself, of course
bad.

First, the rationale given above for the CAPS case applies. Users want
efficient man pages. So B<> and I<> are interwined with logical
meaning for the reader. (I only look for bold text, because I'm
looking through the names of options).

This can of course be changed, but this would require some kind of
coordination between all langauges for preparing man pages (groff,
perldoc, docbook, …). In manpages-l10n we have > 100 projects at the
moment, I did not do any statistics on their source language.

Secondly as stated in 3. above readers and tools might not see the
original markup language at all. For example in our case, the
translators do not see all the details of the markup language, but
often some mixed or intermediary representation. This is nice, because
it releaves the translators from knowing all markup languages
available. Po4a might not be perfect, but I think it does it's job
quite well here.

And then translators often are forced to read (inperfect) texts which
they have limited knowledge of. In contrast to ordinary users they
might not use the tool or all options and have little or limited time
(and interest) to "experiement". So I often look at the markup. Oh'
it's B<> - then this is verbatim text, i.e. the name of an option. I
must not translate this. Then I<> - this is variable, fine, I should
translate it to serve our readers. This sometimes helps immensly in
understanding and in the translation.

So translators use the visual markup as logical one. In this process I
do not care how B<> is rendered in the end (nor for I<>). Of course
readers later on would expect some consistent rendering, like in the
CAPS case to quickly understand this (imperfect) text.

In theory this should occure, in practice this is quite often the
case. I know man pages with *very* long sentences and here the markup
is one of the tools to understand this sentences. 

> The downside?  It will take many, many years for pages to migrate.  I expect
> we'll still be reading unadapted man pages when we're discovering unsigned
> 32-bit overflows in "enterprise" Linux distributions in 2038.

If there is a goal and some kind of coordination I'm fine with having
some migration period. manpages-l10n can actually help here - we
regularly feed back errors to our upstream projects. So if we know how
options names / fixed text should be marked and how variable text
should be marked, then we could approach our upstreams (on a case by
case basis) and ask them to apply this consistenly. In fact, I usually
point them to man-pages(7), at least to the major points.

So please state the "right" convention and coordinate with as many
other tools as well. Really please.

What would be horrible is that each project invents its own
conventions, both for the readers and the translators. 

> It's on my to-do list to implement this, and maybe it will be in the groff
> 1.23.0 release.  You can read more here
> <https://lists.gnu.org/archive/html/groff/2020-08/msg00068.html>.  (Note that
> my observations in that message about font styling practices have been
> modified as above per research I've done in the intervening months.)

So please coordinate and disseminate the change to as many projects as
possible and make it easy for them to switch to whatever is agreed
upoon, and do so quickly. 

> > (with an additional \\% at the beginning, but I don't complain about the
> latter).
> 
> That's the *roff hyphenation character.  At the beginning of a word it
> suppresses hyphenation.  This is approximately a 50-year old syntactical
> feature.  :)

As said, I don't speak *roff, I simply copy those codes not handled by
po4a over. In Systemd all full stops have \\&. Probably better, but I
simply do as upstream does. So no complaint from my side.

> > In a KDE konsole this looks strange (underlined instead of bold), in a VT
> visually this does not matter.
> 
> Underlining is to be expected; most terminal emulators do not support italics,
> so the TTY output driver for groff tells the terminal to use underlining
> instead.  See grotty(1) for more information.

Thanks, I simply seldomly read the man pages in anything but VT, see
below.

> I confess that I go many months without checking man page rendering in VTs. 
> But if this is something you do I am intensely interested in any readability
> problems you encounter.

No problem, I'm probably highly unusal as I actually do most work on
VTs (except those which nowadays require X, like graphics, most
browsing). So I usually read the man pages in VTs as well.

> > 3. Usually B<> is not additionally quoted, I noticed that it is now in the
> new version, e.g. \\[lq]B<...>\\[rq].
> 
> Again, this is a stylistic choice.  Bolded content sometimes becomes ambiguous
> if the bold attribute is lost or stripped away, which can happen when people
> use the man page interface clumsily (or render man pages to an extremely
> primitive device).  My rule of man page maintenance/authorship is to introduce
> quotes if such confusion is a significant risk, and not otherwise.  Two rules
> of thumb are:

I do understand your reasoning, but in the set of man pages I worked
in B<> is often by itself understood to be some kind of quoting, so
this is unusual. I myself have not experienced output methods so dump
to strip these away (bold and italics are now quite generally
available, and as you state, underline is available as an
alternative). 

For me, this looks strange, but again as translator I will faithfully
reproduce this in the translation as long as it does not contradict
German gramar heavily. Often I actually add quotes when upstream does
not use any or only little markup. (The tendency I feel is that
literal quotes become somewhat unpopular in english texts, e.g. in
systemd they were drastically reduced some time ago). 

> > 4. Regarding the picture, the toolchain of manpages-l10n still does not
> integrate it but tells me it is in a separate file. This is a little
> unfortunate, but right now I do not have the time to debug this. And the
> downside is only the missing translation. Therefore please close this bug for
> now. If I ever investigate this further, I would open (if necessary) a new
> bug.
> 
> Whew.  It took me a while to get back from all of my soap boxes to the actual
> topic. 😬
> 
> I am not sure what you mean by the picture being "in a separate file", but I
> will assume (unless you correct me) that this is an artifact of the way the
> manpages-l10n tool chain works, and not a defect in groff's soelim(1) man page
> per se.

Yes, this is somewhere tied into po4a. I just noticed that systemds
man pages "just work" with similar graphics, while groffs don't. Since
right know I do not have time to dweleve into this, I suggest that I
keep this as low priority learning project for myself and if I manage
to to this some time and actually find a bug somewhere, I will report
it, but not before. Thus I suggest to close this issue right now.

> > 5. The line graphics was changed. On my system, the arrows are displayed
> fine in a VT, but not the lines. Both display fine in a KDE konsole. Maybe you
> want to keep the previous line and just use the arrows? (But most users
> probably will use a terminal program in a graphical environment, so this
> really is very minor)
> 
> I will check this out.  I'm a bit loath to change the input because it is
> correct with respect to my present understanding.  What I think is happening
> is that the VT driver has no glyphs for the Unicode box drawing characters, so
> it doesn't render them.

Probably, and it is extrem low priority, so consider it as such. 

> Thank you for yours, and for your patience with my reply!  If you can shed
> light on any of these issues, please follow up.

I hope I did follow up approprietely. To summarize:

I think I understand the problem. I'm not against change. But please
keep the aim of the man pages and their consistency in mind, i.e. if a
transition is needed, please do your best to make it as smooth as
possible (e.g. by telling everyone including po4a and manpages-l10n
about the new right way). 

If I should/need to add anything to the actual bug, please tell me and
I will of course.

Best 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