roff

groff [option...] [file...]

-Tdevice
    Specifies the output device. Common values include `ps` (PostScript), `ascii` (plain text for terminals, similar to nroff), `html`, `dvi`, and `pdf`.

-mname
    Loads the specified macro package `name`. Examples include `man` (for manual pages), `mdoc` (another manual page format), `ms` (for manuscripts), and `mm` (for memoranda).

-rCN
    Sets a string register `C` to the numerical value `N`. Registers are variables used for storing numbers or strings within roff documents.

-e
    Enables the `eqn` preprocessor, used for typesetting mathematical equations.

-p
    Enables the `pic` preprocessor, used for creating simple diagrams and line drawings.

-t
    Enables the `tbl` preprocessor, used for formatting tables.

-opages
    Outputs only the specified pages. The `pages` argument is a comma-separated list of page ranges (e.g., `1-5,7,10-`).

-l
    Sends the formatted output directly to the default printer using `lpr`.

-Idir
    Adds `dir` to the search path for macro files and other `groff`-related resources.

The roff system is a powerful text formatting framework, a descendant of the original `runoff` program from the mid-1960s. On modern Linux systems, the functionality of roff is primarily provided by the groff (GNU roff) project. It is not a single executable command in the way `ls` or `grep` are, but rather a sophisticated suite of tools and a markup language designed for producing high-quality textual output for various devices, from terminals to printers.

roff processes source text files embedded with formatting requests and macros to generate formatted output. It's widely used for creating manual pages (`man` pages), books, reports, and other technical documentation. The core concept involves separating content from presentation, allowing authors to focus on writing while roff handles the layout, typography, and pagination based on defined styles or macro packages.

The roff system has a steep learning curve due to its powerful but complex syntax and the necessity of understanding specific macro packages or raw roff requests. While incredibly robust for technical documentation, it's generally less user-friendly for casual document creation compared to modern word processors or simpler markup languages like Markdown. Debugging formatting issues can also be challenging.

roff itself provides a low-level set of formatting requests. To simplify document creation, developers created collections of higher-level commands called 'macro packages'. These packages encapsulate common formatting tasks (like headings, paragraphs, lists) into easy-to-use macros. Key macro packages include `man` and `mdoc` (for manual pages), `ms` (manuscript format), and `mm` (memoranda format). Using a macro package allows authors to write documents with logical structure, letting the package handle the intricate `roff` commands for proper presentation.

The roff system is often used in conjunction with various preprocessors that handle specialized content before the main `groff` (or `troff`/`nroff`) processing stage. These preprocessors translate specific markup into roff requests. Common preprocessors include eqn for mathematical equations, tbl for tables, and pic for diagrams. There are also `refer` for bibliographic references and `grap` for plotting data. The typical workflow involves piping the output of one or more preprocessors to the main `groff` command: `eqn_file | tbl_file | groff -m macro_pkg > output`.

The origins of roff trace back to the `runoff` program developed by Jerome Saltzer for the CTSS operating system in 1964. This was later rewritten for Unix by Joe Ossanna as `troff` (for typesetting) and `nroff` (for terminal output) at Bell Labs in the early 1970s. These tools became fundamental to the Unix ecosystem, particularly for creating system documentation and man pages. The GNU Project developed groff (GNU roff) in the late 1980s, primarily by James Clark, as a free software replacement that largely superseded the original Bell Labs versions. groff is now the standard roff implementation on Linux and other free Unix-like systems, continuing its legacy as a vital tool for high-quality text formatting.

groff(1), man(1), nroff(1), troff(1), tbl(1), eqn(1), pic(1), man(7), mdoc(7)