By default, the groffer program collects all input into a single
file, formats it with the groff program for a certain device, and
then chooses a suitable viewer program. The device and viewer
process in groffer is called a mode. The mode and viewer of a
running groffer program is selected automatically, but the user
can also choose it with options. The modes are selected by
option the arguments of --mode=anymode. Additionally, each of
this argument can be specified as an option of its own, such as
anymode. Most of these modes have a viewer program, which can be
chosen by the option --viewer.
Several different modes are offered: graphical modes for the X
Window System, text modes, and some direct groff modes for
debugging and development.
By default, groffer first tries whether x mode is possible, then
ps mode, and finally tty mode. This mode testing sequence for
auto mode can be changed by specifying a comma separated list of
modes with the option --default-modes.
The searching for man pages and the decompression of the input
are active in every mode.
Graphical display modes
The graphical display modes work mostly in the X Window System
environment (or similar implementations within other windowing
environments). The environment variable DISPLAY and the option
--display are used for specifying the X Window System display to
be used. If this environment variable is empty, groffer assumes
that the X Window System is not running and changes to a
text mode. You can change this automatic behavior by the option
--default-modes.
Known viewers for the graphical display modes and their standard
X Window System viewer programs are
* in a PDF viewer (pdf mode)
* in a web browser (html, xhtml, or www mode)
* in a PostScript viewer (ps mode)
* X Window System roff viewers such as gxditview(1) or
xditview(1) (in x mode)
* in a DVI viewer program (dvi mode)
The pdf mode has a major advantage — it is the only graphical
display mode that allows searching for text within the viewer;
this can be a really important feature. Unfortunately, it takes
some time to transform the input into the PDF format, so it was
not chosen as the major mode.
These graphical viewers can be customized by options of the X
Window System Toolkit Intrinsics. But the groffer options use a
leading double minus instead of the single minus used by the X
Window System Toolkit Intrinsics.
Text modes
There are two modes for text output, mode text for plain output
without a pager and mode tty for a text output on a text terminal
using some pager program.
If the variable DISPLAY is not set or empty, groffer assumes that
it should use tty mode.
In the actual implementation, the groff output device latin1 is
chosen for text modes. This can be changed by specifying option
-T or --device.
The pager to be used can be specified by one of the options
--pager and --viewer, or by the environment variable PAGER. If
all of this is not used the less(1) program with the option -r
for correctly displaying control sequences is used as the default
pager.
Special modes for debugging and development
These modes use the groffer file determination and decompression.
This is combined into a single input file that is fed directly
into groff with different strategy without the groffer viewing
facilities. These modes are regarded as advanced, they are
useful for debugging and development purposes.
The source mode with option --source just displays the
decompressed input.
Option --to-stdout does not display in a graphical mode. It just
generates the file for the chosen mode and then prints its
content to standard output.
The groff mode passes the input to groff using only some suitable
options provided to groffer. This enables the user to save the
generated output into a file or pipe it into another program.
In groff mode, the option -Z disables post-processing, thus
producing the groff intermediate output. In this mode, the input
is formatted, but not postprocessed; see groff_out(5) for
details.
All groff short options are supported by groffer.
