Hi Branden, On Mon, Oct 23, 2023 at 04:15:23AM -0500, G. Branden Robinson wrote: > [dropped t...@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
