bugGNU troff - Bugs: bug #59962, soelim(1) man page uses pic...

 
 

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

Submitted by:  Helge Kreutzmann <kreutzm>
Submitted on:  Thu 28 Jan 2021 04:26:56 PM UTC  
 
Category:  Preprocessor soelim Severity:  2 - Minor
Item Group:  Documentation Status:  Need Info
Privacy:  Public Assigned to:  G. Branden Robinson <gbranden>
Open/Closed:  Open Planned Release:  None

Add a New Comment (Rich Markup)
   

You are not logged in

Please log in, so followups can be emailed to you.

 

( Jump to the original submission)

Tue 04 May 2021 11:10:34 PM UTC, comment #6: 

Hi, Helge!

Thanks for following up.  I apologize that this response is lengthy.  You've stumbled into some controversial topics.

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

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

groff's use of italics here is a deliberate stylistic choice.  The Graphic Systems C/A/T for which Unix troff was written circa 1973 supported three font styles: roman, bold, and italic.  All three have been used over the years to mark up the topic part of a man page cross reference.  (Blissfully, nearly everyone agrees that the parenthesized manual section part should be in roman.)  Early Unix manuals simply set them in roman; by the time of Unix Seventh Edition (1979), the man pages were consistent about using italics (except in the "See also" section, which eschewed font changes altogether).  A look at the hier(7) page of the various historical Unix releases available at The Unix Historical Society (TUHS) <https://minnie.tuhs.org/cgi-bin/utree.pl> is illustrative.

