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
