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.robin...@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.robin...@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 >