The command line is parsed according to the usual GNU convention. The whitespace between a command line option and its argument is optional. Options can be grouped behind a single -- (minus character). A filename of -- (minus character) denotes the standard input.
The groff program allows to control the whole groff system by command line options. This is a great simplification in comparison to the classical case (which uses pipes only).
The physical paper size, giving the actual dimensions of the paper sheets, is controlled by output devices like grops with the command line options -p and -l. See groff_font(5) and the man pages of the output devices for more details. groff uses the command line option -P to pass options to output devices; for example, the following selects A4 paper in landscape orientation for the PS device:
groff -Tps -P-pa4 -P-l ...
The grog(1) program can be used for guessing the correct groff command line to format a file.
The groffer(1) program is an allround-viewer for groff files and man pages.
and
Besides these, there are some internal preprocessors that are automatically run with some devices. These aren't visible to the user.
Details on the naming of macro files and their placement can be found in groff_tmac(5); this man page also documents some other, minor auxiliary macro packages not mentioned here.
The groff extensions to the classical troff language are documented in groff_diff(7)
The groff language as a whole is described in the (still incomplete) groff info file; a short (but complete) reference can be found in groff(7)
There is a shell script nroff(1) that emulates the behavior of classical nroff. It tries to automatically select the proper output encoding, according to the current locale.
The formatter program generates intermediate output; see groff_out(7)
The postprocessor to be used for a device is specified by the postpro command in the device description file; see groff_font(5) This can be overridden with the -X option.
The default device is ps.
Today, most printing or drawing hardware is handled by the operating system, by device drivers, or by software interfaces, usually accepting PostScript. Consequently, there isn't an urgent need for more hardware device postprocessors.
The groff software devices for conversion into other document file formats are
Combined with the many existing free conversion tools this should be sufficient to convert a troff document into virtually any existing data format.
To process a roff file using the preprocessors tbl and pic and the me macro set, classical troff had to be called by
_s_h_# pic foo.me | tbl | troff -me -Tlatin1 | grotty
Using groff, this pipe can be shortened to the equivalent command
_s_h_# groff -p -t -me -T latin1 foo.me
An even easier way to call this is to use grog(1) to guess the preprocessor and macro options and execute the generated command (by using backquotes to specify shell command substitution)
_s_h_# `grog -Tlatin1 foo.me`
The simplest way is to view the contents in an automated way by calling
_s_h_# groffer foo.me
On EBCDIC hosts (e.g. OS/390 Unix), output devices ascii and latin1 aren't available. Similarly, output for EBCDIC code page cp1047 is not available on ASCII based operating systems.
Report bugs to bug-groff@gnu.org. Include a complete, self-contained example that will allow the bug to be reproduced, and say which version of groff you are using.
Three groff mailing lists are available:
Details on CVS access and much more can be found in the file README at the top directory of the groff source package.
There is a free implementation of the
grap
preprocessor, written by
Ted Faber
This document is distributed under the terms of the FDL (GNU Free
Documentation License) version 1.1 or later.
You should have received a copy of the FDL on your system, it is also
available on-line at the
GNU copyleft site
This document is based on the original groff man page written by
James Clark
groff
is a GNU free software project.
All parts of the
groff package
are protected by GNU copyleft licenses.
The software files are distributed under the terms of the GNU General
Public License (GPL), while the documentation files mostly use the GNU
Free Documentation License (FDL).
Due to its complex structure, the groff system has many man pages.
They can be read with
man(1)
or
groffer(1)
AUTHORS
Copyright © 1989, 2002, 2003, 2004, 2005 Free Software Foundation, Inc.
SEE ALSO
The
groff info file
contains all information on the groff system within a single document.
Beneath the detailed documentation of all aspects, it provides
examples and background information.
See
info(1)
on how to read it.