troff

Format output for a PostScript printer, saving the output to a file

$ troff [path/to/input.roff] | grops > [path/to/output.ps]

$ troff -[me] [path/to/input.roff] | grops > [path/to/output.ps]

$ troff -T [ascii] -[man] [path/to/input.roff] | grotty

$ troff -T [pdf] [path/to/input.roff] | gropdf > [path/to/output.pdf]

troff [options] [file...]

troff is commonly invoked as part of groff:
groff [option...] [file...]

-T name
    Specify the output device or character set. Common values include 'ps' (PostScript), 'dvi', 'html', 'ascii'.

-m name
    Load the specified macro file (e.g., 'ms', 'me', 'mm') before processing input files. These packages provide higher-level commands for document structure.

-o list
    Output only the pages specified in list. The list can be a comma-separated sequence of page numbers or ranges (e.g., '1,3-5,7').

-r CN
    Set the number register C (a single character name) to the value N before processing. Used for defining variables.

-i
    Read standard input after all specified files have been processed.

-z
    Suppress normal output. Useful for checking syntax or defining macros without generating a document.

-F dir
    Search dir for font files.

-M dir
    Search dir for macro files.

-n N
    Start page numbering at N.

-d CS
    Define character C as string S.

file...
    One or more input files to be processed. If no files are specified, troff reads from standard input.

troff (short for 'typesetter roff') is a powerful and highly flexible document formatting system developed at Bell Labs. It reads input text mixed with special formatting commands and produces device-independent output, typically used for high-quality typesetting. Unlike its counterpart nroff, which targets terminal output, troff is designed for graphical output devices like laser printers and phototypesetters. Although the original troff is proprietary, the GNU project provides a free re-implementation called groff, which is the version commonly found on Linux systems. troff is foundational to Unix documentation, including man pages, and allows for precise control over layout, fonts, and graphics through its extensive command set and macro capabilities.

The troff command itself is often an alias or component of the groff suite on modern Linux systems. Direct usage might be limited compared to invoking groff with appropriate options. Mastering troff requires a significant learning curve due to its low-level control and reliance on specific macro packages and preprocessors. Output often requires a separate post-processor (e.g., grops for PostScript) to render the final document.

troff's power is significantly extended by macro packages, which are collections of predefined commands that simplify document structure. Common packages include:
ms: (Manuscript) A general-purpose package for articles and books.
me: (Memorandum) Designed for memos and technical reports.
mm: (Memorandum Macros) Another comprehensive package for various documents.
These packages abstract away low-level formatting details, allowing users to focus on content.

troff documents often integrate content generated by specialized preprocessors that translate specific syntax into troff commands. This allows for complex elements like equations, tables, and diagrams to be easily included:
eqn(1): For mathematical equations.
tbl(1): For creating complex tables.
pic(1): For drawing simple diagrams.
refer(1): For managing bibliographic references.
A typical workflow involves piping the output of preprocessors into troff, then piping troff's output to a post-processor.

troff originated in the early 1970s at Bell Labs, developed by Joe F. Ossanna and later maintained by Brian W. Kernighan. It was a rewrite of roff (which stood for 'runoff') to support the Graphic Systems CAT phototypesetter, marking a significant leap in document typesetting on Unix systems. troff, along with its text-oriented counterpart nroff, became integral to the Unix operating system's documentation and publishing tools. The original proprietary troff was eventually superseded in the open-source world by groff (GNU roff), a free implementation started by James Clark in 1989, which aimed to be compatible with Bell Labs troff while adding extensions.

groff(1), nroff(1), man(1), eqn(1), tbl(1), pic(1), refer(1), grops(1), ms(7), me(7), mm(7)