Re: Macro package loading best practices

[G. Branden Robinson]

Hi Dave, Larry, and John,

At 2024-02-23T09:07:42-0600, Dave Kemper 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.
> 
> There are exceptions, of course.  Users rarely render man pages with a
> groff command, and the man frontend takes care of the groff switches.
> I seem to recall that at least one of the historical macro packages
> assumes that it's specified on the command line and initializes
> something differently if not.

More precisely, full-service macro packages take different approaches to
initialization.

Some, like mm, expect to be loaded via the command line.  I haven't
rigorously verified this, but it seems to be the case that,
historically, *roff formatters processed all command-line register and
string definitions (`-r` and `-d` options) before processing any `-m`
options.  mm relied upon this to gather parameters from the user; the
very act of loading the macro package initialized it.

Others, like ms, expect to be loaded via the command line, but don't
initialize (or, not completely) at that point.  They instead expect a
bunch of register configuration to take place before some kind of
"starting macro", which then completes initialization.

The parameters that are really important for full-service packages are
things like the type size, vertical spacing, and page dimensions and/or
margins.  These can influence where the first piece of formatted text
gets written (and on trap placement), and that's why this is an
important issue.

> But absent one of those exceptions, it doesn't seem groff
> documentation should recommend, as a best practice, requiring every
> user to specify one or more -m options for things that aren't
> optional.  The document author, not the user, should be the one
> specifying the document's required macro package(s).

It occurs to me that I could document the following techniques for
coping with the foregoing two approaches.

$ groff foobar.mm
.nr L 8i
.nr W 5.5i
.nr O 0.75i
.nr S 11p
.nr V 13.5p
.mso m.tmac
.H 1 Introduction
Hello, world!

$ groff foobar.ms
.mso s.tmac
.nr LL 5.5i
.nr PO 0.75i
.nr PS 11p
.nr VS 13.5p
.NH 1
Introduction
.LP
Hello, world!

And, for completeness, here are the command-line "equivalents":

$ groff -rL=8i -rW=5.5i -rO=0.75i -rV=13.5p -mm foobar.mm
.H 1 Introduction
Hello, world!

$ groff -ms foobar.ms
.nr LL 5.5i
.nr PO 0.75i
.nr PS 11p
.nr VS 13.5p
.NH 1
Introduction
.LP
Hello, world!

Viewed this way, mm's approach seems more flexible.

I'll have to experiment with these to ensure that they work as I expect.
If so, I reckon I'll end up with some material much like the foregoing.

(I've noted with puzzlement more than once that ms has no `PL` register
recording the page length.  Maybe adding it would make sense to support
"continuous rendering"/infinite page length on terminals.)

At 2024-02-23T22:19:18-0500, Larry Kollar wrote:
> 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.

I don't have a response to this, except to note that it solidly
reinforces Dave's observations.

> Now manpages… I seriously doubt we can do much about them.

Probably not, as long as mandoc(1) is around to fly the banner of
liberating man pages from *roff tyranny.  At least it does a superior
job to its many forebears who bore that colorful standard unsteadily
into a fiery crevasse.

At 2024-02-28T07:57:07+1100, John Gardner wrote:
> 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

Why not refer to the preprocessors by their options?  -t -p -e?

FYI, there shouldn't ever be any reason to load pdfmark.tmac with either
man page package.  Not if you're writing for portability anyway.

groff man(7) (in 1.23.0) and mdoc(7) (in Git) now automatically
hyperlink everything that they should.  I'm still working on
anchor/bookmark autogeneration in mdoc, but I expect to land that soon
for document/section/subsection titles.  As always, managing state
correctly when formatting a collection of man pages is the tricky part.
Once that's done, I expect I'll sort out the device/\X copy mode thing.

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

I'd say that's one of multiple legitimate approaches.

Regards,
Branden

signature.asc
Description: PGP signature