[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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

From: Alejandro Colomar (man-pages)
Subject: Re: Plan 9 man added a new macro for man page references
Date: Tue, 3 Aug 2021 22:23:09 +0200
User-agent: Mozilla/5.0 (X11; Linux x86_64; rv:78.0) Gecko/20100101 Thunderbird/78.12.0

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.




Alejandro Colomar
Linux man-pages comaintainer;

reply via email to

[Prev in Thread] Current Thread [Next in Thread]