[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

nesting lists in man(7) pages

From: G. Branden Robinson
Subject: nesting lists in man(7) pages
Date: Wed, 11 Aug 2021 01:16:45 +1000
User-agent: NeoMutt/20180716

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

> 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

$ ./build/test-groff -Tutf8 -man -rLL=72n EXPERIMENTS/
foo(1)                   General Commands Manual                  foo(1)

       foo - frobnicate any input

       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.


[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
[3] ...participating in discussions about escaping hyphens and the
    output line continuation escape \c, issues of perennial frustration
    among unweathered man(7) authors.

Description: Unix manual page

Attachment: signature.asc
Description: PGP signature

reply via email to

[Prev in Thread] Current Thread [Next in Thread]