Re: Use various macro packages in the same page (was: Re: Plan 9 man added a new macro for man page references)

[John Gardner]

>
> But the mdoc(7) and man(7) languages can also be regarded as languages
> with a grammar


I wish people would stop referring to these as "languages". They're macro
packages, plain and simple: their "syntax" is that of the language they're
written in, Roff. How mandoc(1) implements and parses them is immaterial,
especially since mandoc's job isn't to be an implementation of Troff, but
to be a formatter for these two very specialised macro sets, using a
cherry-picked subset of language features.

It's difficult to get newcomers interested in Troff when they're frequently
being told that the program's input language isn't one, but several... only
to find out much later on how they really work, and that the system is less
complex than they initially believed.

On Wed, 4 Aug 2021 at 20:49, Ingo Schwarze <schwarze@usta.de> wrote:

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