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
