Re: Use various macro packages in the same page (was: 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 08:59:21AM +0200:

> Is it possible to use more than one macro package at the same time?

Branden already explained well how it is possible to use multiple
auxiliary macro packages in addition to one full-service package,
in general - except that doing so is undesirable in manual pages.
He also explained how mdoc(7) and man(7) will get into a fight about
the big picture, like page layout and the like.

Another area of conflict is macro scoping, i.e. where (1) the
syntactic scope of each macro and (2) its formatting effect
begins and ends, and related nesting.  On the roff side, this whole
topic is somewhat non-obvious because groff_mdoc(7) and groff_man(7)
are implemented as macro packages, so on first sight, all that
happens there is text replacements.

But the mdoc(7) and man(7) languages can also be regarded as languages
with a grammar and semantic significance attached to the grammatical
elements, even though groff doesn't implement them that way.  Both
languages can be compiled into an abstract syntax tree (AST), and that's
what mandoc(1) does - and then the mandoc(1) formatters start their
work from that AST.

For both languages, that AST has a block structure, but the rules
where blocks start and end, and whether and how they can nest, are
vastly different.  In a nutshell, man(7) blocks mostly do not nest,
whereas mdoc(7) blocks can not only nest to a depth of multiple
level, but support - in contrast to languages like XML/HTML - what
mandoc calls "bad nesting":

  .Bf -emphasis
  This is a block of italic text
  .Po
  with a parenthetic remark that starts italic
  .Ef  \" end the scope of .Bf
  and ends roman.
  .Pc  \" end the scope of .Po

I'm not saying relying on such features is good style in a manual page,
only that scoping rules (which authors rarely need to worry about)
are non-trivial under the hood and completely different in both
languages.  While man(7) is simpler than mdoc(7) in this area, it does
have one feature that mdoc(7) does not: next-line scoping:

  .SH
  Synopsis

is equivalent to

  .SH Synopsis

in man(7), but not in mdoc(7).

Then, while both languages have some macros that explicitly close
blocks (.RE, .EE, .Ed, .El, .Oc, ...), both also have blocks that
end implicitely - sometimes at the end of the input line (or the next
input line for man(7)), sometimes at the beginning of certain other
blocks.  These closing-out rules are again vastly different in both
languages, even though authors usually don't need to be aware of
them.

However, if you start mixing both languages, scoping, nesting, and
closing rules are all going to conflict.

I`m not saying that cannot be solved.  The obvious, trivial solution -
"mdoc blocks cant nest into man blocks and vice versa" - is not
sufficent because you clearly want to permit mdoc content inside .SH
and man content inside .Sh, and maybe even mdoc content inside .RS
and man content inside .Bd.  So non-trivial new scoping, nesting,
and closing rules would have to be developed.

Regarding the social aspects, i agree with Alejandro's goal of
helping transitions, but i also agree with Branden's doubts which
kind of an impression mixed-language pages would make on package
owners having to maintain them.  We just talked about the benefits
of good code as a model for novice authors to look up to, and i
wouldn't relish the idea of people starting to imitage mixed-language
pages.

When processing 2400 pages, the work clearly needs to be split into
manageable chunks.  I think processing one group of pages, then the
next one, and so on, using a translation tool and manual postprocessing,
seems preferable to first changing one macro across all pages, then
the next macro, and so on.

Yours,
  Ingo