Why use groff/troff?
You might have heard about writing documents in LaTeX or you may already be using it, however, it is time to learn something new because LaTeX is bloated! Seriously, if you've ever downloaded LaTeX, haven't you ever wondered why the full texlive package is 2.2 GB in size, well because it is complete bloat! Groff (pronounced g-roff or groff) is much more extensible and versatile than LaTeX or any other kind of software for writing documents. I would like to point out that groff is actually roff for GNU systems (hence the g as in GNU), and troff is roff for non-GNU systems. Groff is commonly used for writing man pages, however, you can do much more as you will soon find out. You can easily open up the command line or any terminal alongside your favorite text editor and start writing documents instantaneously. Compiling groff documents using whatever compilation software that you might use is way more efficient and faster than compiling documents in LaTeX, if you don't believe me try it for yourself.
Installing packages
By default groff should come pre-installed on whatever variant of GNU/Linux you may be running, so you don't actually need to install anything. That is what makes groff so superior to other document-writing applications, not to mention it is more Unix compliant as well. Whenever you can, always use the built-in GNU utilities over some other arbitrary applications. In case it isn't already installed, you can follow the steps down below to install it on your system.
On GNU/Linux
For Debian-based distros (Ubuntu, Debian, etc.):
$ sudo apt-get install groffFor Arch-based distros (Parabola, Manjaro, Antergos, etc.):
$ sudo pacman -S groffSimilar to LaTeX, compiling isn't much different except it is way faster (nearly instantaneous), which is just one of the manifold advantages of using this program. For compiling groff documents, you will most likely want it in a pdf format, rather than the default postscript format that it compiles to. To compile a groff document into a pdf (assuming you want to use the ms macros), you can run the following command:
$ groff -ms groff.ms -T pdf > groff.pdfOn Windows
If you are interested in using GNU utilities such as groff on Windows, then you should really consider switching over to GNU/Linux. But if you don't want to make that switch for whatever reason, then you can still download and install the packages here (choose the complete package setup).
On MacOS
Groff should also come pre-installed on MacOS, so you can use it just like on GNU/Linux. But it can be pretty outdated depending on the version of your MacOS, hence you might want to install it from HomeBrew on here.
Basic Document Formatting
Similar to LaTeX, when defining a tag, you must place it on its own line and it should always come first. The tags that you will most likely need are included down below, such as: title, paragraph, bold, italics and more. If for whatever reason you want to define your own macros, you can do that too, but you would have to put them in a separate file or at least that is what you would ideally want to do. The reason you have to use specific tags, is because groff isn't your typical "what you see is what you get" editor such as: Microsoft Word, LibreOffice, etc. So for groff to properly format your document, you need to define these commands for it to do so. The tags work more as functions, so when you go to compile the document it know how to interpret the lines of text.
Basic Formatting
I personally use the ms macros (more about that down below), so that is why I will use the extension .ms at the end of my file. I will also be writing this groff document inside of vim, but you can practically use whatever text editor you want. Keep in mind when using groff though, that all the commands always come at the beginning of the line. It may look a little weird at first, but it's like this so that when you're compiling the document, groff will know what is what so it can properly format the title, headings, etc. The commands for bold, italic, etc. can take in three arguments: (1) the characters or words you're bolding, (2) the thing that goes right after and (3) the thing that goes right before. This is the conventional format that you would want to write documents in:
$ vim groff.ms
.TL
Title of your groff document
.AU
Your name
.AI
Your institution
.AB
This is an abstract.
.AE
.SH
Section heading is unnumbered
.PP
This is an indented paragraph.
.NH
Numbered section heading on the first level
.NH 2
Numbered subsection heading at the second level
.PP
Put the following words in quotation marks and on their own line to appear as
.B "bold text"
in this sentence. Mind you, this will all be on the same line. Do this to have
.B "bold text in parenthesis" ) (
look like this. The bold function is taking in the three arguments as explained above. Here
.I "italic text"
will continue the paragraph, just keep writing on the next line. If you want to
.UL "underline text" ,
and get the comma right after the quotation marks, you have to insert it as a second argument.
.BX "This text is boxed"
and the logic works the same for all functions when formatting in groff.
.IP \(bu 2
This is a properly formatted list item
.IP \(bu 2
Make sure that you add list items this way so they appear indented with bullet points
Now you can compile the document into a pdf format by using the command above (under installation).
Intellectual Mathematical Formatting with eqn (groff/troff)
Groff comes with many preprocessors, one of which is eqn and this one allows you to do pro-mathematical formatting when writing essays. With eqn, you can easily write any mathematical notation without having to do any weird formatting that you would typically have to do, such as in Microsoft Word or in LibreOffice. By calling the eqn function within the groff document, this will call the eqn preprocessor to do the special formatting, ultimately allowing you to add properly formatted mathematical equations to your document. At first glance it might seem a bit complicated on how to write the syntax when using the eqn function, but you basically want to write the mathematical equations the same way you would say it aloud. For example, the quadratic equation could be said in words like this: "x is equal to negative b plus or minus the square root of b squared minus 4ac over 2a". When placing something over an integer for example, you have to specify what part of the equation will go over, so you must put that section in curly brackets as shown below. Make sure that you put the block of code in between .EQ and .EN so that the function eqn will be called upon, when you go to compile the document. You can implement the following logic of expressing mathematical notations with the basic formatting of a groff document from above.
Formatting Mathematical Equations
It should be noted that groff doesn't care about spaces or the number of lines that you use for various expressions, it automatically does all of that for you. Which is pretty nice because that explicitly allows you to write mathematical notations however you like. If you write various equations under the same .EQ and .EN block, they will appear on the same line. So in order to separate them, you would have to use separate .EQ and .EN blocks and that would put each equation on its own line. Also, when using any Greek letters such as: π, φ, θ, etc. you can literally write their names out as pi, phi, etc. and that will properly format them in. Lastly, there should be spaces in between the parentheses at the beginning and at the end, otherwise the expressions might not come out properly formatted. If you are further interested on what else, you could do, have a look at the official documentation on here.
This is how you would write the quadratic formula using eqn in a groff document:
$ vim eqn.ms
.EQ
x = { -b +- sqrt { b sup 2 -4ac } } over 2a
.EN
This is how you would write the pi formula using eqn in a groff document:
$ vim eqn.ms
.EQ
pi = int from -1 to 1 dx over sqrt {1-x sup 2}
.EN
This is how you would write the standard deviation formula using eqn in a groff document:
$ vim eqn.ms
.EQ
s = sqrt { {sum from i=1 to N ( x sub i - x bar ) sup 2} over N-1 }
.EN
Another useful feature in groff can be setting macros, in case you are going to write the same equation or part of an equation over and over again. Let's say you would want to reuse the discriminant from the quadratic formula over and over again; instead of writing it out every time you go to use it, you can just set it as a macro and call upon it whenever you need it. Down below I defined my macro as disc (you can name your macro whatever you want) and then I put the discriminant inside of the grave accents. That way whenever I want to use it, I can just call the variable disc inside of the .EQ and .EN block, and that will print out the thing I assigned the variable to (in this case being disc).
$ vim eqn.ms
.EQ
define disc `b sup 2 -4ac`
.EN
.EQ
disc
.EN
The last thing I would like to touch upon, is using in-line code when writing a basic essay or something of that sort. When writing a paragraph, to get the code to show up inside of your sentence, you have to set a delimiter. That is because the eqn preprocessor is solely looking at what is in between the blocks of .EQ and .EN, so by default it can't handle in-line code. But when you set the delimiter to anything such as $$ or @@, it will process whatever is found in between those two characters. This could cause conflict though, when you go to use the same characters for something other than processing equations with eqn. To handle this problem is relatively simple, all you have to do is turn off the delimiter before you go to use it again for something else, and that will allow you to use it again for some other use case.
$ vim eqn.ms
.EQ
delim $$
.EN
.PP
This is a paragraph.
Here are some more sentences.
Here is the discriminant: $b sup 2 -4ac$
The equation between the delimiter will be printed.
.EQ
delim off
.EN
Now the delimiter is turned off and it won't interfere with the next sentence.
Your ice cream costs $3 more than mine.
The first command that I have provided above for compiling a groff document is for basic compilation without the use of the eqn preprocessor. For compiling groff documents in other macro packages, have a look at the bottom of man groff in your terminal for more information. They all essentially work the same, however, I've decided to use the ms macro for this guide. Nevertheless, to compile a groff document with eqn (using the ms macros), you can run either one of two commands:
$ groff -e eqn.ms -ms -T pdf > eqn.pdf
$ eqn eqn.ms -T pdf | groff -ms -T pdf > eqn.pdf