Re: Macro package loading best practices

[John Gardner]

I tend to begin my documents with the following comment, designed to
illustrate for the author what macro packages are used by the document,
which preprocessors are needed, etc:

.\" uses: -mpdfmark -man -rLL=80 tbl pic eqn

I opt for a *descriptive* directive instead of a *prescriptive* one ("uses:"
instead of "use:"), so folks who format my documents know what
options/preprocessors to use, but avoid interpreting it as a literal
command (which would otherwise make assumptions about the author's Troff
implementation and/or the availability of macro packages and preprocessors).

— John



On Sat, 24 Feb 2024 at 19:04, Larry Kollar <larry.kollar@icloud.com> wrote:

>
> > Dave Kemper <saint.snit@gmail.com> wrote:
> >
> > On 2/22/24, G. Branden Robinson <g.branden.robinson@gmail.com> wrote:
> >> I've come to think that a set of "best practice" for *roff document
> >> composition is to:
> >>
> >> A.  Load your desired full-service macro package (if any) on the command
> >>    line with `-m`.
> >> B.  Load any auxiliary macro packages that your document _requires_
> >>    either on the command line with `-m` or at the very beginning of
> >>    your document with `mso`.
> >
> > Point A is a widespread historical expectation (at least partly
> > because, far enough back in history, troff didn't have .mso), but I
> > don't think it should be generally considered best practice.
> > Command-line options ought to be what the name says: *options*.  Want
> > a different paper size or font family?  Sure, those are options.
> >
> > But in no sense is loading m.tmac optional for -mm documents.  It is
> > absolutely required, so ideally it should not be incumbent on every
> > user who wants to render that document to know which switches to flip
> > to get it to work right, but on the document author to include this
> > within the document.
>
> This is a very good point, and one I should have thought of
> when I read Brandon’s original post last night.
>
> The differences between -man, -ms, and -mm are loosely analogous
> to the XML world’s XHTML, Docbook, and DITA[1]. Nobody with
> the most minimal understanding of either triplet are going to expect
> a single package/transform to handle all three.
>
> But in the case of groff, there’s at least twice as many years of inertia
> (compared to XML) to consider. It really does make sense that an -mm
> based book file should invoke the macro package(s) it needs, but so
> many of us are automatically going to put that -mm on the command
> line (a/k/a “widespread historical expectation”). At least the major
> packages do look to see if they’ve already been invoked before running
> through the whole shebang again.
>
> In the case of those of us who have specialized[2] -ms, it would make
> even more sense to use .mso instead of the command line “option.”
> Our modified package could source s.tmac at the outset.
>
> Now manpages… I seriously doubt we can do much about them.
>
> — Larry
>
> [1] If you want to quibble about the analogy, I’ll likely agree with you.
>
> [2] DITA supports “specialization,” the defining of new elements to
> suit a particular in-house need. Whether groff or XML, the cost is in
> portability.
>
>
>