1.8 Conventions Used in This Manual

We apply the term “groff” to the language documented here, the GNU implementation of the overall system, the project that develops that system, and the command of that name. In the first sense, groff is an extended dialect of the roff language, for which many similar implementations exist. We say “the formatter” when speaking of behavior that is generally true of troff and nroff programs.

A tradition has arisen that GNU programs’ names bear a prefix ‘g’ where necessary to distinguish them from other implementations on the host system (see Environment). Thus, for example, geqn is GNU eqn. On operating systems that lack a troff of different provenance, this prefix is omitted; GNU troff is the only troff available. Exceptionally, ‘groff’ always retains its leading ‘g’.

We call non-GNU troff systems AT&T troff because that is the common origin of almost all troff implementations³ (with more or less compatible changes). Similarly, we say ‘gpic’, ‘geqn’, and so on.

This manual employs Emacs names for non-graphic keycap engravings on the alphabetic section of the keyboard. “RET” is Return or Enter, and “SPC” is the space bar.

The roff language features several major syntactical categories within which many items are predefined. Presentations of these items comprise the name of the category followed by a colon and the form in which the item is most commonly used.

Register: \n[example]

The register ‘example’ is one that that groff doesn’t predefine. You can create it yourself, though; see Setting Registers.

To make this document useful as a reference and not merely amiable bedtime reading, we tend to present these syntax items in exhaustive detail when they arise. References to topics discussed later in the text are frequent; skim material you haven’t mastered yet.

We use Texinfo’s “result” (⇒) and error→ notations to present output written to the standard output and standard error streams, respectively. Diagnostic messages from the GNU troff formatter and other programs are examples of the latter, but the formatter can also be directed to write user-specified messages to the standard error stream. The notation then serves to identify the output stream and does not necessarily mean that an error has occurred.⁴

$ echo "Twelve o'clock and" | groff -T ascii | sed '/^$/d'
    ⇒ Twelve o'clock and
$ echo '.tm all is well.' | groff > /dev/null
    error→ all is well.

Sometimes we use ⇒ abstractly to represent formatted text that you will need to use a PostScript or PDF viewer program (or a printer) to observe. While arguably an abuse of notation, we think this preferable to requiring the reader to understand the syntax of these page description languages.

We also present diagnostic messages in an abbreviated form, often omitting the name of the program issuing them, the input file name, and line number or other positional information when such data do not serve to illuminate the topic under discussion.

Most examples are of roff language input that would be placed in a text file. Occasionally, we start an example with a ‘$’ character to indicate a shell prompt, as seen above.

We encourage you to to try the examples yourself, and to alter them to better learn groff’s behavior. Our examples sometimes need to direct the formatter to set a line length (with ‘.ll’) that fits within the page margins of this manual. We mention this so that you know why it is there before we discuss the ll request formally.⁵

We refer occasionally to man pages, in which aspects of the groff system or of its operating environment are further documented.⁶ When you see a citation like groff_man(7), understand that you can type ‘man groff_man’ at the command line to view it. The numbered category distinguishes pages by their purpose. You can try ‘man 'groff(1)'’ and ‘man 'groff(7)'’ to observe this distinction.⁷ Your system likely offers an intro(1) page that will help you make the most of this resource.