nesting lists in man(7) pages

[G. Branden Robinson]

Hi, Ingo!

At 2021-08-04T13:33:30+0200, Ingo Schwarze wrote:
> I can confirm Branden's observation that lists are where people (and
> even more so, tools automatically generating man(7) code) often
> produce low-quality man(7) code.  I'm not quite sure why, though.

I'm _so_ tempted to say, "failure to understand the target language",
but I reckon I should actually step up and try to improve one of the
generator tools, like pod2man or docbook-to-man, before making this
claim.

> The .IP macro seems almost as good as .Bl -bullet/-dash to me,

You mentioned somewhere that we might infer link targets from IP tags.
That's technically true, but if they're used as recommended in
groff_man_style(7), they _won't_ convey semantic information of use.
They really will just be numbers in a list, or bullet symbols or the
like.  That's one reason my style advice reads that way--to stregthen
TP's semantic value.

> 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
foo(1)                   General Commands Manual                  foo(1)

Name
       foo - frobnicate any input

Description
       We have a foolproof scheme for getting rich.

       •      Incorporate in Cayman Islands.

       •      Acquire venture capital.

       •      Hire gnomes.

              †      Collect underpants.

              †      ???

              †      Profit!

       •      Retire to tropical paradise.

groff example                  2020-08-10                         foo(1)

Source attached.

Regards,
Branden

[1] https://lists.gnu.org/archive/html/groff/2017-08/msg00028.html
[2] I showed up in April 2017[3], not August, but it took me a few
    months to work up the nerve to throw my problem down in front of
    everyone.
[3] ...participating in discussions about escaping hyphens and the
    output line continuation escape \c, issues of perennial frustration
    among unweathered man(7) authors.

nested-IP.man
Description: Unix manual page

signature.asc
Description: PGP signature