2.6 Invocation Examples

roff systems are best known for formatting man pages. Once a man librarian program has located a man page, it may execute a groff command much like the following.

groff -t -man -Tutf8 /usr/share/man/man1/groff.1

The librarian will also pipe the output through a pager, which might not interpret the SGR terminal escape sequences groff emits for boldface, underlining, or italics; see the grotty(1) man page for a discussion.

To process a roff input file using the preprocessors gtbl and gpic and the me macro package in the way to which AT&T troff users were accustomed, one would type (or script) a pipeline.

gpic foo.me | gtbl | gtroff -me -Tutf8 | grotty

Using groff, this pipe can be shortened to an equivalent command.

groff -p -t -me -T utf8 foo.me

An even easier way to do this is to use grog to guess the preprocessor and macro options and execute the result by using the command substitution feature of the shell.

$(grog -Tutf8 foo.me)

Each command-line option to a postprocessor must be specified with any required leading dashes ‘-’ because groff passes the arguments as-is to the postprocessor; this permits arbitrary arguments to be transmitted. For example, to pass a title to the gxditview postprocessor, the shell commands

groff -X -P -title -P 'trial run' mydoc.t

and

groff -X -Z mydoc.t | gxditview -title 'trial run' -

are equivalent.