Re: Macro package loading best practices

[John Gardner]

Hi Branden,

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


Because those preprocessor options won't necessarily be available in every
Troff implementation; e.g., Heirloom and Neatroff. Even worse, they could
mean different things altogether, like -t and -p did in otroff.

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.


Sorry, I gave a really shite example to illustrate how multiple macro
packages might be specified (and that was the first thing I thought of,
lol).

But apropos(1) of portability, I'm already toying with a pure PostScript
library small enough to embed in Roff documents that essentially provides a
low-level interface to the pdfmark operator. As in, Adobe Distiller's
extension to the PostScript language that serves as the basis for all
PDF-specific features not supported in traditional PostScript.

Sorry, I'm rambling. Time for me to shaddap.

— John

On Wed, 28 Feb 2024 at 09:07, G. Branden Robinson <
g.branden.robinson@gmail.com> wrote:

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