Hi Alex, Short answer: yes, but no. Not in this case.
At 2021-08-04T08:59:21+0200, Alejandro Colomar (man-pages) wrote:
> Something that I already had in mind some time ago came to my mind
> again with this. I don't know much of groff, so it may not be
> possible, but I'll ask anyway.
>
> Is it possible to use more than one macro package at the same time?
> (As long as they are compatible, or you use compatible features, of
> course.)
Yes, but...
> I mean like using 2 C includes, <stdlib.h> and <stdint.h>, where you
> get the definitions of functions/macros from both and you can use them
> all. With some exceptions, as for example including both <string.h>
> and <libgen.h> and using basename(3) wouldn't probably work; that's
> what I meant with compatible features.
...no. Because instead of name collisions, the problem mdoc vs. man,
and each of them vs. ms, for that matter, have, is that all three want
to manage the layout of the page. How long it is, what the line length
is, where it breaks, who sets the headers and footers ("titles" in roff
parlance) who's responsible for defining, planting, and if necessary
moving page location and other traps, and probably some things I'm
forgetting.
Here's what groff_tmac(5) in groff Git HEAD says.
Macro packages
Macro packages come in two varieties; those which assume respon‐
sibility for page layout and other critical functions (“major” or
“full-service”) and those which do not (“supplemental” or “auxil‐
iary”). GNU roff provides most major macro packages found in
AT&T and BSD Unix systems, an additional full-service package,
and many supplemental packages. Multiple full-service macro
packages cannot be used by the same document. Auxiliary packages
can generally be freely combined, though attention to their use
of the groff language name spaces for identifiers (particularly
registers, macros, strings, and diversions) should be paid. Name
space management was a significant challenge in AT&T troff;
groff’s support for arbitrarily long identifiers affords few ex‐
cuses for name collisions, apart from attempts at compatibility
with the demands of historical documents.
Man pages
an
man an is used to compose man pages in the format originating
in Version 7 Unix (1979). It has a small macro interface
and is widely used; see groff_man(7).
doc
mdoc doc is used to compose man pages in the format originating
in 4.3BSD-Reno (1990). It provides many more features
than an, but is also larger, more complex, and not as
widely adopted; see groff_mdoc(7).
Because readers of man pages often do not know in advance which
macros are used to format a given document, a wrapper is avail‐
able.
andoc
mandoc This macro file, specific to groff, recognizes whether a
document uses man or mdoc format and loads the correspond‐
ing macro package. Multiple man pages, in either format,
can be handled; andoc reloads each macro package as neces‐
sary.
Because that's fairly deep in the weeds (groff_tmac(5)), I've recently
added some material to groff(1) as well.
Macro packages
Macro files are roff input files designed to produce no output
themselves but instead ease the preparation of other roff docu‐
ments. When a macro file is installed at a standard location and
suitable for use by a general audience, it is termed a macro
package.
Macro packages can be loaded prior to any roff input documents
with the -m option. The groff system implements most well-known
macro packages for AT&T troff in a compatible way, extends them,
and adds some packages of its own. Several of them have one- or
two-letter names due to the intense sense of naming economy prac‐
ticed in early Unix culture. This laconic approach led to many
of the packages being identified in general usage with the nroff
and troff option letter used to invoke them, sometimes to punning
effect, as with “man” (short for “manual”), and even with the op‐
tion dash, as in the case of the s package, much better known as
ms or even -ms.
Macro packages serve a variety of purposes. Some are “full-ser‐
vice” packages, adopting responsibility for page layout among
other fundamental tasks, and defining their own lexicon of macros
for document composition; each such package stands alone and a
given document can use at most one. GNU roff provides the fol‐
lowing such packages.
an is used to compose man pages in the format originating in
Version 7 Unix (1979); see groff_man(7). It can be speci‐
fied on the command line as -man.
doc is used to compose man pages in the format originating in
4.3BSD-Reno (1990); see groff_mdoc(7). It can be speci‐
fied on the command line as -mdoc.
e is the Berkeley general-purpose macro suite, developed as
an alternative to AT&T’s s; see groff_me(7). It can be
specified on the command line as -me.
m implements the format used by the second-generation AT&T
macro suite for general documents, a successor to s; see
groff_mm(7). It can be specified on the command line as
-mm.
om (invariably called “mom”) is a modern package written by
Peter Schaffter specifically for groff. Consult the mom
home page ⟨https://www.schaffter.ca/mom/⟩ for extensive
documentation. She—for mom takes the female pronoun—can
be specified on the command line as -mom.
s is the original AT&T general-purpose document format; see
groff_ms(7). It can be specified on the command line as
-ms.
Others are supplemental. For instance, andoc is a wrapper pack‐
age specific to groff that recognizes whether a document uses man
or mdoc format and loads the corresponding macro package. It can
be specified on the command line as -mandoc. A man(1) librarian
program may use this macro file to delegate loading of the cor‐
rect macro package; it is thus unnecessary for man itself to scan
the contents of a document to decide the issue.
Many macro files augment the function of the full-service pack‐
ages, or of roff documents that do not employ such a package—the
latter are sometimes characterized as “raw”. These auxiliary
packages are described, along with details of macro file naming
and placement, in groff_tmac(5).
I want to slim down the discussion in groff_tmac(5) a bit. It's kind of
a strange page, not so much a specification of a _file format_ (as a
section 5 page should do), as a rambling discourse about what macro
packages are, what *roff input should broadly look like, and what some
specific macro packages that don't have their own dedicated pages do.
A lot of that stuff should probably go to a section 7 page. As I have
been at pains to note, the macro package file format _is_ the (g)roff
input file format; there is no syntactical difference whatsoever. In
that sense I find the mere _existence_ of the groff_tmac(5) page
misleading. I think it fools people into assuming that *roff macro
files are more specialized than they really are.
> Being able to use both mdoc(7) and man(7) in the same file would:
>
> - Remove the need of man(7) for a new semantic .MR macro
> - Easen the transition from man(7) to mdoc(7), as it could be done in
> many small steps, taking first what's most useful from mdoc(7).
>
> I guess (but don't really know) that it's not possible currently, but
> is it something that groff(1) could add as an extension feature?
> Supporting something like `groff -man -mdoc ...`.
That feels like a long pole on a technical basis, and would require man
and mdoc to agree upon on some shared infrastructural basis for page
management. That said, it isn't actually an insane idea; having had to
troubleshoot that exact area of both packages' groff implementations in
the recent past, I can say that I don't think there are many
constraints. For something like ms(7) or mm(7) I think it would be out
of the question. But man pages don't support footnotes or multiple
columnation, which are the biggest headaches in page layout management
I'm aware of. (You can do sophisticated things like drop caps and text
flow around irregular polygons, but no traditional macro package is so
ambitious. Maybe mom(7) is. The minority of people who needed such
things historically resorted to "raw" troff features to get them, I
think.)
The weirder, and maybe ultimately more frustrating problems, would come,
I fear, with unexpected interactions between the two macro sets. It
could be the NON-obvious stuff, not having to do with page breaks or
titles or traps that might screw us up, and might do so repeatedly.
Such a project would also afford Ingo and I more opportunities to argue
and fight more than we already do, so while it might provide enjoyable
entertainment for bystanders, it might not help get real work done any
faster. ;-)
All that aside, think about what specimens of combined-dialect man pages
in the field would do to the level effort demanded to acquire this
fusional language among prospective or novice man page writers. It
makes a hard social problem even harder. I don't think Ingo or I, as
dialectal partisans, relish the idea of the admixture.
So, yeah, for technical as well as personnel reasons, it feels like a
tall hill to climb. We have to measure the opportunity cost: what other
useful things could we be spending the same effort on?
Regards,
Branden
signature.asc
Description: PGP signature