This practice was pretty consistent up until the 1990s.  Things have gotten more chaotic since then, possibly thanks to the advent of Linux and BSD kernels running on consumer PC hardware--more specifically on terminal drivers written for the PC console.  By the time the luster wore off of VGA text modes, people had hacked "ANSI" color support onto various terminal drivers and emulators and called the results compatible with DEC VT100 terminals (when they weren't--Thomas Dickey is helpful on this <https://invisible-island.net/xterm/xterm.faq.html#what_vt220>) and generally exhibiting a lot of ignorance of ISO 6249/ECMA-48 escape sequences and of the existence of the terminfo library altogether.

These days you will find a significant number of people claiming that man page cross references should have the topic part in bold because it's "literal".  "Anything literal in man page text", they will tell you, "should be in bold, and anything variable in italics".

While more correct than the opposite, the foregoing rule is overstated and over-applied.  One of the principles of pleasant typography is that boldface should not be used to excess, and in man pages a robotic application of the above-quoted principle does indeed frequently lead to excess.

Worse, many champions of the above inflexible principle merrily boldface their man page cross references without using the \% hyphenation escape (of which they have no knowledge, but see below) at the beginning to suppress hyphenation of the topic word, so you will often end up with a hyphen and a line break in the middle of this supposedly scrupulously "literal" man page topic word.  Users who believe what the principle expounders have been peddling will be frustrated when they attempt to copy and paste such "literals".

Nevertheless some people remain violently committed to boldface topic names in man page cross references.  And while I think they're wrong and inconsistent with Unix historical practice and good typographical style, this isn't really where the problem lies.

The problem is that the man(7) macro language doesn't know what a man page cross reference is.  The insufficiency of semantic cues is one of the problems that motivated the development of the mdoc(7) macro language used by the BSDs.  Unfortunately, that language is much larger than man(7), which is already poorly used and poorly understood by many hackers, who are also frequently resistant to learning much about it as they proclaim their preference for Markdown, perldoc, or DocBook instead.

Much more importantly from the standpoint of an integrated documentation standpoint, the fact that man(7) doesn't know what a man page cross reference is means that it cannot hyperlink between man pages in spite of all the necessary ingredients being present...almost.

A solution to the debacle exists. Long story medium, with a new macro MR for man page cross references and a new string, say MF (or maybe XF), which specifies the font to be used when rendering the topic part of the cross reference, we can solve all of these problems.  (1) Man page readers, not authors, can configure whichever font they want to see for the topic in cross references.  (2) Hyphenation will be suppressed in the topic with no extra effort or learning.  (3) Semantic cross-reference information will be available in (3a) the device-independent output format, making life easier for anything that cares to process it, for instance to generate hyperlinks and (3b) the source document for the benefit of the many tools that (attempt to) parse man(7) language directly.

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.

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

> (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.  :)

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

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.

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

(1) If the bolded content contains spaces, quote the content as well; if the bold is stripped away, the reader won't be able to tell where the bolding stops.

(2) If the bolded content starts with letters or punctuation that might be parsed as part of the sentence, quote the content as well.  For example, some of the ms(7) macros take an optional argument "no" that changes their behavior.  The construction "if you give this macro a no, this heading is suppressed" is hard for a human to parse on the first reading.

Counterexamples, where I seldom if ever find supplemental quotation helpful, are sequences beginning with a backslash (which has no function in natural languages) or Unix option dashes (which are ambiguous in principle, but almost never in context, especially if one follows the style rule which holds that em dashes used to interrupt a sentence should not have any adjacent space).

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

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

This is a tricky problem for groff because it--specifically, grotty(1), the output driver for terminal devices--has no way to query the terminal device regarding its repertoire of supported glyphs or Unicode code points[1].  This isn't a matter of the necessary code not being written yet (in groff); as far as I know, there is no interface for such a thing in the Unix or Linux terminal APIs, nor in the ISO 6429/ECMA-48 control sequence scheme for passing such information.

My dim recollections of the Linux VT implementation are that (1) it was written back when ISO 8859 character sets were all that most people bothered to use (UTF-8 didn't seriously start to take wing on Linux until after 2000, thanks to folks like Markus Kuhn); (2) they were limited to 256 code points; and (3) there was some VGA hack that enabled 512 different glyphs on the screen if you disabled one of the character attributes.  I don't remember which it was, but memory of this point is one of the factors that makes me paranoid about text attributes being stripped in rendered man pages.

> So I would suggest to address 1. and 2. (and maybe 3./5.) and then close this bug.
>
> Thanks again for your work.


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

Regards,
Branden

[1] People familiar with groff may wonder about this claim given the existence of '.if c', '.fchar', and similar.  As I understand it, these work at the interface between groff language input and the output driver.  But the problem we have with VTs not drawing these line characters is that the Linux terminal driver can't tell grotty that it doesn't support them.  However, the Linux VT driver does (or did, the last time I checked, months or years ago) support the glyphs in the DEC ACS (alternate character set), which includes box-drawing characters.  It therefore seems to me that when the Linux VT driver is in UTF-8 mode and it hits one of the code points for which a DEC ACS symbol is entirely adequate, it should render that ACS symbol instead.

G. Branden Robinson <gbranden>
Project AdministratorIn charge of this item.
Tue 04 May 2021 09:08:35 PM UTC, comment #5: 

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)


Hi Helge,

The rationale for this change is documented in the release's 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.

Dave <barx>
Project Member
Sun 02 May 2021 03:13:42 PM UTC, comment #4: 

Hello Branden,
thanks for working on improving the (soelim) man pages.

I manually inserted the version from git as of this morning into our toolchain for testing purposes. As #59222 is closed, I report all I noticed while quickly reviewing the newly generated man page. Please apologize if some is an artefact due to the manual process (but I do hope there is none).

1. The headings of soelim are now all lower case instead of upper case (e.g. Name, Synopsis, Description instead of NAME, SYNOPSIS, DESCRIPTION)

2. The markup is partially strange. Usually program names are in B<>, but now they are in I<> (with an additional \\% at the beginning, but I don't complain about the latter). In a KDE konsole this looks strange (underlined instead of bold), in a VT visually this does not matter.

3. Usually B<> is not additionally quoted, I noticed that it is now in the new version, e.g. \\[lq]B<...>\\[rq].

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.

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)

So I would suggest to address 1. and 2. (and maybe 3./5.) and then close this bug.

Thanks again for your work.

Helge Kreutzmann <kreutzm>
Wed 21 Apr 2021 03:02:58 AM UTC, comment #3: 

With #59222 resolved, the only remaining issue for this ticket is the question of whether the manpages-l10n project ( https://tracker.debian.org/pkg/manpages-l10n ) has a toolchain that can cope with our conditional use of a pic diagram in the soelim(1) page.

We're still waiting to hear back from that project regarding whether they'd prefer to update their toolchain to recognize what our page is doing, or whether some fine-tuning to the page source would facilitate cooperation.

G. Branden Robinson <gbranden>
Project AdministratorIn charge of this item.
Thu 28 Jan 2021 07:17:03 PM UTC, comment #2: 

Also see bug #59222.

G. Branden Robinson <gbranden>
Project AdministratorIn charge of this item.
Thu 28 Jan 2021 06:17:22 PM UTC, comment #1: 

original submission:
Hi Helge,

Thanks for the report.

> Man page: groff.1.po
> Issue: Why B<and> but not B<7>?
>
> "I<groff> has man pages in sections B<1>,B< 5>,B<and> 7B<.>"


This was fixed on 15 September 2020.  https://git.savannah.gnu.org/cgit/groff.git/commit/?id=550ab5338e04e54539214997315f451c89ac25e6

> --
> Man page: groff.1.po
> Issue: English sentence broken (and sentence garbage: »in the same section« and »with the lowset section«)
>
> "When there are several I<man pages> with the same name in the same I<man> "
> "section, the one with the lowest section is should as first."


As above.

> --
> Man page: soelim.1
> Issue: The following graphs cannot be processed by po4a. To ease translation, please render this directly, avoiding pic.tmac. See bootup(7) for an example
>
> "The normal processing sequence of groff is this:"


Hmmm, it may be desirable to enhance your toolchain, or possibly to special-case your project's handling of GNU soelim, since its usage of the pic preprocessor in a man page document is, to the best of my knowledge, rare.  (However, your project likely has access to better raw data on this issue than I do.)

What I believe should excuse soelim(1) from complaint is that it only uses pic if the formatter is in "troff mode"--this is the "t" conditional in troff.  In soelim(1) we have in-page logic that boils down to this:

.if t
.PS
.\" pic diagram
.PE
.el
.\" ASCII art alternative

On further consideration, the quoted strings in the pic document are also legitimate strings for localization, so again this may boil down to a toolchain issue, because these should be easy to match.  (The fixed sizes of the geometric objects surrounding the text could prove troublesome, admittedly.  Possibly some sufficiently clever pic-writing could overcome this by measuring the strings and sizing the objects to fit them.)

In my view, having a fallback/alternative for nroff devices is not only the right thing to do for accessibility purposes, but it should be showing up as localizable text.

Can you share any insight on these matters?

> --
> Man page: soelim.1
> Issue: missing whitespace
>
> "B<-I>I<dir>"


This was fixed on 8 October 2020.  https://git.savannah.gnu.org/cgit/groff.git/commit/?id=7eca9c3c6d0efdbb29dcedad51d18d4c4993a22a

The issues already fixed are expected in the groff 1.23.0 release, and the release candidate available at https://alpha.gnu.org/gnu/groff/ already reflects them.

G. Branden Robinson <gbranden>
Project AdministratorIn charge of this item.
Thu 28 Jan 2021 04:26:56 PM UTC, original submission:  

Dear Groff maintainer,
the manpage-l10n project maintains a large number of translations of
man pages both from a large variety of sources (including Groff) 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: groff.1.po
Issue: Why B<and> but not B<7>?

"I<groff> has man pages in sections B<1>,B< 5>,B<and> 7B<.>"
--
Man page: groff.1.po
Issue: English sentence broken (and sentence garbage: »in the same section« and »with the lowset section«)

"When there are several I<man pages> with the same name in the same I<man> "
"section, the one with the lowest section is should as first."
--
Man page: soelim.1
Issue: The following graphs cannot be processed by po4a. To ease translation, please render this directly, avoiding pic.tmac. See bootup(7) for an example

"The normal processing sequence of groff is this:"
--
Man page: soelim.1
Issue: missing whitespace

"B<-I>I<dir>"

Helge Kreutzmann <kreutzm>

 

(Note: upload size limit is set to 16384 kB, after insertion of the required escape characters.)

Attach Files:
   
   
Comment:
   

No files currently attached

 

Depends on the following items: None found

Items that depend on this one: None found

 

Carbon-Copy List
  • -email is unavailable- added by barx (Posted a comment)
  • -email is unavailable- added by gbranden (Posted a comment)
  • -email is unavailable- added by kreutzm (Submitted the item)
  •  

    Do you think this task is very important?
    If so, you can add your encouragement to it.
    This task has 0 encouragements so far.

    Only logged-in users can vote.

     

     

     

    Follow 5 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2021-04-21 gbranden CategoryNone => Preprocessor soelim
        SummaryIssues in Groff man pages => soelim(1) man page uses pic diagram--should it?
    2021-01-28 gbranden Severity3 - Normal => 2 - Minor
        StatusNone => Need Info
        Assigned toNone => gbranden

    Back to the top


    Powered by Savane 3.7