Re: Plan 9 man added a new macro for man page references

[Ingo Schwarze]

Hi Alejandro,

Alejandro Colomar (man-pages) wrote on Wed, Aug 04, 2021 at 11:44:32AM +0200:
> On 8/4/21 10:57 AM, G. Branden Robinson wrote:

>>      The other hole in man(7) functionality that pains me, and which I
>>      see people deploying ersatz simulacra thereof, is the list.[3]  Our
>>      own page groff(7) sins voluptuously in this respect to produce
>>      lengthy references of escape sequences, request names, and built-in
>>      registers.  Fixing it will require a major overhaul.  I'm not sure
>>      what I want to do about this yet.  mdoc has tackled the
>>      problem--with a frighteningly complex interface.  I question the
>>      wisdom of "porting" mdoc's "Bl" to man(7) under any name.

> One thing I'll ask, if I may:
> 
> If you port it with the same exact features,

Please don't.

Brandon is completely right that the .Bl macro looks frighteningly complex
on first sight, even though it is actually very easy to use in practice.
Even though i never bothered with deprecating any parts of .Bl,
many of its parts are not really needed in practice.  Ordering stuff
by usefulness:

  -tag
  This is the real workhorse.
  The syntax is non-trivial but not difficult:
  .Bl -tag [-width ...] [-offset ...] [-compact]
  Using it is reasonably simple.

  -bullet and -dash
  are almost identical with each other except for the item marker.
  They are highly useful, and using them is very easy.

  -enum
  has exactly the same syntax as -bullet and is as easy to use.

Here come the parts not to be imitated:

  -column
  is admittedly ugly in several respects and not among the best parts
  of mdoc.  It is not fit to serve as a model for anything new.
  Fortunately, man(7) has no need for it.  If pages written in man(7)
  really need tables, they can embed tbl(7) code, as long as they don`t
  go overboard abusing arcane tbl(7) features.  Using basic tbl(7)
  features in man(7) is reasonably portable and provides all that
  .Bl -column provides, and more.

  -diag
  is excessively specialized.  It has a traditional use case in BSD
  manual pages, but could easily be dispensed with.

  -hang, -inset, -item, and -ohang
  are mostly useless and could easily be deprecated.

  -hyphen
  is just a pointless synonym

> could it come with the same exact name?
> Well, .BL to keep uppercase man(7) conventions.
> That would reduce brain load.  :)

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.

The .IP macro seems almost as good as .Bl -bullet/-dash to me,
and .TP almost as good as .Bl -tag, even better in so far as .TQ
is easier to use than .Bl -compact.  Sure, .TP/.IP lists cannot nest,
or is there another problem with them i'm missing?

Yours,
  Ingo