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

[Alejandro Colomar (man-pages)]

Hi, Ingo!

On 8/3/21 4:30 PM, Ingo Schwarze wrote:
> 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.

It is more complex (in the end with man(7) I end up using mainly .PP, 
.IP, .B, .I, and combinations of I, B and R, and then a few .RS/.RE, 
.EX/.EE, .SH and .SS), while mdoc(7) has quite more macros and less 
obvious ones (compared to these extremely simple ones).

But it's not necessarily extremely complicated; I mean, with some time 
I'd probably get it easy.  It's just that I learnt man(7) by necessity, 
and I haven't had the need to learn mdoc(7) yet, but I may some day.

But hey, I can transfer my man(7) knowledge easily to write other kinds 
of documents (done that; legal documents), and it scales well :)

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

That's true... partly.  I'd say that with a consistent man-pages corpus, 
it would be easier to know what you have to use, just by looking at 
other pages, but we don't have that at the moment (and it's one of my 
long term goals here).

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

Yup.  From what I've seen, Linux man-pages have been ignoring the 
recommended style when there were three fonts mixed, and instead have 
used (somewhat incorrectly) 2 fonts, in exchange for simplicity.

However, now I'm trying to fix that and it doesn't seem so much complex 
(yes, it involves \c).

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

Hmmm, much more than what's in my head right now from man(7), but not an 
exaggerate number.


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

There are a few considerations:

- Neither Michael nor I do have a lot of time these times (the next 
release of the man-pages (5.13), which should be released soon, will be 
quite small because of that).

- I have other more prioritary fixes for the pages:
  - Fixing the includes in the examples
  - Documenting types in system_data_types(7)
  - Add a LIBRARY section (as in FreeBSD pages) to simplify the current 
text that provides that information in a mix of sections.
  - Some other consistency fixes.

- I would like to have the pages consistently use man(7) before ever 
considering a language change.  The thing, and this is only a prediction 
of mine, is that when we have the pages more consistent than now, it 
should be even easier to use man(7), and incoming patches should be more 
correct on average, so there will be less reason to move to another 
language/dialect.

- There are some benefits, as it seems, but enough to make such a big 
change?  Not sure.

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

Cheers,

Alex


--
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/