Re: groff Digest, Vol 233, Issue 1

[Riza Dindir]

You might also use the ms macro package for your thesis.

I do not need to mention, but... You can create macros for use in your
thesis, for instance chapter headings, section headings. Pic, eqn, and tbl
are helpers here for diagrams and the like.

Back in the day, when I wrote my thesis I had to use TeX. If I had known,
and had a unix/linux machine at hand, I would have used troff/groff and
most probably the ms macro package and added some extensions to change the
chapter and section headings. And diagrams, it was problematic on windows
to do diagrams using TeX. With troff/groff it would have been easier. That
is my opinion of course.

I have been using ms for creating simple reports for some time now, and it
served me well.

On Sat, Mar 2, 2024 at 8:02 PM <groff-request@gnu.org> wrote:

> Send groff mailing list submissions to
>         groff@gnu.org
>
> To subscribe or unsubscribe via the World Wide Web, visit
>         https://lists.gnu.org/mailman/listinfo/groff
> or, via email, send a message with subject or body 'help' to
>         groff-request@gnu.org
>
> You can reach the person managing the list at
>         groff-owner@gnu.org
>
> When replying, please edit your Subject line so it is more specific
> than "Re: Contents of groff digest..."
>
>
> Today's Topics:
>
>    1. thesis help (cm@sdf.org)
>    2. Re: thesis help (G. Branden Robinson)
>    3. Re: thesis help (Damian McGuckin)
>
>
> ----------------------------------------------------------------------
>
> Message: 1
> Date: Fri, 1 Mar 2024 15:58:25 -0500
> From: cm@sdf.org
> To: groff@gnu.org
> Subject: thesis help
> Message-ID: <ZeJBcZ6M1cWdGiS+@styx.my.domain>
> Content-Type: text/plain; charset=us-ascii
>
> Greetings,
>
> 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:
>
> .SA 1
> .FD 1
> .ND "m, d, y"
> .TL
> Title of Paper
> .AU "N. H. Gehani" NHG
> .AS 1
> Abstract...
> .AE
> .MT 4 1
> .H 1 Introduction
> Text...
> .H 1 Conclusions
> Conclusion...
> .H 1 Acknowledgement
> Acknowledgement...
> .SG nhg
> .NS 3
> References
> .NE
> .SK
> .H 1 References
> .VL 1.5i 0.5i
> .LI ref-mark
> reference...
> .LE
> .CS
>
> 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.
> 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.
>
> The groff output diverges from the book significantly: There is a page
> number header at the top of the first page and there is some extra
> stuff after "Acknowledgement..." which looks like this:
>
>         NHG-nhg                 N. H. Gehani
>
>         Att.
>         References
>
> Anyone know what would account for this difference between groff and
> Heirloom/9base?  What would be a good way to make groff behave like
> the other two?
>
> 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 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.
>
> 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!
>
> CM
>
> [0] N. H. Gehani, Document Formatting and Typesetting on the UNIX System,
> Silicon Press, 1987
> [1]
> https://www.tuhs.org/cgi-bin/utree.pl?file=3BSD/usr/lib/me/src/thesis.me
>
>
>
> ------------------------------
>
> Message: 2
> Date: Sat, 2 Mar 2024 02:01:19 -0600
> From: "G. Branden Robinson" <g.branden.robinson@gmail.com>
> To: groff@gnu.org
> Subject: Re: thesis help
> Message-ID: <20240302080119.7bl36tvwxwelzwmb@illithid>
> Content-Type: text/plain; charset="utf-8"
>
> 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
> -------------- next part --------------
> A non-text attachment was scrubbed...
> Name: br-thesis.mm
> Type: application/x-troff-mm
> Size: 406 bytes
> Desc: not available
> URL: <
> https://lists.gnu.org/archive/html/groff/attachments/20240302/75a21dc1/attachment.bin
> >
> -------------- next part --------------
> A non-text attachment was scrubbed...
> Name: signature.asc
> Type: application/pgp-signature
> Size: 833 bytes
> Desc: not available
> URL: <
> https://lists.gnu.org/archive/html/groff/attachments/20240302/75a21dc1/attachment.sig
> >
>
> ------------------------------
>
> Message: 3
> Date: Sat, 2 Mar 2024 20:41:09 +1100 (AEDT)
> From: Damian McGuckin <damianm@esi.com.au>
> To: groff@gnu.org
> Subject: Re: thesis help
> Message-ID: <88abd23-4ccf-2c34-f656-851e4cfb1ea9@esi.com.au>
> Content-Type: text/plain; format=flowed; charset=US-ASCII
>
>
> Hi CM,
>
> On Sat, 2 Mar 2024, G. Branden Robinson wrote:
>
> >> Initially, I tried using an mm template for "external papers" from
> >> Gehani [0], p. 306.  Here is a stripped-down version:
>
> I have used *roff with MM for 40+ years. I have not used cover sheet stuff
> 39+ years ago. I have used it for a thesis, helped others who used it for
> their theses, but have primarily used it (or help others use it) for 100s
> of documents, reports, papers, memoranda, letters, invoices and (back when
> I sent them), faxes.
>
> >> 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.
>
> I use 'pdftk' to mess with page ordering.  Easy.
>
> BR - Damian
>
>
>
> ------------------------------
>
> Subject: Digest Footer
>
> _______________________________________________
> groff mailing list
> groff@gnu.org
> https://lists.gnu.org/mailman/listinfo/groff
>
>
> ------------------------------
>
> End of groff Digest, Vol 233, Issue 1
> *************************************
>