File: groff.info,  Node: Conventions Used in This Manual,  Next: Credits,  Prev: Installation,  Up: Introduction

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 *note 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.(1)  (*note Conventions Used
in This Manual-Footnote-1::)

     $ 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.(2)  (*note
Conventions Used in This Manual-Footnote-2::)