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

 
 

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

Submitter:  Helge Kreutzmann <kreutzm>
Submitted:  Thu 28 Jan 2021 04:26:56 PM UTC
   
 
Category:  Preprocessor soelim Severity:  2 - Minor
Item Group:  Documentation Status:  Invalid
Privacy:  Public Assigned to:  gbranden
Open/Closed:  Closed Planned Release:  None
* Mandatory Fields

Add a New Comment Rich Markup
   

Jump to the original submission

Sat 02 Mar 2024 10:47:46 PM UTC, comment #15: 

comment #6:

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


Bug #65403 requests that this point be documented more clearly.

Dave <barx>
Group Member
Sun 21 Jan 2024 08:21:01 PM UTC, comment #14: 

comment #12:

> I reported the originating issue to po4a (Debian bug #1061234),


That's http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=1061234 in clickable form (or rather, a form that takes you to the right place when you click it; savannah turns the above into an invalid savannah link).

Dave <barx>
Group Member
Sun 21 Jan 2024 04:54:35 PM UTC, comment #13: 


comment #12:

> Hello all,
> first, I reported the originating issue to po4a (Debian bug #1061234), so this is really no longer any issue in roff. So I think this ticket can be resolved.


Okay.  Resolving as "Invalid" since the issue didn't end up applying to groff.

> secondly, thanks for all the additional feedback, especially the accessibility issue I can understand.


Glad to be of help.
 

> Finally, echo $TERM says
> linux


So am I.

On my virtual consoles, which use the Latin-9 character set, I don't get ACS characters at all (not a surprise, grotty(1) doesn't know how to produce them...yet).  I assume you're using some sort of UTF-8-enhanced terminal.

That's going to be a problem; you and I are going to need to use different terminal types, and getty(8) or logind(8) is going to have to set $TERM appropriately for the driver managing the VT.

This may be tough to resolve; historically, the big firms that dominate Linux kernel development have shown scant interest in supporting bug fixes or development of the Linux VT environment beyond, I suppose, whatever is the minimum necessary to support an on-call admin remotely accessing machines hosted in a data center to reconfigure containerized network services.

The bug-ncurses list may be a good next stop for troubleshooting the issue you're having.

G. Branden Robinson <gbranden>
Group administrator
Sun 21 Jan 2024 09:00:49 AM UTC, comment #12: 

Hello all,
first, I reported the originating issue to po4a (Debian bug #1061234), so this is really no longer any issue in roff. So I think this ticket can be resolved.

secondly, thanks for all the additional feedback, especially the accessibility issue I can understand.

Finally, echo $TERM says
linux

Helge Kreutzmann <kreutzm>
Mon 15 Jan 2024 02:02:13 PM UTC, comment #11: 

Thanks to Dave for covering some of these points.  That may help make my reply shorter (but don't count on it 😅).

comment #8:

> I think we discussed this already, I sill think this is not correct, but it does not make sense to discuss this further


I would just point out (as I learned from Ingo Schwarze) that mixed-case section and subsection headings are better for accessibility purposes.  Apparently, screen readers pronounce sequences of capitals letter-by-letter, not as words.
 

> #2
> Thanks for the explanation.
> a) consistency is key (and also for tools processing the man pages), so for me youngster (I only started Linux/Unix mid 90s) putting references in bold is all I know, hence I ask to make it consistent when I see a deviation.
>
> And at least some tools (external to roff) "know" these rules and hyperlink (e.g. in HTML) B<foo>(x).
>
> The new macro is a great idea and I agree that it will be picked up properly very slowly. Is it a GNU extension and which minimum requirement is attached to it? It would be great if there is a web page explaining the use of this (and the minimum requirements as well) so I could point people to this. I expect people to tell me "my software runs on xyz" so I cannot use it or "I support this old Linux distribution(s)".


As Dave said, plan9port and groff 1.23.0, released in July, support it.  Likely the next release of mandoc will.

Here's what groff_man(7) says nowadays:


     .MR topic manual‐section [trailing‐text]
            (since groff 1.23) Set a man page cross reference as
            “topic(manual‐section)”.  If trailing‐text (typically
            punctuation) is specified, it follows the closing
            parenthesis without intervening space.  Hyphenation is
            disabled while the cross reference is set.  topic is set in
            the font specified by the MF string.  The cross reference
            hyperlinks to a URI of the form “man:topic(manual‐section)”.

 

> And yes, the probably best thing would be to request all those markup languages with converters into *roff to use this macro during conversion, this would probably speed up the conversion quite a bit.


I don't expect any converters to start taking it up until some readers of man pages see the macro in the wild and wonder why their converters aren't producing it.  And it is probably easier for the users of such converters to convince their maintainers to adopt the new macro than for me to approach them singing the praises of my own invention.  (I use the term "invention" with some reluctance.  Ingo says that `MR` "copies" mdoc(7)'s `Xr`, but as far as I can tell, both have a common ancestor [or at least an analogue] in the `MS` macro of DEC Ultrix man(7), which groff has documented for decades.)

>  To be honest, I know very little about *roff myself, so if I were to write a man page, I would use some higher level tool myself, in the distant past I used SGML.


In my opinion it is not difficult, and I have spent many hours revising groff_man(7) and groff_man_style(7) trying to make the subject approachable.

> b) The "bold is literal and italic is variable" is very helpful to me both as reader and as a translator.


I'm glad to hear it.  It's a good rule of thumb, but please don't over-apply this principle.

As groff_man_style(7) says:


            Use bold for literal portions of syntax synopses, for
            command‐line options in running text, and for literals that
            are major topics of the subject under discussion; for
            example, this page uses bold for macro, string, and register
            names.  In an .EX/.EE example of interactive I/O (such as a
            shell session), set only user input in bold.
[...]
            Use italics for file and path names, for environment
            variables, for C data types, for enumeration or preprocessor
            constants in C, for variant (user‐replaceable) portions of
            syntax synopses, for the first occurrence (only) of a
            technical concept being introduced, for names of journals
            and of literary works longer than an article, and anywhere a
            parameter requiring replacement by the user is encountered.
            An exception involves variant text in a context already
            typeset in italics, such as file or path names with
            replaceable components; in such cases, follow the convention
            of mathematical typography: set the file or path name in
            italics as usual but use roman for the variant part (see .IR
            and .RI below), and italics again in running roman text when
            referring to the variant material.
[...]
     Observe what is not prescribed for setting in bold or italics
     above: elements of “synopsis language” such as ellipses and
     brackets around options; proper names and adjectives; titles of
     anything other than major works of literature; identifiers for
     standards documents or technical reports such as CSTR #54,
     RFC 1918, Unicode 13.0, or POSIX.1‐2017; acronyms; and occurrences
     after the first of a technical term.

     Be frugal with italics for emphasis, and particularly with bold.
     Article titles and brief runs of literal text, such as references
     to individual characters or short strings, including section and
     subsection headings of man pages, are suitable objects for
     quotation; see the \(lq, \(rq, \(oq, and \(cq escape sequences in
     subsection “Portability” below.


> Sometimes the text is very hard to read, and having an indication what is the actual variable really helps, especially if I have little knowledge of the topic. And in many man pages this is done, so consistency is key again.


Agreed.
 

> Ideally we had semantic markup, hard coding "bold", "italic" etc. so semantics is not nice.


I agree.  I have an idea for further reforming man(7) along these lines.

(Full disclosure: in the year since I posted that, I have come to think that it would be better to make the "tag" macro an enclosing pair.  This (1) more closely resembles the block-structured nature of HTML and other modern formatting/markup systems and (2) safely leaves the macros ignorable by systems that don't know about (or reject) them, preserving the textual content of the page.

As a straw-man example just to make this concrete...


.DC filename I \" set anything with tag "filename" in font I (italics)
Blah blah blah then open the file
.HS filename
.I /etc/passwd
.HE
to see the list of users with accounts on your system
(assuming you're not using LDAP or something like that).


(groff man's font macros would need to be updated to suppress their own changes of font to honor that imposed by the "tag class", when one applies.  There is the question of what to do about trailing punctuation (not necessarily punctuation--it could be anything), as with calls like ".IR /etc/passwd ."  This will require some thought.  And re-implementing mdoc is an anti-goal.)

> #5
> The current state in my VT is that the arrows work (jay!), the only have a box before/above which is rendered as straight line in an xterm (vertically or horizontally). So from my point this is very, very minor and not a problem of *roff.


It sounds like the VT font is missing mappings for the ACS "HLINE" and "VLINE" symbols.  This should be fixable with an update to the "acsc" terminfo capability code for your terminal type.  It can be made to fall back to ASCII characters for those specific characters.  Further, you can supply your own terminfo definition for your terminal type in $HOME, and not have to alter any packages supplied by your distributor.

What terminal type are you using?  In other words, what does "echo $TERM" say on your Linux VT?

> And as usual, thanks for your very helpful and extensive explanations.


My pleasure.  If I leave anything vague--or if I am incorrect!--please raise the point and I will attempt to remedy it.

This has been quite the discussion.  What remains for resolution of this ticket?

Regards,
Branden

G. Branden Robinson <gbranden>
Group administrator
Mon 15 Jan 2024 03:45:49 AM UTC, comment #10: 

comment #8:

> You are probably right. Po4a emits:
> po4a::man: This page includes another file with '.mso'. Do not forget to translate this file ('pic.tmac').
> But this "other file" ('pic.tmac') does not appear.


Ah, pointing to .mso is very helpful!  This line in soelim.1.man loads the definitions for the macros .PS and .PE (and a couple others that soelim.1.man doesn't use).  They are in the file tmac/pic.tmac, which is shipped as part of groff (http://git.savannah.gnu.org/cgit/groff.git/tree/tmac/pic.tmac).  The good news is that this file produces no output itself, so there is nothing in it that needs translation.

> The current situation is that the graphics are not translated.


The graphics are encoded within the file soelim.1.man itself, in two segments between the macros .PS and .PE.  Is po4a stripping out these segments?  If so, this is a separate issue from the diagnostic about the .mso line: .PS and .PE should be recognized as start and end macros for pic segments even in the absence of pic.tmac being included.

Dave <barx>
Group Member
Mon 15 Jan 2024 01:23:22 AM UTC, comment #9: 

comment #8:

> The new macro is a great idea and I agree that it will be
> picked up properly very slowly. Is it a GNU extension and
> which minimum requirement is attached to it?


The .MR man macro originated as an extension in Plan 9 troff in 2020, which GNU troff then also adopted.  In the time since Branden wrote comment #6, groff 1.23 has been released, so this macro is now officially available.

> It would be great if there is a web page explaining the use of this
> (and the minimum requirements as well) so I could point people to this.


I'm not aware of such a page.  The groff 1.23 release notes (http://lists.gnu.org/r/info-gnu/2023-07/msg00001.html) cover the syntax of .MR, but this information is buried in the middle of a very long document describing a release with a huge number of changes.  And the macro is of course documented in the groff_man(7) man page included with the 1.23 groff release; this is probably the most definitive place to point people.

Dave <barx>
Group Member
Sun 14 Jan 2024 08:02:46 AM UTC, comment #8: 

Hello Dave,
sorry for having missed Brandens reply (and thus the delay in responding).

#1
I think we discussed this already, I sill think this is not correct, but it does not make sense to discuss this further

#2
Thanks for the explanation.
a) consistency is key (and also for tools processing the man pages), so for me youngster (I only started Linux/Unix mid 90s) putting references in bold is all I know, hence I ask to make it consistent when I see a deviation.

And at least some tools (external to roff) "know" these rules and hyperlink (e.g. in HTML) B<foo>(x).

The new macro is a great idea and I agree that it will be picked up properly very slowly. Is it a GNU extension and which minimum requirement is attached to it? It would be great if there is a web page explaining the use of this (and the minimum requirements as well) so I could point people to this. I expect people to tell me "my software runs on xyz" so I cannot use it or "I support this old Linux distribution(s)".

And yes, the probably best thing would be to request all those markup languages with converters into *roff to use this macro during conversion, this would probably speed up the conversion quite a bit. To be honest, I know very little about *roff myself, so if I were to write a man page, I would use some higher level tool myself, in the distant past I used SGML.

b) The "bold is literal and italic is variable" is very helpful to me both as reader and as a translator. Sometimes the text is very hard to read, and having an indication what is the actual variable really helps, especially if I have little knowledge of the topic. And in many man pages this is done, so consistency is key again.

Ideally we had semantic markup, hard coding "bold", "italic" etc. so semantics is not nice.

And thanks for explaining the rationale and meaning of \%.

c) Yes, I almost exclusively read man pages in the (Linux) console, very seldom in an xterm or somewhere else.

#3
Your rationale seems sensible. As a translator, I usually simply follow suite.

#4
You are probably right. Po4a emits:
po4a::man: This page includes another file with '.mso'. Do not forget to translate this file ('pic.tmac').
But this "other file" ('pic.tmac') does not appear. I remember we made some experiments back then to solve this, but it broke more than it helped.
The current situation is that the graphics are not translated.
In conclusion: Not a bug in *roff, but in po4a and I understand if requesting a "workaround" in *roff is completely inapproriate. Therefor, as stated below, this does not warrant keeping this issue open.

#5
The current state in my VT is that the arrows work (jay!), the only have a box before/above which is rendered as straight line in an xterm (vertically or horizontally). So from my point this is very, very minor and not a problem of *roff.

And as usual, thanks for your very helpful and extensive explanations.

           Helge

Helge Kreutzmann <kreutzm>
Tue 09 Jan 2024 08:48:20 PM UTC, comment #7: 

Helge, do you have any response to comment #6 here?

In particular, it's still unclear what the "separate file" is that you reference in item 4 of comment #4, or whether this is something that warrants keeping this bug open, since that comment also stated that item 4 could be disregarded.

Dave <barx>
Group Member
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>
Group administrator
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>
Group 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>
Group administrator
Thu 28 Jan 2021 07:17:03 PM UTC, comment #2: 

Also see bug #59222.

G. Branden Robinson <gbranden>
Group administrator
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>
Group administrator
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)
  •  

    There are 0 votes so far. Votes easily highlight which items people would like to see resolved in priority, independently of the priority of the item set by tracker managers.

    Only logged-in users can vote.

     

    Follow 7 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2024-01-21 gbranden StatusNeed Info Invalid
        Open/ClosedOpen Closed
    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.13-4448.
    Corresponding source code