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

[G. Branden Robinson]

Hi Alex,

At 2023-10-23T12:47:21+0200, Alejandro Colomar wrote:
> On Mon, Oct 23, 2023 at 04:15:23AM -0500, G. Branden Robinson wrote:
> [Added groff@, to have some mailing list]

Ah, okay, well, in so doing you have exposed some brain farts of mine to
the world.  But I have no doubt that Ingo would have caught them, and
possibly pounced, so I take this opportunity to correct myself.

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

I didn't fulfill the promise of this footnote.  Here it is.

https://lists.gnu.org/archive/html/groff/2017-08/msg00028.html

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

This is obviously wrong.  EX/EE "nest" within any kind of paragraph just
fine.  My brain seized upon a generalization and ran too far with it.

I withdraw the observation.  What I can say is that SH, SS, and RS/RE
all affect the amount by which the text is inset, and EX/EE do not.  Our
man pages already say that, though.

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

I felt a little guilty writing that and not going ahead and presenting
an exhibit, and publishing my laziness to a mailing list compounds my
embarrassment.

On the bright side, I took a quick stab at it, at (A) it worked as I
expected on the first try; and (B) groff and mandoc are in perfect
harmony here.

$ cat ATTIC/nests-inside-tagged-paragraphs.man
.TH foo 1 2023-10-23 "groff test suite"
.SH Name
foo \- frobnicate a bar
.SH Description
.TP
tag1
Prepare the turbo encabulator.
.RS
.RS
.EX
$ \c
.B "turbenc \-\-start"
.EE
.RE
It's up and running fine now.
.RE
.TP
tag2
.RS
Shut down the turbo encabulator.
.RS
.EX
$ \c
.B "turbenc \-\-halt"
.EE
.RE
It slowly grinds to a halt.
.RE
.P
All done now.
$ nroff -Tascii -man ATTIC/nests-inside-tagged-paragraphs.man
foo(1)                      General Commands Manual                     foo(1)

Name
       foo - frobnicate a bar

Description
       tag1   Prepare the turbo encabulator.
                     $ turbenc --start
              It's up and running fine now.

       tag2
              Shut down the turbo encabulator.
                     $ turbenc --halt
              It slowly grinds to a halt.

       All done now.

groff test suite                  2023-10-23                            foo(1)
$ mandoc -Tascii -man ATTIC/nests-inside-tagged-paragraphs.man | ul
foo(1)                      General Commands Manual                     foo(1)

Name
       foo - frobnicate a bar

Description
       tag1   Prepare the turbo encabulator.
                     $ turbenc --start
              It's up and running fine now.

       tag2
              Shut down the turbo encabulator.
                     $ turbenc --halt
              It slowly grinds to a halt.

       All done now.

groff test suite                  2023-10-23                            foo(1)

Et voilá.

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

In a sense, it can't be flawed because it has no spec; but other edge of
that blade says it can't be flawless, because it has no spec.

Same's true of man(7), of course.

My mad crush on formal verification is not going anywhere soon.

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

Can you name a man-pages document where this problem is itching you?
Probably many--show me just one at first.

I'd like to see how well the half-designed, existing-only-in-my-head
`LS`/`LE` extension macros for man(7) I've proposed might address it.

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

That _seems_ to be what it's doing?  Don't get hung on up on the
indentation level; it appears to be bracketing the `TP` body to me.

If the input makes sense, and the output looks right, I wouldn't worry
too much about how mandoc(1) presents the tree.  I consider that a
debugging aid.

$ mandoc -Ttree -man ATTIC/nests-inside-tagged-paragraphs.man \
  | sed -n '/Description/,$p'
      Description (text) 4:5
  SH (body) 4:2
      TP (block) *5:2
        TP (head) 5:2 ID=HREF
            tag1 (text) *6:1
        TP (body) 6:1
            Prepare the turbo encabulator. (text) *7:1.
      RS (block) *8:2
        RS (head) 8:2
        RS (body) 8:2
            RS (block) *9:2
              RS (head) 9:2
              RS (body) 9:2
                  EX (elem) *10:2
                  $ \c (text) *11:1 NOFILL
                  B (elem) *12:2 NOFILL
                      turbenc \-\-start (text) 12:4 NOFILL
                  EE (elem) *13:2 NOFILL
            It's up and running fine now. (text) *15:1.
      TP (block) *17:2
        TP (head) 17:2 ID=HREF
            tag2 (text) *18:1
        TP (body) 18:1
      RS (block) *19:2
        RS (head) 19:2
        RS (body) 19:2
            Shut down the turbo encabulator. (text) *20:1.
            RS (block) *21:2
              RS (head) 21:2
              RS (body) 21:2
                  EX (elem) *22:2
                  $ \c (text) *23:1 NOFILL
                  B (elem) *24:2 NOFILL
                      turbenc \-\-halt (text) 24:4 NOFILL
                  EE (elem) *25:2 NOFILL
            It slowly grinds to a halt. (text) *27:1.
      PP (block) *29:2
        PP (head) 29:2
        PP (body) 29:2
            All done now. (text) *30:1.

Regards,
Branden

signature.asc
Description: PGP signature