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

[Ingo Schwarze]

Hi Alejandro,

Alejandro Colomar wrote on Mon, Oct 23, 2023 at 04:30:58PM +0200:

> This got me curious about TQ, since mandoc(1) considers it "very rarely
> used, even in GNU pages".
> 
> Ingo, you may want to reword that, since TQ was being used in the Linux
> man-pages project,

Done, thanks for the heads up.
I append the resulting commit below.

> and yesterday I wrote a patch to use it even more:
> <https://www.alejandro-colomar.es/src/alx/linux/man-pages/man-pages.git/commit/?id=0962e38105076fffc6dae174a9026917c6a3941d>

Strange, i pulled from
  https://git.kernel.org/pub/scm/docs/man-pages/man-pages
and don't see such changes there, so i'm just judging from
code inspection right now, without looking at formatted versions.

I think that is a really bad patch.

 1. It gratuitiously makes the description of almost every option
    longer by a whole line, which is a significant waste of screen
    real estate.  It's further aggravating that due to long options,
    most Linux manual pages already have an extra line for the
    options at the start of each paragraph.  Now you are
    doubling that from one to two wasted lines per option
    compared to the same functionality on BSD.  The situation
    becomes even more dire because Linux already tends to have
    many low-utility options compared to BSDs, so you keep driving
    density of useful information down and verbosity and fluff up.

 2. Your argument that this helps searching is a red herring.
    The weakness of man(7) in searching has nothing to do with
    the *formatting* of list item heads, it is caused by the
    lack of *semantic markup*.  There would be no problem creating
    search anchors for multiple .Fl topics on the same output line
    in mdoc(7).  The only reason i did not do it is because it
    is irrelevant for us since we barely have any of those
    POSIX-violating long options.

 3. Seperating two synonymous .Fl entries onto different .TP/.TQ
    lines weakens semantic expressiveness further.  Even though
    mandoc already contains special guessing logic in the HTML
    formatter to treat .TQ and following .TP as part of the same
    list, other formatters and other output modes may be less smart.
    I mean, those are not even the same macros, and yet you hope
    for them to be rcognized as entries in the same list?

 4. Even the best HTML markup that is so far feasible results
    in *two* list entries, one with an empty body and and only the
    second one with the corresponding content.  While that may or may
    not look superficially right (depending on the CSS), it certainly
    isn't semantically correct and is likely to cause accessibility
    grief, for example for blind people.
    So, you want HTML formatters (and formatters to other output
    languages that support semantic markup) to combine .TQ and
    subsequent .TP not only into the same list, but also into the same
    list element - but only if the body of the .TQ is empty, i guess?
    So you want different macros to behave identically in some
    ways (.TQ and .TP part of the same list) but the same macro
    fundamentally different depending on its content.  The same
    macro sometimes gets its own element and sometimes needs to
    fuse into a different macro.
    So much fun for implementers of formatting modules!

 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.

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

Either way, that sentence in our manual page clearly is no longer
true even without that particular patch, so it's gone now.

> TQ seems to be a sibling of TP.  Not sure if this will affect this
> -Thtml bug in some way; my experiments seem good, but they weren't
> exhaustive.

Yes, i believe mandoc -T html is already able to more or less
cope with typical use cases of .TQ.  It seems likely though that
you can construct less typical use cases that render badly to HTML
(or any other semantical markup language for that matter).  You can
be virtually certain that HTML output from any non-mandoc formatter
will be atrocious right now, and any future output to any semantical
markup language will almost certainly be bad initially unless whoever
implements that future output mode in whichever program closely looks
at mandoc code first and is aware that man(7) formatting requires
intelligent and complicated guessing and cannot be done in any way
that is based on any context-independent grammar.

Yours,
  Ingo


Log Message:
-----------
Remove the statement that .TQ was "rarely used even in GNU manual pages".

It appears the Linux Manual Pages project started to quite aggressively
use .TQ ever for cases where it not only provides no value, but makes
formatting worse even when it formats as intended.  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.

But whether this is wise or stupid is their problem and none of our
business.  Either way, we should not call a thing "rarely used"
after that is no longer true.

Thanks to Alejandro Colomar <alx at kernel org org>
for making me aware that the statement is no longer true.

Modified Files:
--------------
    mandoc:
        man.7

Revision Data
-------------
Index: man.7
===================================================================
RCS file: /home/cvs/mandoc/mandoc/man.7,v
retrieving revision 1.149
retrieving revision 1.150
diff -Lman.7 -Lman.7 -u -p -r1.149 -r1.150
--- man.7
+++ man.7
@@ -440,7 +440,7 @@ unspecified, the saved or default width 
 Like
 .Ic TP ,
 except that no vertical spacing is inserted before the paragraph.
-This is a GNU extension and rarely used even in GNU manual pages.
+This is a GNU extension.
 .It Ic UC
 Sets the volume for the footer for compatibility with man pages from
 .Bx