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

[Alejandro Colomar]

Hi Branden,

On Mon, Oct 23, 2023 at 04:15:23AM -0500, G. Branden Robinson wrote:
> [dropped tech@mandoc.bsd.lv from Cc; I'm not subscribed, so it
> deep-sixes my mails]

[Added groff@, to have some mailing list]

> 
> At 2023-10-19T23:32:42+0200, Alejandro Colomar wrote:
> > > >         $ cat nested_indent.man 
> > > >         .TH nested_indent 7 2023-10-19 experiments
> > > >         .SH Ingo said:
> > > >         .TP
> > > >         Todo
> > > >         Currently, when formatting .TP or .IP with a non-empty head,
> > > >         [yada yada]
> > > >         .RS
> > > >         .PP
> > > >         When formatting .IP or .RS with an empty head, mandoc needs
> > > >         [yada yada]
> > > >         .RE
> > > > 
> > > > As you can see, here the indentation is controlled by a single
> > > > RS/RE pair, and everything within it uses PP as a normal paragraph
> > > > separator.
> > > 
> > > While that also generates correct terminal and typographical (PS,
> > > PDF) output in the same purely presentational sense as .TP .IP .TP,
> > > it does not help with respect to the semantic problem we are
> > > discussing here.
> 
> My approach when requiring indentation "under" a tagged paragraph has
> been to use `RS`/`RE` twice; once to align _normal_ paragraph
> inset with the tagged one's indentation, and once to inset relative to
> the tagged paragraph.  Understanding this matter was one of the factors
> that drew me into groff and man(7) development.[1]
> 
> > > You see that the first .TP, the .RS, and the second .TP are all
> > > child nodes of the top-level .SH.  The .RS is not a child of the .TP
> > > but a sibling.  The two .TP nodes still aren't siblings of each
> > > other.
> 
> This is a reasonable interpretation, and consistent with how we present
> RS/RE in groff_man(7)--alongside SH, SS, and EX/EE.  You can't nest any
> of those under a paragraph, either.
> 
> > > Now on first sight, you might blame me for that and call it a mandoc
> > > artifact, arguing that mandoc instead ought to treat the .RS as a
> > > child of the first .TP.  But no, that would be incorrect parsing
> > > for the following reason: the .TP inmplies an indentation, and
> > > the .RS also implies an indentation.  If the .RS were a child of
> > > the .TP, we would get double indentation.  You can make that
> > > argument even more convincing by adding a width argument to .RS
> > > and varying that argument.  That way, you see that the .RS is
> > > indented relative to the .SH, not relative to the .TP.
> 
> That's correct, and consistent with how I've documented this vexing
> issue in groff_man_style(7).
> 
> > > There are some cases where it is not completely clear whether one
> > > man(7) node following another man(7) node is a child or a sibling.
> > > mandoc(1) makes arbitrary choices in such ambiguous cases, usually
> > > opting for sibling relations where possible and avoiding unnecessary
> > > child relationships.  But this is not an ambiguous case.  Just like
> > > the .IP, the .RS is definitely a sibling and not a child of the .TP.
> > > As i said, no block can nest inside .TP.
> 
> I agree, but I may need to review and reconsider the second paragraph of
> this advice from groff_man_style(7), then.
> 
>        • .RS doesn’t indent relative to my indented paragraph.
>               The .RS macro sets the left margin; that is, the position
>               at which an ordinary paragraph (.P and its synonyms) will
>               be set.  .IP, .TP, and the deprecated .HP use the same
>               default indentation.  If not given an argument, .RS moves
>               the left margin by this same amount.  To create an inset
>               relative to an indented paragraph, call .RS repeatedly
>               until an acceptable indentation is achieved, or give .RS
>               an indentation argument that is at least as much as the
>               paragraph’s indentation amount relative to an adjacent .P
>               paragraph.  See subsection “Horizontal and vertical
>               spacing” above for the values.
> 
>               Another approach you can use with tagged paragraphs is to
>               place an .RS call immediately after the paragraph tag;
>               this will also force a break regardless of the width of
>               the tag, which some authors prefer.  Follow‐up paragraphs
>               under the tag can then be set with .P instead of .IP.
>               Remember to use .RE to end the indented region before
>               starting the next tagged paragraph (at the appropriate
>               nesting level).
> 
> I'll see if I can undertake some experiments with mandoc(1) to see if it
> works consistently with groff man(7) (and every other man(7), as far as
> I know).  It seems like it might, because having an `RS` after the tag
> of a `TP` paragraph might close the "block" that mandoc(1) imputes to
> the `TP` macro when building the AST.
> 
> > > But very frequently, situations arise where man(7) doesn't really
> > > allow any good solution, and the best you can do is not making
> > > the source gratuitiously worse than it needs to be.
> 
> I think "very frequently" is overstated here.  I'd say "occasionally".
> Thousands of adequate man(7) pages, and possibly thousands more if they
> were written by more clueful authors or generation tools, can speak to
> that.
> 
> > > The .TP .IP .TP idiom is such an example.  It's definitely ugly from
> > > both semantic and stylistic points of view, but no good solution is
> > > available.  I'm willing to go further and claim that no better
> > > solution can be designed even if you are willing to introduce a new
> > > macro or change the way the .TP API is defined, even in incompatible
> > > ways, because it's not this particular macro that is broken.  What
> > > is broken is the fundamental design of the language: the language
> > > not only predates the concept of semantic markup, but it also
> > > predates the concept of block nesting in markup languages.  Yes,
> > > that is hard to believe for people born after 1970 because those
> > > people have essentially grown up with HTML and LaTeX and those two
> > > markup languages have defined their concept of what a markup
> > > language is, but let's face it, man(7) predates those fundamental
> > > concepts, and it shows all over the place.
> 
> *roff was written as a Unix filter.  It assumed non-seekable input and
> worked on one output line at a time (except when diverting).
> 
> mdoc(7) is not all that different in this respect; it simply doesn't
> have a nail sticking up in this respect as RS/RE does.
> 
> There is this, for example:
> 
>        The list and display macros do not do any keeps and certainly
>        should be able to.
> 
> ~33 years after that was written, it still hasn't been addressed.
> 
> Who knows, maybe I will after adding `KS` and `KE` to man(7).  3;-)
> 
> > Hmmm.  You convinced me (about the problems of man(7)), I think.
> 
> If you needed convincing that man(7) has problems, i.e., is not perfect,
> then I could have told you that a long time ago.
> 
> One question is whether you can get people to abandon it for mdoc(7),
> and the answer to that seems to be "yes, if you're a *BSD developer" and
> otherwise "yes, if you roll a 00 on percentile dice".

