Troff is a simple yet powerful word processor for Linux systems. It allows you to easily create print-ready documents by compiling source files from the command line. Unlike LaTeX Troff is incredibly lightweight and comes preinstalled on most Linux systems. This tutorial shows you how to use Troff to format PDF documents in Ubuntu.
What is Troff and why use it?
In the basic sense, Troph It is a word processing program that converts code-like text into printable documents. Unlike word processors, Troff does not rely on a "WYSIWYG" model. Instead, it requires you to use specific types of code to handle your formatting.
One of the biggest advantages of this approach is its simplicity. A basic Troff installation will contain everything you need to create a document. Furthermore, its lack of a graphical user interface means you can even create a document over SSH.
Tip: Learn how to redirect GUI applications over SSH In Linux.
Install Troff
Troff is often bundled by default in most Linux distributions. You can check if you have it on your system by running its -h flag. This will display a short list of all the flags that the Troff installation accepts.
troff -h
There are cases where distributions do not bundle Troff by default. In this case, you can install it by searching for the package. “groff”.
This is a re-implementation of the Troff and Nroff programs by the GNU Project, which includes a number of new and modern features.
You can install groff in Ubuntu using the following command:
sudo apt install groff
Create your first Troff document
Similar to source code, each Troff document is a text file containing instructions on how to create a document. This includes page width and margins, as well as character and page spacing.
This level of control allows you to manipulate the program to create any type of document. To simplify this, Troff developers have created "macros" that condense these commands into a simpler format.
One of the most common macros you'll use in Troff is "milliseconds." This will create an article-style document. You can create an "ms" document using the touch command:
touch my-first-document.ms
Since all Troff documents are text documents, you can open the document with a text editor. In my case, I'm using vim. Alternatively, you can use any of these text editors for Linux.
vim my-first-document.ms
Understanding Troff Format
All Troff documents follow a similar structure. Each formatting command you perform must be on a separate line within the content you are trying to format. Thus, a typical Troff document would look like this:
.COMMAND1 This is a piece of content in a Troff document. COMMAND2 This is a different piece of content in a Troff document.
Two of the most basic commands you'll use in milliseconds are .TL and .PP. The former converts your text to a heading and centers it in your document, while the latter formats your text to follow a paragraph-like pattern.
For example, the following snippet uses both TL and .PP commands:
.TL My First Troff Document .PP This is content that I want to look like a paragraph in my final document. It is not a very long content but it is my first Troff document and it is something that I am proud of. It is about three sentences long and it should wrap around the document properly.
From here, create your document by passing your file into Troff.
groff -ms -Tpdf ./my-first-document.ms > output.pdf
Tip: If you prefer something simpler, learn how to Writing in MLA format in Google Docs.
Create bold, italic, and underline text
Just like a regular word processor, most Troff macros provide a number of style commands for customizing your document. For MS, these are .B, .I, .UL, and .BX.
- Command B changes the text to bold.
- The .I command changes text to italics.
- UL and .BX are commands that draw an underline and a box around text, respectively.
Similar to the commands above, using these commands in your document requires separating each style on its own line:
.TL My First Troff Document .PP This is .B content .R that I want to look like a paragraph in my final document. [...]
In this example, I created a new line before the word "content" I added the .B command to change it to bold, then created a new line and added the .R command. This allows Troff to revert to its previous style.
It's important to note that you always need to add the .R command when changing the style. For example, the following snippet won't end with the .I command because Troff didn't see the .R file after it:
.TL My First Troff Document .PP This is .I content that I want to look like a paragraph in my final document. [...]
Create new document sections
Similar to LaTeX, Troff also supports section detection and hierarchy, so you don't need to sort and match the level of each heading when editing.
To create a new section in your document, use the .NH command followed by your heading name.
.TL My First Troff Document .NH My First Heading .PP This is content that I want to look like a paragraph in my final document.
By default, each Troff header has a level value that determines how the program will build and display its content in the final document. You can change this value to adjust the header level.
For example, the following creates a level 2 address directly below the original:
.TL My First Troff Document .NH My First Heading .NH 2 My First Subheading .PP This is content that I want to look like a paragraph in my final document.
Aside from regular numbered headers, Troff can also create empty headers that will still follow the document level hierarchy.
To do this, replace .NH with the SH command:
.TL My First Troff Document .SH My First Heading .SH 2 My First Subheading .PP This is content that I want to look like a paragraph in my final document.
Tip: Learn how to Change margins in Google Docs.
Creating lists in Troff
Troff's simplicity also allows you to customize its behavior to suit your needs. For example, menus don't come by default on Troff or ms macros. However, you can still create a menu by combining a few ms commands.
Each list in Troff consists of three parts: an indent, a bullet, and the content. To create an indent, use the .RS and .RE commands. This will indent the current indent level of any text inside it by four spaces.
RS This is my first item. .RE
The IP command also allows you to set a custom bullet point and the space between it and your text. In this case, I'm setting my bullet point to "[1]" and giving it four spaces.
.RS .IP [1] 4 This is my first item. .RE
.RS .IP [1] 4 This is my first item. .IP [2] 4 This is my second item. .IP [3] 4 This is my third item. .RE
Finally, automate this process by creating a custom macro. For example, the following snippet links my IP command to QW.
.de QW .IP [-] 4 .. .RS .QW This is my first item. .QW This is my second item. .QW This is my third item. .RE
Creating Tables with Preprocessors in Troff
One of the odd things about Troff is that most of its features are present as "initial treatments"For the most part, these are off-the-shelf binaries that work by creating Preprocessor Container Scripts and convert it to low-level Troff code.
Tbl is a great example of a Troff preprocessor. It's a program that manages tables in a document. A basic Tbl container looks like this:
.TS allbox ; cc c. item1 item2 item3 item4 item5 item6 .TE
- The .TS and .TE commands tell Tbl that this is an environment it can read.
- The second line tells the program how to format this table.
- The third line is a space-separated field that specifies the column size and alignment of your table.
- The fourth and fifth lines are tab-separated fields that contain the contents of your table.
Compiling a document using Tbl is a little different from compiling a regular Troff file. First, upload your file:
tbl my-first-document.ms > preprocessed.ms
Next, feed the program output to Troff:
groff -ms -Tpdf ./preprocessed.ms > output.pdf
Finally, automate this process using UNIX pipes:
tbl my-first-document.ms | groff -ms -Tpdf > output.pdf
Frequently Asked Questions:
Q1: Is it possible to use Troff in Windows?
answer. By default, Troff and Groff are not officially ported to Windows. However, you can still use Groff with other GNU tools by Installing the Windows Subsystem for Linux.
Q2: Does Troff have a bibliography tracking feature?
answer. Yes. Referencing is a simple preprocessor that uses an external bibliography file to automatically track references in a Troff document. You can learn more about how it works by visiting its man page by running man referencing.
Q3: How can I fix the “missing DESC” error when compiling Troff?
answer. This issue is likely caused by a missing dependency on your system or an incompatible version file. To fix this, install the appropriate groff package from your distribution's repository.
