LinuxCommandLibrary

troff

Format documents for typesetting and printing

TLDR

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

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

Format output for a PostScript printer using the me macro package, saving the output to a file
$ troff -[me] [path/to/input.roff] | grops > [path/to/output.ps]
copy

Format output as ASCII text using the man macro package
$ troff -T [ascii] -[man] [path/to/input.roff] | grotty
copy

Format output as a pdf file, saving the output to a file
$ troff -T [pdf] [path/to/input.roff] | gropdf > [path/to/output.pdf]
copy

SYNOPSIS

troff [options] [file ...]

PARAMETERS

-a
    Produce an ASCII approximation of the document on standard output.

-b
    Report only if troff is busy or debugging, without actually running.

-C
    Enable compatibility mode; try to emulate older troff versions more closely.

-d *string*
    Define string *string*; same as .ds *string* (see man groff).

-f
    Refrain from preformatting; useful with slow output devices. Equivalent to the '.uf 1' request.

-i
    Read standard input after processing all specified files.

-m *name*
    Prepend the macro file /usr/share/groff/1.22.3/tmac/tmac.*name* to the input files. (default is 'an' or 'ms').

-n *num*
    Number first page *num*.

-o *list*
    Output only pages specified in *list*. *list* is a comma separated list of page numbers and ranges.

-q
    Suppress terminal error messages.

-r *an*
    Set number register *a* to *n*.

-s *n*
    Stop every *n* pages to resume printing when a newline is entered.

-T *name*
    Prepare output for device *name*. Default is ps.

-U
    Disable safe mode.

-v
    Print the version number.

-w *warning*
    Enable *warning*.

-W *warning*
    Disable *warning*.

-z
    Suppress output; only check for errors.

DESCRIPTION

troff is a typesetting system originally developed in the Unix environment. It's a powerful command-line tool used to format documents for output, primarily to printers or other rendering devices. It interprets a markup language, processing input text with formatting commands and producing formatted output. troff is a descendant of the earlier roff program and is part of the GNU troff (groff) package.

It's used for creating technical documentation, man pages, books, and other types of formatted text. While more modern typesetting systems like LaTeX are often preferred, troff remains relevant due to its legacy, its presence in Unix-like systems, and its role in generating man pages. The input language consists of text interspersed with formatting requests, specified by lines starting with a dot (.) character or backslash (\) escape sequences. troff can be customized with macro packages that simplify common formatting tasks. It is a complex tool, requiring a significant learning curve to master.

CAVEATS

troff requires a solid understanding of its formatting language. Errors in the input can lead to unpredictable output, and debugging can be challenging. While part of the groff package, it can still feel quite different than more modern tools. Interoperability with other systems can be limited due to its specialized format.

MACRO PACKAGES

troff relies heavily on macro packages to define formatting styles. Common packages include 'man' (for man pages), 'ms' (a general-purpose macro package), and 'mm' (another general-purpose package). These packages provide predefined commands for headings, paragraphs, lists, and other common document elements.

PREPROCESSORS

troff often works in conjunction with preprocessors like eqn (for mathematical equations), tbl (for tables), and pic (for drawing diagrams). These preprocessors translate their respective input languages into troff commands, which are then processed along with the rest of the document. They are called as pipes to the troff command.

HISTORY

troff was developed by Joe Ossanna at Bell Labs in the early 1970s, evolving from the earlier roff. It was initially intended for phototypesetters. It became a key component of Unix, used for creating documentation and manuals. Over time, various versions and implementations emerged. GNU troff (groff) is a free software implementation that provides a modern, portable, and feature-rich version of troff.

SEE ALSO

groff(1), nroff(1), eqn(1), tbl(1), pic(1)

Copied to clipboard