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

[Alejandro Colomar]

Hi Branden, Ingo,

On Mon, Oct 23, 2023 at 08:36:11AM -0500, G. Branden Robinson wrote:
[...]
> > 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.

There's no formatting bug.  The problem is lack of consistency in the
man(7) source, which confuses contributors.  I need to fix patches from
contributors that use PP when IP should go, or the other way around,
because they just don't understand why each of them is used in each
case.

The thing is, in my head 3 years ago, when I was first exposed to
man(7), I remember this inconsistency being one of the most complex
things to wrap in my head.

Wrapping everything in RS/RE so that one can use PP to continue within
a TP would also make it easy to move text from within a TP to a
non-indented section, since the indentation is only written once, in the
RS.  It's more DRY.

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

I think keeping it DRY would be the resume of what to aim for.

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

Yeah... in terminals.  But in HTML, things go wrong.  See
<https://inbox.vuxu.org/mandoc-tech/ZTGggTYHc-vKcv4e@debian/T/#mb0247a1393d34f3d7b622feef20ac25189d694c8>

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

It's not only that, but also the HTML output.

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

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

Currently, it's being used in 684 pages, and 3108 cases.

        $ grep -rH '^\.TQ' | uniq | wc -l
        684
        $ grep -rH '^\.TQ' | wc -l
        3108

Well, here goes my experiment, based on Branden's one.

        $ cat nest-of-rats.man 
        .TH foo 1 2023-10-23 "groff test suite"
        .SH Name
        foo \- frobnicate a bar
        .SH Description
        .TP
        tag1
        .TQ
        another1
        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.

I just added the TQ another1.

        $ mandoc -Ttree ./nest-of-rats.man
        title = "foo"
        sec   = "1"
        vol   = "General Commands Manual"
        os    = "groff test suite"
        date  = "2023-10-23"

        SH (block) *2:2
          SH (head) 2:2 ID=HREF
              Name (text) 2:5
          SH (body) 2:2
              foo \- frobnicate a bar (text) *3:1
        SH (block) *4:2
          SH (head) 4:2 ID=HREF
              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
              TQ (block) *7:2
                TQ (head) 7:2 ID=HREF
                    another1 (text) *8:1
                TQ (body) 8:1
                    Prepare the turbo encabulator. (text) *9:1.
              RS (block) *10:2
                RS (head) 10:2
                RS (body) 10:2
                    RS (block) *11:2
                      RS (head) 11:2
                      RS (body) 11:2
                          EX (elem) *12:2
                          $ \c (text) *13:1 NOFILL
                          B (elem) *14:2 NOFILL
                              turbenc \-\-start (text) 14:4 NOFILL
                          EE (elem) *15:2 NOFILL
                    It's up and running fine now. (text) *17:1.
              TP (block) *19:2
                TP (head) 19:2 ID=HREF
                    tag2 (text) *20:1
                TP (body) 20:1
              RS (block) *21:2
                RS (head) 21:2
                RS (body) 21:2
                    Shut down the turbo encabulator. (text) *22:1.
                    RS (block) *23:2
                      RS (head) 23:2
                      RS (body) 23:2
                          EX (elem) *24:2
                          $ \c (text) *25:1 NOFILL
                          B (elem) *26:2 NOFILL
                              turbenc \-\-halt (text) 26:4 NOFILL
                          EE (elem) *27:2 NOFILL
                    It slowly grinds to a halt. (text) *29:1.
              PP (block) *31:2
                PP (head) 31:2
                PP (body) 31:2
                    All done now. (text) *32:1.

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.

Cheers,
Alex

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

signature.asc
Description: PGP signature