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

[G. Branden Robinson]

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