Conventions Used in This Manual (The GNU Troff Manual)

### 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.

The `roff` language features several major categories for which many items are predefined. Presentations of these items feature the form in which the item is most commonly used on the left, and, aligned to the right margin, the name of the category in brackets.

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; skip material you don’t understand 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.2

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

Sometimes we use ⇒ somewhat 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.

You are encouraged to try the examples yourself, and to alter them to better learn `groff`’s behavior. Our examples frequently need to direct the formatter to set a line length (with ‘`.ll`’) that will fit 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.3