Re: mandoc -man -Thtml bug: inconsistent vertical space before .TP

[G. Branden Robinson]

Hi Ingo,

At 2023-10-24T02:13:34+0200, Ingo Schwarze wrote:
>  5. On top of all that, i have a hard time to think of any macro
>     that has a more wicked failure mode than .TQ in case the
>     formatter does not support it.  The output visually looks
>     perfectly fine, and the reader gets no hint that the *most
>     important* information is missing.

I think you're getting carried away here.  `TQ` _takes no arguments_, so
if a formatter completely ignores it, no text goes missing.

       .TQ    Set an additional tag for a paragraph tagged with .TP.  An
              input trap is planted as with .TP.

              .TQ is a GNU extension supported by Heirloom Doctools
              troff and mandoc (since 1.14.5) but not by Documenter’s
              Workbench, Plan 9, or Solaris troffs.  See subsection “Use
              of extensions” in groff_man_style(7) for suggestions.

[That's groff_man(7) from Git HEAD.]

Observe:
$ cat ATTIC/abracadabra.man
.TH foo 1 2023-10-24 "groff test suite"
.SH Name
foo \- frobnicate a bar
.rm TQ \" Die, foul extension!!
.SH Description
.TP
abra
.TQ
cadabra
Newport News.
$ nroff -man ATTIC/abracadabra.man
foo(1)                      General Commands Manual                     foo(1)

Name
       foo - frobnicate a bar

Description
       abra   cadabra Newport News.

groff test suite                  2023‐10‐24                            foo(1)
$ mandoc ATTIC/abracadabra.man | ul
foo(1)                      General Commands Manual                     foo(1)

Name
       foo - frobnicate a bar

Description
       abra
       cadabra
              Newport News.

groff test suite                  2023-10-24                            foo(1)

So, violence is done to the formatting, and it's a violence I dislike,
_but no text is missing from the rendered page_.  And, happily, mandoc
doesn't participate in such violence even when prodded to do so.

The only man(7) formatters that will be adversely affected are those
Kernighan troff descendants listed above--so, System V Unix, DWB, and
Plan 9 troffs.  That's a pretty marginal collection.  (P9US is FLOSS, so
something can be done about that one, even.[1])

I think you may have mixed in your own fulminations against the new `MR`
macro (whose presence in groff is my doing) with your apprehension about
`TQ`, which predates my participation in groff development by several
years.

I'm a bit dubious of `TQ` myself, but it does fulfill, partially, a need
that mdoc(7) meets with `.Bl -compact`.

If we were to add my proposed list macros, LS/LE to man(7), we could
de-document `TQ`, as it would be redundant with stacked, bodyless `TP`s
inside `LS`/`LE` brackets.

https://lists.gnu.org/archive/html/groff/2022-12/msg00075.html

I haven't explicitly made the connection to HTML before, but it's pretty
easy to imagine this mapping.

LS -> <UL>
TP -> <LI> ... </LI>
LE -> </UL>

Is that a tradeoff you'd be willing to make?

> Actually, part of the reason why i initially added that additional
> warning about .TQ was that i felt uneasy about it: less portable than
> for example .EX, less important than for example .UR, no semantic
> benefit, purely presentational intent, ad hoc house of cards on the
> foundation of .TP, which is already shaky enough in its own right,

> and a terrible failure mode.

...a _cosmetic_ failure mode.  No text is lost.

> So at that time in the past, i was quite happy to get the impression
> that it was rarely used and stressed that in the documentation, hoping
> people would behave reasonably and only use it in exceptionally dire
> cases where really nothing else could possibly help.

They could always have done what `TQ` itself does:

.br
.ns

and then

.TP
again as usual.

But that's two low-level requests instead of zero, and one of those
might take some explaining since it exercises a formatter feature that
only relatively advanced *roff users ever fool with.  As the maintainer
of groff_man_style(7), I do _not_ want to explain "no-space mode" to man
page authors, many of whom suggest that they could never confuse the `=`
and `==` operators in C--they're bad-ass coders, yo--but struggle
mightily to distinguish hyphens from minus signs when composing English.
Nope nope nope.

The "semantic lift" that `TQ` attempts to achieve here is, I think, an
improvement on use of `br` and `ns`, even if it imparts no semantic
content per se, but rather works around the entangled formatting
consequences of the `TP` macro that does.  I have an idea for getting
more semantic mileage out of that, too.

https://lists.gnu.org/archive/html/groff/2022-12/msg00075.html (again)

> Remove the statement that .TQ was "rarely used even in GNU manual
> pages".

Some Linux kernel hackers and other, ehrm, "stakeholders" might take
exception to your implication that the Linux man-pages endeavor is a GNU
project; it is not.  (It _does_ document a great deal of the GNU C
library nevertheless; this is the product of Info champion Richard
Stallman's immovable object meeting experienced Unix and GNU/Linux
developers' irresistible force demanding man pages.)

But that's just a nit about the commit message.  It's well down the list
of wrong things OpenBSD developers have said about GNU.  ;-)

> It's also a bad idea to use it that aggressively because .TQ has
> particularly catastrophic formatting behaviour on formatters (other
> than groff and mandoc) that do not support it: It essentially has the
> effect of omitting the topic of the discussion from the formatted
> version of the manual page, but in such a way that it does not become
> apparent to the reader that anything is missing.

This is false, as I demonstrated above.  And to my mind, this is a more
injurious misstatement than situating the Linux man-pages under the GNU
umbrella.

Regards,
Branden

[1] Technically DWB 3.3 is now, too, but as far as I know its only
    utility relative any other troff is for people like me to get some
    idea of how a System V troff would behave without paying for or
    begging access to an AIX or HP-UX host.  So I like it the way it
    is, frozen in amber except for C code cleanliness issues.

signature.asc
Description: PGP signature