Understanding the `groff` Command in Linux

The groff command in Linux is a document formatting system that reads plain text mixed with formatting commands and produces formatted output. The name groff stands for "GNU troff," which is a GNU implementation of the troff program (a typesetting system not unlike TeX but predating it).

Syntax

The basic syntax of the groff command is:

groff [OPTIONS] [FILES]...

Options

Here's a table of common groff options:

Option	Shorthand	Description
--version		Show version information.
--help		Show a help message.
-T[DEVICE]		Set the output device. Common devices are ps, pdf, html, etc.
-m[MACRO]		Use the specified macro package.
-M[DIR]		Add the specified directory to the search path for macro files and devices.
-e		Preprocess with eqn (equations).
-t		Preprocess with tbl (tables).
-p		Preprocess with pic (pictures).
-s		Preprocess with soelim.
-P[PRINTER]		Send the output to the specified printer.

Creating a Sample Text File with vim

To create a groff text file using vim, open the terminal and type:

vim sample.groff

Once in vim, press i to switch to insert mode and enter the following text as an example:

.TL
Groff Example
.AU
John Doe
.AI
Linux Documentation
.PP
This is a simple paragraph in our .groff document. The groff typesetting system is quite powerful.

To save and exit vim, press Esc, then type :wq and press Enter.

Examples of Using groff

Example 1: Formatting Text to PostScript

groff -Tps -ms sample.groff > sample.ps

This command will format the sample.groff file using the -ms macros and set the output device to PostScript, redirecting the output to sample.ps.

Example 2: Viewing the Output as a PDF

After generating the PostScript file, you can view it as a PDF using ps2pdf ( which is part of Ghostscript):

ps2pdf sample.ps sample.pdf

Then open sample.pdf with your preferred PDF viewer.

Example 3: Creating HTML Output

groff -Thtml -ms sample.groff > sample.html

This will create an HTML file from the groff file.

Example 4: Using Preprocessors

If your groff file contains tables, equations, or pictures, you might need to use preprocessors like tbl, eqn, or pic. Here's how to use them:

groff -Tps -ms -te sample.groff > sample.ps

In this command, -te tells groff to preprocess the document with tbl for tables and eqn for equations.

Combining groff with Other Commands

You can also combine groff with other Unix commands, for instance, viewing the output directly in a terminal using groffer:

groffer --text sample.groff

Tips for Using groff

• groff can seem complex due to its multitude of options and macros, but starting with simple documents and gradually introducing more elements can help you learn its functionality.
• There are several macro packages available, such as -ms, -mm, and -me, each designed for different types of documents. Choosing the right macro package is crucial.
• As with most document preparation systems, it is often useful to review the output in a viewer to make sure formatting is correct.

The groff command offers a powerful system for typesetting documents and creating various output formats from plain text sources. While it has a steeper learning curve than other text formatting systems, it provides fine-grained control over document presentation, making it a valuable tool for complex text processing tasks in Linux.

What Can You Do Next 🙏😊

If you liked the article, consider subscribing to Cloudaffle, my YouTube Channel, where I keep posting in-depth tutorials and all edutainment stuff for software developers.