I'm not yet convinced by the superiority of mdoc(7), as you probably
guessed.  I fear that I might face similar problems in other areas if I
were to switch to it.

What I think I'm convinced is that there's no perfect way of dealing
with indentation in man(7).  .TP/.RS/.RE might be the most consistent
one.  I just wish it didn't introduce a break after the tag.

The good thing about TP/RS/RE is that you could think of it like braces
in C:  if (...) foo(); doesn't need them; if (...) {foo(); bar();} does.
Similarly, mandoc could consider an RS directly following a TP as the
wrapper for the tagged section.

> 
> Another question is that, if you can persuade people to give up on
> man(7), whether they will land anywhere useful in particular.  My view
> is that there are three classes of people who take this leap, and
> another that used to be large but is dwindling.
> 
> A.  They go to some dialect of Markdown, where nothing molests their
>     precious ASCII WYSIWYG characters or requires them to think about
>     anything except terminal devices, or demands much consideration of
>     semantics as opposed to presentation.
> 
> B.  They do to Doxygen/ReSt/Sphinx or whatever is currently fashionable.
> 
> C.  They escape from responsibility for maintaining documentation
>     altogether, and are deliriously happy about it.  (So should we be,
>     if they hate it so much--see below.)
> 
> D.  They go to DocBook, because anything that looks like XML is
>     inherently superior to anything that doesn't.
> 
> Further, in my opinion, the people in all three of these classes
> generally neglect their documentation in its new "superior" format at
> least as badly as they did when it was in man(7) format.  This is
> particularly true of classes B and D.
> 
> My opinion is that becoming conversant with the markup format simply
> isn't the hardest thing about composing high quality documentation in
> man(7), nor even in mandoc(7), which I think has a more difficult
> learning curve, is freighted with a vastly larger macro vocabulary
> (taxing the memory), carries around more cruft, and is just plain
> weirder for anyone who ever uses *roff for any other purpose.  (I admit,
> that last factor seems to rule out a _lot_ of BSD people.  In CSRG BSD
> days, authoring manuals seemed still to be regarded as an honorable
> thing.[1]  In the early to mid 1990s, some kind of rot set in.[2])
> 
> No, the hardest thing about technical writing is that doing it well
> requires thought, at least as much as programming does, and software
> engineers share a delusion with their managers that this isn't the case.
> Writing the docs, like writing the test cases, is regarded as something
> you "should be able to do with your brain switched off".  It's a menial
> task, kicked to the end of a production deadline, done with resentment
> and in a hurry.
> 
> That fallacious belief is reflected with clarity in the low quality of
> the documentation and test harnesses we see, by and large.
> 
> We should honor the exceptions when we encounter them; they are rare
> enough.
> 
> Regards,
> Branden
> 
> [1] 
> https://minnie.tuhs.org/cgi-bin/utree.pl?file=4.3BSD-Reno/share/doc/ps1/00.contents
>     
> https://minnie.tuhs.org/cgi-bin/utree.pl?file=4.3BSD-Reno/share/doc/ps2/00.contents
>     
> https://minnie.tuhs.org/cgi-bin/utree.pl?file=4.3BSD-Reno/share/doc/smm/00.contents
>     
> https://minnie.tuhs.org/cgi-bin/utree.pl?file=4.3BSD-Reno/share/doc/usd/00.contents
> 
> [2] The Web, maybe.



-- 
<https://www.alejandro-colomar.es/>

signature.asc
Description: PGP signature