Re: thesis help

[G. Branden Robinson]

Hello CM,

At 2024-03-01T15:58:25-0500, cm--- via wrote:
> I am hoping to typeset my PhD thesis in troff.  I have found some
> modern resources about writing a thesis with mom, but out of personal
> interest I want to try using a more traditional macro package.
> 
> Initially, I tried using an mm template for "external papers" from
> Gehani [0], p. 306.  Here is a stripped-down version:

To me, this looks more like the example on page 294 (Chapter 8, §2.1,
"Internal and External Papers With All Internal Authors").  Maybe I
have a different printing.

> I tried compiling this with groff, Heirloom troff, and 9base troff.
> Heirloom and 9base pretty much match what's in the book, but the cover
> sheet is at the end and the Heirloom version has an extra blank page.

Often in *roff typesetting, things like tables of contents come at the
end of the document because it is only then that enough information is
known to format them correctly.  This can be true of cover sheets too if
some reason they require information that is not known at the "start" of
the document.  *roff is a single-pass formatter.  However, with scripts,
make(1) files, or tools like mmroff(1), this limitation can be overcome.

When I tried this example, I found that moving the `CS` macro call
earlier, right after `MT`, did not produce the results I expected; the
abstract did not appear on the cover page.  However, checking it against
Heirloom and that formatter's ancestor DWB 3.3 troff, I see that that
appears to be consistent with historical practice.  (It _still_ may be a
bug, however.)

Another problem I get when relocating the `CS` call early in the
document is that the top page margin is wrong thereafter.  DWB and
Heirloom don't mess that up so it looks like a groff mm bug to me.

I see that DWB assumes that the author is affiliated with "AT&T Bell
Laboratories"; groff mm does not.  (Heirloom says "Company Name".)  If I
add an `AF` call to the document, I get appropriate results with groff
mm but not DWB or Heirloom--they're "stuck" with the default.  While a
difference, I do not consider this a bug in groff mm.  It may be a
difference worth noting in the groff_mm(7) man page, however.

For now, it appears that for robustness, and maybe forever if one wants
a document portable to DWB and Heirloom troffs, one should keep the `CS`
call at the end of the document as shown by Gehani.

> This could be fixed by rearranging the pages with ghostscript after
> compiling, but if there is a better way I would like to know it.

There is in groff, at least if you're formatting for PDF.

gropdf(1):

   Device control commands
[...]
     \X'pdf: switchtopage when name'
            Normally each new page is appended to the end of the
            document, this command allows following pages to be inserted
            at a ‘named’ position within the document (see pagename
            command above).  ‘when’ can be either ‘after’ or ‘before’.
            If it is omitted it defaults to ‘before’.  It should be used
            at the end of the page before you want the switch to happen.
            This allows pages such as a TOC to be moved to elsewhere in
            the document, but more esoteric uses are possible.  The
            convenience macro for this command is .pdfswitchtopage.

> The groff output diverges from the book significantly: There is a page
> number header at the top of the first page

I cannot reproduce this.  I'm attaching my test document, which differs
little from yours (but illustrates the use of `pdfswitchtopage`.

> and there is some extra stuff after "Acknowledgement..." which looks
> like this:
> 
>       NHG-nhg                 N. H. Gehani
> 
>       Att.
>       References

Judging by the DWB 3.3 troff manual, this looks like the way the `SG`
macro is supposed to work for memorandum type 0.  Memorandum type 4
should redefine it to be a no-op.  groff mm's implementation evidently
doesn't.  In the meantime (and thereafter, for that matter, since it's
not supposed to do anything for `MT 4` anyway) you can harmlessly leave
out the `SG` call.

> Anyone know what would account for this difference between groff and
> Heirloom/9base?

Independent implementation.  In Git, groff_mm(7) introduces the package
as follows.

     groff mm is intended to be compatible with the mm implementation
     found in the AT&T Documenter’s Workbench (DWB), with the following
     limitations.

     •  Omitted features include the logo and company name strings, }Z
        and ]S, respectively; the encoded company site location
        addresses recognized as the third argument to the AU macro; the
        Pv (“private” heading) register; and the OK (other keywords) and
        PM (proprietary markings) macros.

     •  The CS (output cover sheet) macro is implemented only for
        memorandum type 4.

     •  The grap preprocessor is not explicitly supported; no G1 and G2
        macros are defined.

     •  The registers A, C, E, T, and U, typically set from the troff or
        nroff command lines with DWB mm, are not recognized.

     •  When setting the registers L or W from the command line, use an
        explicit scaling unit to avoid surprises.

     •  DWB mm’s nP macro indented the second line of a paragraph to
        align it with the start of the text of the first (after the
        paragraph number); groff mm’s does not.

     •  Cut marks are not supported.

It then goes on to present some groff mm extensions.

The other mm macro packages in the world have a common ancestor.  It is
not clear to me how much they diverged from each other, but there are
differences between DWB and Heirloom for sure.

> What would be a good way to make groff behave like the other two?

Bug fixes, for a start.

> I am not set on mm, but I would like the document to compile on
> different systems without depending on a particular troff
> implementation; groff seems to be the most ubiquitous.

I am not certain that any mm implementation in the world is maintained
_besides_ GNU's.  DWB has been dead for 30 years, killed in an AT&T
internal screw job documented by Nils-Peter Nelson; Heirloom hasn't seen
a release in five; and as far as I know Plan 9 from User Space maintains
their mm only for the sake of rendering historical Unix and Plan 9
documents--their "tmac.m" file has not changed in literally 20 years,
come this May.  (I was unaware that any Plan 9 docs were written using
mm, though.)

> I also came across this "thesis.me" setup for me macros [1], and I'm
> curious how this would have been used.  Were students intended to copy
> this and use it as a base for their document, compiling with
> "troff -me"?  Or would they include the contents of thesis.me using
> some command line option or troff command?  Just want to be sure I'm
> not missing something subtle or interesting here.

I don't know what was intended by people at UC Berkeley, but either
approach would work.  The facility for doing the latter is the `so`
request.  So a Berkeley thesis might have started as follows.

.so /usr/lib/me/src/thesis.me

> Using troff for my thesis isn't just a means to an end; I'm kind of
> using it as an excuse to do a mini historical research project.  It
> would be cool to reconstruct how a thesis might have been typeset in
> the 80s, while addressing practical concerns like compatibility with
> modern groff.  Besides the questions above, if anyone has any general
> advice or suggestions I'm all ears!

I reckon my advice would be:

1.  Use the latest released version of groff (currently 1.23.0).
2.  Read its documentation.  I've been working on it for 7 years.  :)
3.  Report bugs.
4.  Join as many groff mailing lists as you have bandwidth for, starting
    with groff@gnu.org and adding on bug-groff and/or groff-commit,
    depending on your interests.

Most discussions, code changes, and bug reports don't have to do with
the mm package, though.  It does have users here, though.

I'll have a look at the mm bugs noted above.  If you'd care to share an
appellation less terse than CM, I can credit you accordingly as the
reporter.

Regards,
Branden

br-thesis.mm
Description: application/troff-mm

signature.asc
Description: PGP signature