Re: nesting lists in man(7) pages

[Ingo Schwarze]

Hi Branden,

G. Branden Robinson wrote on Sat, Aug 14, 2021 at 12:53:31AM +1000:

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

Kristaps called

  .Bd .Ed .Oo .Oc  .RS .RE  --  explicit blocks
  .Sh .It .Op      .SH .TP  --  implicit blocks
  .Ar .Em          .B  .I   --  in-line elements

and i consider that terminology reasonable.

> I don't know if blockifying man(7) paragraph tags in worth the trouble
> or likely to get update,

You mean, "uptake"?

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

Regarding .MR:

You recently felt troubled when you realized that there is no
apparent way to tell people about the new NAME -> Name feature;
i sent a message confirming your fears earlier today.

Adding a new macro indeed does create very serious real-world
problems that cannot easily be solved, and those problems are worse
for man(7) and Linux than for mdoc(7) and BSD because the number
of distros is probably by about a factor of hundred higher in Linux
than in BSD and because all BSD systems usually update mandoc within
one year of a new release coming out, whereas for many Linux distros,
a new groff package may take much longer to land.

Is this feature really significant enough to design a solution that
is incompatible with existing formatters?  Is there really no way to
reach the same goal without totally breaking compatibility?

I think there is no way to deny that the compatibility break is very
serious indeed.  If a new page uses .MR, an old formatter will
completely omit the manual page reference and show nothing at all,
in all output modes.

For example, would it be sufficient to treat .IR as a manual page
reference if and only if the second argument starts with '(' and a
decimal digit, optionally followed by some ASCII letters, and ends
with ')', optionally followed by punctuation?  That would be fully
compatible with existing formatters, false positives would be very
rare and could be suppressed by prepending "\&" to the argument if
an unusually diligent author really felt a pressing need to do so.
Without any hurry, authors could be educated to use the new feature
and avoid idioms like

  .RI (see kill (2)).

in favour of

  (see
  .IR kill (2)).

Many will already be doing just that, intuitively.

I'm not saying that is the best or only way.  I'm merely saying you
run a risk of rushing to the implementation stage before really
considering (a) the design and (b) the consequences for real-world
manual pages and how to get onto a viable migration path.

Reagrding tagged lists:

Yes, i is an area where bad man(7) code gets written even more often
then in other respects.  But before deciding that a new language
feature needs to be designed because people do cray things for the
lack of it, we have to understand what exactly is missing.  Or,
which is a similar, but not exactly the same question, why exactly
people are doing those crazy thing.

So far, the only speculation offered to that question is "failure
to understand the target language".  Even if that spaculation is
accurate, and it does seem plausible, then it is *not at all* an
argument to add anything new.  You have three list macros (.TP,
.IP, .HP) in your (otherwise small) language.  People don't understand
the list macros.  How do we solve that problem?  Add more list
macros!  You must be joking, Mr. Feynman...

The technicalities i just brought up regarding how man(7) list
macros do not really nest are certainly not the reason why lists
are so often badly marked up in man(7) code: i think a very small
number of people is aware of these technicalities.  Even if there
were, i dont think it would deter them.  And the number of people
who design their man(7) code to support HTML as well as possible
is likely to be extremely small, too.  So what *is* the actual
problem?  Don't even start searching for a solution until you have
a very clear answer to that question.

Even if we would come to the conclusion that new list macro(s) are
needed, i doubt that they need to be explicit.  Even though .RS and
.EX exist, they feel like exceptions and implicit blocks feel more
natural and nearer to the spirit of the man(7) language.  By
comparison, the mdoc(7) language has a balanced approach of providing
both explicit and implicit macros, and even there, the list item
macro (.It) is an implicit one, no less than .TP in man(7).
Besides, one can argue that in the context of man(7), the fact
that .TP is implicit does not hinder rendering of lists as <dl><dt>...
at all.  What causes the problem is rather that the explicit .RS
macro suddenly intrudes into a language otherwise mostly designed
with implicit blocks.

After the problem has been identified, the design has to be considered.
For example, if the HTML rendering issue caused by the .RS interruption
were the problem - but i believe it is not, see above - then for example
adding a third "indentation" (or equivalently, "level") argument to the 
.TP macro might be a viable candidate for a design.  It might not even
cause a serious compatibility break.

Again, i'm far from presenting this as the best or only solution to a
(yet unidentified) problem.

Yours,
  Ingo