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
