Re: nesting lists in man(7) pages

[G. Branden Robinson]

Hi Ingo,

At 2021-08-11T14:37:58+0200, Ingo Schwarze wrote:
> G. Branden Robinson wrote on Wed, Aug 11, 2021 at 01:16:45AM +1000:
> > but I reckon I should actually step up and try to improve one of the
> > generator tools, like pod2man
> 
> That would be a noble deed because pod2man(1) is a very useful tool
> and produces almost decent man(7) code in most respects, though i
> don't doubt it can be made even better.  Also, helping Russ Allbery
> would feel like giving something back to a venerable greybeard of
> of outstanding merit.

Strongly agree.  When I attended a DebConf for the first time in many
years in Montréal in 2017, Russ was a person I sought out for a
handshake.  He's done great service on the Debian Technical Committee.

(Nowadays, the notions of handshakes and in-person technical conferences
seem quaint...)

> > or docbook-to-man, before making this claim.
> 
> I pity you if you try, but you would be a hero if you succeeded.

I'm not sure I have that strong a lust for glory.  :P

> Feedback regarding mandoc -Tman is also welcome.  I admit maintenance
> done on it petered out a bit during the last few years.  It appears
> systems not supporting mdoc(7) and hence requiring distribution of
> auto-generated man(7) pages in release tarballs alongside the original
> mdoc(7) code become less and less common, so mandoc -Tman is seeing
> less and less use, seemingly.

I am sometimes surprised to see pre-generated mandoc-generated man(7) in
manual trees.  I don't recall seeing anything in the markup that alarmed
me.  Surely if I had, I would have rushed to this mailing list to
thunder to you about correctness... ;-)

> Indeed, in mandoc(1), man_validate.c function post_IP(), which checks
> for content to automatically tag, does not tag the recommended .IP
> content you describe above:
> 
> /*
>  * Skip leading whitespace, dashes, backslashes, and font escapes,
>  * then create a tag if the first following byte is a letter.
>  * Priority is high unless whitespace is present.
>  */
> 
> And in fact, it also does not tag if that first character is
> a character escape sequence, for example \(bu.

Perfectly reasonable, if you want to take on the business of parsing the
paragraph tags.

> >> Sure, .TP/.IP lists cannot nest, or is there another problem with
> >> them i'm missing?
> 
> > Au contraire!  You can nest them if you use .RS/.RE.  My struggles
> > with mixing .RS and .IP was in fact the issue that inflicted me on
> > all of you[1][2].
> > 
> > $ ./build/test-groff -Tutf8 -man -rLL=72n EXPERIMENTS/nested-IP.man
> [...]
> 
> Technically, that's not nesting, but one .IP list, then a second,
> indented .IP list, then another .IP list:

Or even one "list" per IP call...

>    $ man -l -T tree nested-IP.man
>       [...]
>       IP (block) *10:2
>         IP (head) 10:2
>             \(bu (text) 10:5
>         IP (body) 10:2
>             Hire gnomes. (text) *11:1.
>       RS (block) *12:2
>         RS (head) 12:2
>         RS (body) 12:2
>             IP (block) *13:2
>               IP (head) 13:2
>                   \(dg (text) 13:5
>               IP (body) 13:2
>                   Collect underpants. (text) *14:1.
>             IP (block) *15:2
>               IP (head) 15:2
>                   \(dg (text) 15:5
>               IP (body) 15:2
>                   ??? (text) *16:1.
>             IP (block) *17:2
>               IP (head) 17:2
>                   \(dg (text) 17:5
>               IP (body) 17:2
>                   Profit! (text) *18:1.
>       IP (block) *20:2
>         IP (head) 20:2
>             \(bu (text) 20:5
>         IP (body) 20:2
>             Retire to tropical paradise. (text) *21:1.

Yup.  I get you completely.  I had Presentationitis from reading a lot
of linux-man list traffic recently.

So, you're right, what we really need here are begin- and end-list tags.

The instant problem comes from IP, like all paragraph tags, being "spot"
markup rather than "block" markup.  (There are probably more correct
terms for these.)

I don't know if blockifying man(7) paragraph tags in worth the trouble
or likely to get update, but people compose lists _all the time_ in
man(7) pages and they so often turn out badly that I'm warming up to the
idea of taking that on as my next big man(7) reform..._after_ I get MR
implemented, a feature that is drumming its fingers on the table in my
brain.

Regards,
Branden

signature.asc
Description: PGP signature