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

[Ingo Schwarze]

Hello Alejandro,

Alejandro Colomar (man-pages) wrote on Tue, Aug 03, 2021 at 09:29:14AM +0200:

> Thinking about it twice...
> 
> Given mdoc(7) already implemented that, and that the basic difference 
> between mdoc(7) and man(7) is basically that man(7) is simple and 
> doesn't have semantic macros (only style macros), and mdoc(7) was 
> designed to superseed man(7) by having semantic macros instead of
> style macros

I consider that summary accurate.

> (but with the side effect of being much more complex in the way), 

I can't dispute the fact that the macro repertoire of mdoc(7)
is more complex than the macro repertoire of man(7).

But i never quite understood why people find using mdoc(7) more
complicated than using man(7), for several reasons.

 1. The mdoc(7) macro repertoire is quite small in absolute terms:
    24 un-deprecated structure macros and
    26 un-deprecated semantic macros.
    The MACRO OVERVIEW for these can easily be seen in one
    terminal window, all at the same time.
    Yes, there are also about 11 physical markup macros
    and about 3 useful text production macros,
    but those hardly change the overall picture.
    For comparison, DocBook is more than 5 times the size of mdoc(7),
    and the texinfo(5) language is also sigificantly larger than mdoc(7).

 2. I find it easier to remember that a function name needs .Fn
    than that it needs .B, or that a command line argument needs
    .Ar than that it needs .I.  The amount of content type to macro
    mappings you need to memorize (or look up) is exactly the same
    for both languages, except that mdoc(7) has mnemonics and man(7)
    has not.

 3. mdoc(7) has fewer syntactic quirks than man(7), not more.
    A function argument needs .Fa, so it always gets .Fa, no matter
    in which context.  In man(7) it sometimes needs .I, sometimes .IR,
    sometimes .RI, and when it appears on the same line a bold *and*
    roman content, you need a completely different syntax: escape
    sequences, either \c or \f.  And that's just one example of
    syntax complexity in man(7).

 4. For displays and lists, i claim that mdoc(7) .Bd and .Bl
    syntax is not only more powerful and expressive, but actually
    simpler and more uniform than man(7) .RS, .IP, .TP, .HP, and
    .EX, without even needing as many macros.

 5. In the rare instances where man(7) does have limited semantic
    markup, like .MT, .OP, .SY, .UR, it certainly isn't easier 
    to use than the mdoc(7) equivalents, but it feels alien to the
    rest of the man(7) language.

 6. When writing man(7) code, people regularly resort to using some
    low-level roff features to fill gaps in the man(7) language.
    That is almost never needed with mdoc(7), IMHO making the latter
    easier to use than the former because you need less low-level
    roff(7) skills.

 7. During the last decade, i deprecated several mdoc(7) macros
    including .Bt, .Db, .En, .Fr, .Hf, .Li, .Lp, .Tn, .Ud, .Ux
    and only added a single new one, .Tg.  So the language is
    becoming simpler over time rather than growing.

 8. Existing BSD manual page corpusses use several macros for
    historical reasons that would be trivial to avoid when adopting
    the language for a new corpus, making the language even simpler,
    for example .Os, .Bk, .Lb, .Ad, .Ms, .Bf, .Xo.
    The OS text production macros (.At, .Bx, .Bsx, .Nx, .Fx, .Ox, .Dx)
    would also not be strictly needed, reducing language size by
    another seven macros.  So you would basically end up with
    about 60 useful macros grand total.

> I think it would be wrong to "port" back (some of) those features back 
> into man(7).

That consideration does make sense to me.

When maintaining a programming or markup language, sparingly and
cautiously adding new syntax to fill isolated gaps in the feature set
often makes sense.

When a language is designed from the ground up with one programming
paradigm in mind - physical markup in the case of man(7) - redesigning
it for a completely different programming paradigm while in maintenance
mode seems like a questionable idea to me.

> Either we should move to use mdoc(7), or we don't at all.  (And for
> the moment, I think I'll keep with the man(7) simpler macros.)

*For the moment*, lots of constraints and tradeoffs usually have
to be considered, and i might understand if you come to the conclusion
that now is not the ideal time for you to adopt a language with a
more powerful paradigm.  Given that mdoc(7) has been available for
three decades, it is not a matter of life and death to adopt it
*right now*, it is a seasoned and time-proven language, it is
actively maintained, and will still be available for years to come.

> What are your thoughts?

In the long term, man(7) does not feel sustainable.  It was state of
the art in 1979, but missed the semantic markup revolution that
happened with HTML and mdoc about a decade after it was invented.

Note that you could rightfully say that mdoc(7) was state of the
art in 1994, so it's not exactly dernier cri either.  But i don't
think another revolution comparable to the HTML/mdoc revolution
happened during all those years since then.  Texinfo and Docbook
did not introduce a new paradigm or any significant new concept,
they merely increased the size of languages.  So i think mdoc(7)
is still state of the art in 2021, and unless something quite
unexpected happens, which is of course always possible, will be
for many years to come.

Yours,
  Ingo