A physicist guide to using groff 📄

As someone who has used latex extensively but recently learned the "minimalist way", I'll hereby show you a (way) more minimal (10 mB's vs several GB's) alternative to latex called groff.

Groff or GNU troff is the gnu re-design of the unix troff, troff can do basically everything you'd ever want from a typesetting language but as it'd be very difficult to do certain things directly in groff it comes with macros and pre-processors. The ms macros (shortcuts) will be explained in basics, the preprocessors are just what their name tells you they are, they read some label in your document in which you write in a certain easily understandable language and convert that part to proper troff, afterwards you can pass that into troff and compile it into a pdf, latex does this too for bibliographies and if you compile latex from the command line you know what an ugly clusterfuck that is, groff is way more clean. You don't have to install it as it comes pre-installed on every distro I know of.

Basics

To make a groff document make a file that ends with ".ms" (as we'll be using the ms macros) e.g Report.ms, and type the following:

.TL
TitLe
.AU
Your Name (AUthor)
.AI
Your institution (Author Institution)
.NH
New Header
.PP
IFLF: I fucking love FOSS
.NH 2
Sub Header
.PP
FOSS is love, FOSS is life

Go and move to the file in question on the command line and compile it by issuing the command:

$  groff -ms -T pdf Report.ms > Report.pdf

As is explained in the manual (just type "$ man groff") the ms flag asks groff to use the ms macros and the -T flag gives the output "device" (this is still from the old times where this might go to some kind of special CAT) here we choose pdf. for now go ahead and take a look at Report.pdf, doesn't it look great? Now even better, go look at the size of the document. Now if you're like me you a shell script for it called e.g "groffpile" with arguments the ms file and the pdf file, as can be found in my scripts under the folder conversion.

Equations

This is still from a perspective of a physicist, so we'll have to be able to write equations. This is fairly straightforward as it just as in latex with the {} brackets but more "humane" language, I'll give examples below so you'll get the general idea:

This is produced by:

.PP
Of the encapsulating sphere the detector blocks a certain
$theta$:
.EQ
tan( theta ) = 60 over 70 ->
theta = tan sup {-1}  60 over 70 = 0.7086
.EN
So the solid angle is:
.EQ
Omega = int int sub S sin( theta ) d theta d phi = int sub 0
sup 0.7086 sin ( theta ) int sub 0 sup {2 pi} d phi
= 1.5126
.EN

The only thing I skipped over here is that to be able to use the dollar signs to have equations (just like in latex) you'll have to put the following at the start of your document:

.EQ
delim $$
.EN

This uses the eqn preprocessor, so the document would be compiled by just piping it through:

$ eqn -T pdf file.ms | groff -ms -T pdf > file.pdf

Note that eqn needs to know what device we're outputting to for optimal typesetting

Matrix equations

.EQ
left [
matrix {
ccol {
1 above 2 above 3
}
ccol {
1 above 2 above 3
}
}
right ]
cdot
left [
matrix {
ccol {
0 above 2 above 3
}
ccol {
1 above 5 above 3
}
}
right ]
.EN

More on equations

See here

Diagrams

Diagrams are generated with the "pic" preprocessor, and can even be used with latex input commands with the -t flag. If you want to know more, as explained in the 'man' manual, the full manual is at /usr/share/doc/groff-1.22.4/pic.ms .

Embedding Images

To embed an image you first need to convert the image to the output format (in this case pdf) and then use e.g the following macro:
.PDFPIC -C DeltaEPlot.pdf 3i

To compile this you'll need to add the -U flag to groff. Here 3i means "3 inches" as documented in the full groff manual (see "$man 7 groff")

References

I'll write an extensive guide about this someday, but for now have a look at this youtube video. In short use the preprosessor "refer"

back button home button