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

[Ingo Schwarze]

Hi Branden and Alejandro,

G. Branden Robinson wrote on Tue, Oct 24, 2023 at 04:54:21AM -0500:
> 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.

That is completely true, and my point 5 is completely bogus.  This is
embarrassing, in particular since it also tainted the commit message.
I'm not completely sure how the wrong idea entered my head, possibly by
confusing .TP and .IP, which i tend to confuse regularly, even though
the mnemonics isn't actually bad (.TP is the one that can *only*
be reasonably used for lists with a tag, i.e. the one with mandatory
next-line syntax, whereas .IP is the one that can be used for any
indented paragraph, even without a tag).  Not an excuse of course,
i should have looked more closely and not jumped to wrong conclusions.

> Description
>        abra   cadabra Newport News.

Yes, that's good enough as a fallback for a few rarely used formatters.

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

That's another possible factor which might have contributed to my
massive gaffe, yes.

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

Yes, i fully agree with that.
My points 1. to 4. remain valid, but that only means .TQ should not
be used excessively.  The fact that my point 5 was bogus means
that avoiding it almost completely is not required.
Indeed, reasonable use cases seem the same as for .Bl -compact
with seletive .Pp.  The semantic downside of having a list
entry with an empty body instead of having an item header consisting
of two lines is also the same in both languages.  Then again, while
treating an empty item body as an indication for semantic formatters
that the following body has two tags is a burden on formatters, it's
probably not too heavy to bear, so inventing new syntax to avoid that
burden is likely not reasonable.

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

Well, when designing a new language from scratch, you should
always consider prior art, to reduce the risks of reinventing the
wheel, introducing new design mistakes, and leaving design gaps.
In particular, when designing a markup language for documentation, i
consider it critical to carefully compare the design to HTML, LaTeX,
and mdoc(7) before making final decisions, and there may be a few
more that might also be worth looking at for comparison.  Looking at
DocBook is likely *not* a good idea though simply because its design is
so atrocious in so many respects that you will waste massive amounts
of time without learning anything, excpt maybe what not to do.
That doesn't mean the new design must follow the existing languages,
but not even considering HTML 5 when designing a markup language
feels like straightforward negligence to me.  :-(

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

Well, *if* you really want to totally redesign the very foundations
of man(7) and change it from almost presentation-only and almost
in-line-macro only to the totally different paradigms of semantic
markup and block oriented, that is definitely one among the many task
involved in redesigning.

Yes, structural markup of a list requires saying where the list
starts, where the list ends, and where each item begins.  So that
part of the design of .LS feels right.  If i understand correctly,
the .LS macro will not accept text arguments, which is also good.
The naming seems fair, too.  I did *not* review the proposal though,
so there may be downsides that i am unaware of.  All i'm saying is
that these three points look good, and that the man(7) language indeed
has one of its major weaknesses in this area.

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

I agree that .br+.ns is not better than .TQ in a man(7) page.

The following probably wouldn't be too hard to fix:

   $ man -O tag=ns roff
     ns      Turn on no-space mode.  Currently ignored.
  [...]

The fact that mandoc(1) still ignores .ns is a (weak) indication
that the number of real-world manual pages directly using it is
likely very small.

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

To avoid muddling the waters, i tend to distinguish "semantic markup"
(when talking about markup that indicates, for example, a variable
name or stress emphasis) and "structural markup" (when talking about
markup that indicates, for example, section headings, lists, and displays).

The concepts of structural markup is closely related to the concept of
block nesting, just like the structural programming paradigm is closely
related to the concept of code block nesting.  Both became mainstream
around the same time: FORTAN 77 and C are structural languages,
FORTAN 66 is not.  (The concepts involved are of course much older.)

The link between semantic markup and block nesting is weaker,
but it can also profit a bit.

Some ("in-line") macros are purely semantic, e.g. .UR .MR .Ar .Fa .Ev
Some macros are purely structural, e.g. .SH .SS .PP .Bd -ragged .Bl -column
Some macros are both, e.g. .EX .Bd -literal .Bl -tag .Fo
Some macros are neither, e.g. .BR .IP .TP .TQ .PD .No
Some macros are neither even though they support nesting: .RS .Xo

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

Oops, right.  Groff being a GNU project and groff on the one hand and
Kerrisk + Colomar on the other hand cooperating so closely (which is
also a very reasonable thing to do) i fell into another trap here.
Sorry for that.

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

Heh.  :-/

Misinformation is never good, no matter where it comes from.

Yours,
  Ingo