2.6 Invocation Examples

roff systems are best known for formatting man pages. A man librarian program, having located a page, might render it with a groff command.

$ groff -t -m an -T utf8 /usr/share/man/man1/groff.1

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

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

$ pic foo.me | tbl | troff -m e -T utf8 | grotty

Shorten this pipeline to an equivalent command using groff.

$ groff -p -t -m e -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 -T utf8 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, permitting transmission of arbitrary arguments. 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.