xref: /freebsd-10.3-release/contrib/groff/doc/groff-1

This is groff, produced by makeinfo version 4.2 from ./groff.texinfo.

This manual documents GNU `troff' version 1.18.

   Copyright (C) 1994-2000, 2001, 2002 Free Software Foundation, Inc.

     Permission is granted to copy, distribute and/or modify this
     document under the terms of the GNU Free Documentation License,
     Version 1.1 or any later version published by the Free Software
     Foundation; with no Invariant Sections, with the Front-Cover texts
     being `A GNU Manual," and with the Back-Cover Texts as in (a)
     below.  A copy of the license is included in the section entitled
     `GNU Free Documentation License."

     (a) The FSF's Back-Cover Text is: `You have freedom to copy and
     modify this GNU Manual, like GNU software.  Copies published by
     the Free Software Foundation raise funds for GNU development."
   
INFO-DIR-SECTION Miscellaneous
START-INFO-DIR-ENTRY
* Groff: (groff).               The GNU troff document formatting system.
END-INFO-DIR-ENTRY


File: groff,  Node: Top,  Next: Introduction,  Prev: (dir),  Up: (dir)

GNU troff
*********

This manual documents GNU `troff' version 1.18.

   Copyright (C) 1994-2000, 2001, 2002 Free Software Foundation, Inc.

     Permission is granted to copy, distribute and/or modify this
     document under the terms of the GNU Free Documentation License,
     Version 1.1 or any later version published by the Free Software
     Foundation; with no Invariant Sections, with the Front-Cover texts
     being `A GNU Manual," and with the Back-Cover Texts as in (a)
     below.  A copy of the license is included in the section entitled
     `GNU Free Documentation License."

     (a) The FSF's Back-Cover Text is: `You have freedom to copy and
     modify this GNU Manual, like GNU software.  Copies published by
     the Free Software Foundation raise funds for GNU development."
   
* Menu:

* Introduction::
* Invoking groff::
* Tutorial for Macro Users::
* Macro Packages::
* gtroff Reference::
* Preprocessors::
* Output Devices::
* File formats::
* Installation::
* Copying This Manual::
* Request Index::
* Escape Index::
* Operator Index::
* Register Index::
* Macro Index::
* String Index::
* Glyph Name Index::
* Font File Keyword Index::
* Program and File Index::
* Concept Index::


File: groff,  Node: Introduction,  Next: Invoking groff,  Prev: Top,  Up: Top

Introduction
************

   GNU `troff' (or `groff') is a system for typesetting documents.
`troff' is very flexible and has been in existence (and use) for about
3 decades.  It is quite widespread and firmly entrenched in the UNIX
community.

* Menu:

* What Is groff?::
* History::
* groff Capabilities::
* Macro Package Intro::
* Preprocessor Intro::
* Output device intro::
* Credits::


File: groff,  Node: What Is groff?,  Next: History,  Prev: Introduction,  Up: Introduction

What Is `groff'?
================

   `groff' belongs to an older generation of document preparation
systems, which operate more like compilers than the more recent
interactive WYSIWYG(1) (*note What Is groff?-Footnote-1::) systems.
`groff' and its contemporary counterpart, TeX, both work using a
"batch" paradigm: The input (or "source") files are normal text files
with embedded formatting commands.  These files can then be processed
by `groff' to produce a typeset document on a variety of devices.

   Likewise, `groff' should not be confused with a "word processor",
since that term connotes an integrated system that includes an editor
and a text formatter.  Also, many word processors follow the WYSIWYG
paradigm discussed earlier.

   Although WYSIWYG systems may be easier to use, they have a number of
disadvantages compared to `troff':

   * They must be used on a graphics display to work on a document.

   * Most of the WYSIWYG systems are either non-free or are not very
     portable.

   * `troff' is firmly entrenched in all UNIX systems.

   * It is difficult to have a wide range of capabilities available
     within the confines of a GUI/window system.

   * It is more difficult to make global changes to a document.

     "GUIs normally make it simple to accomplish simple actions and
     impossible to accomplish complex actions."  -Doug Gwyn (22/Jun/91
     in `comp.unix.wizards')


File: groff,  Node: What Is groff?-Footnotes,  Up: What Is groff?

   (1) What You See Is What You Get


File: groff,  Node: History,  Next: groff Capabilities,  Prev: What Is groff?,  Up: Introduction

History
=======

   `troff' can trace its origins back to a formatting program called
`runoff', written by J. E. Saltzer, which ran on MIT's CTSS operating
system in the mid-sixties.  This name came from the common phrase of
the time "I'll run off a document."  Bob Morris ported it to the 635
architecture and called the program `roff' (an abbreviation of
`runoff').  It was rewritten as `rf' for the PDP-7 (before having
UNIX), and at the same time (1969), Doug McIllroy rewrote an extended
and simplified version of `roff' in the BCPL programming language.

   The first version of UNIX was developed on a PDP-7 which was sitting
around Bell Labs.  In 1971 the developers wanted to get a PDP-11 for
further work on the operating system.  In order to justify the cost for
this system, they proposed that they would implement a document
formatting system for the AT&T patents division.  This first formatting
program was a reimplementation of McIllroy's `roff', written by
J. F. Ossanna.

   When they needed a more flexible language, a new version of `roff'
called `nroff' ("Newer `roff'") was written.  It had a much more
complicated syntax, but provided the basis for all future versions.
When they got a Graphic Systems CAT Phototypesetter, Ossanna wrote a
version of `nroff' that would drive it.  It was dubbed `troff', for
"typesetter `roff'", although many people have speculated that it
actually means "Times `roff'" because of the use of the Times font
family in `troff' by default.  As such, the name `troff' is pronounced
`t-roff' rather than `trough'.

   With `troff' came `nroff' (they were actually the same program
except for some `#ifdef's), which was for producing output for line
printers and character terminals.  It understood everything `troff'
did, and ignored the commands which were not applicable (e.g. font
changes).

   Since there are several things which cannot be done easily in
`troff', work on several preprocessors began.  These programs would
transform certain parts of a document into `troff', which made a very
natural use of pipes in UNIX.

   The `eqn' preprocessor allowed mathematical formulae to be specified
in a much simpler and more intuitive manner.  `tbl' is a preprocessor
for formatting tables.  The `refer' preprocessor (and the similar
program, `bib') processes citations in a document according to a
bibliographic database.

   Unfortunately, Ossanna's `troff' was written in PDP-11 assembly
language and produced output specifically for the CAT phototypesetter.
He rewrote it in C, although it was now 7000 lines of uncommented code
and still dependent on the CAT.  As the CAT became less common, and was
no longer supported by the manufacturer, the need to make it support
other devices became a priority.  However, before this could be done,
Ossanna was killed in a car accident.

   So, Brian Kernighan took on the task of rewriting `troff'.  The
newly rewritten version produced device independent code which was very
easy for postprocessors to read and translate to the appropriate
printer codes.  Also, this new version of `troff' (called `ditroff' for
"device independent `troff'") had several extensions, which included
drawing functions.

   Due to the additional abilities of the new version of `troff',
several new preprocessors appeared.  The `pic' preprocessor provides a
wide range of drawing functions.  Likewise the `ideal' preprocessor did
the same, although via a much different paradigm.  The `grap'
preprocessor took specifications for graphs, but, unlike other
preprocessors, produced `pic' code.

   James Clark began work on a GNU implementation of `ditroff' in
early 1989.  The first version, `groff' 0.3.1, was released June 1990.
`groff' included:

   * A replacement for `ditroff' with many extensions.

   * The `soelim', `pic', `tbl', and `eqn' preprocessors.

   * Postprocessors for character devices, POSTSCRIPT, TeX DVI, and
     X Windows.  GNU `troff' also eliminated the need for a separate
     `nroff' program with a postprocessor which would produce ASCII
     output.

   * A version of the `me' macros and an implementation of the `man'
     macros.

   Also, a front-end was included which could construct the, sometimes
painfully long, pipelines required for all the post- and preprocessors.

   Development of GNU `troff' progressed rapidly, and saw the additions
of a replacement for `refer', an implementation of the `ms' and `mm'
macros, and a program to deduce how to format a document (`grog').

   It was declared a stable (i.e. non-beta) package with the release of
version 1.04 around November 1991.

   Beginning in 1999, `groff' has new maintainers (the package was an
orphan for a few years).  As a result, new features and programs like
`grn', a preprocessor for gremlin images, and an output device to
produce HTML output have been added.


File: groff,  Node: groff Capabilities,  Next: Macro Package Intro,  Prev: History,  Up: Introduction

`groff' Capabilities
====================

   So what exactly is `groff' capable of doing?  `groff' provides a
wide range of low-level text formatting operations.  Using these, it is
possible to perform a wide range of formatting tasks, such as
footnotes, table of contents, multiple columns, etc.  Here's a list of
the most important operations supported by `groff':

   * text filling, adjusting, and centering

   * hyphenation

   * page control

   * font and glyph size control

   * vertical spacing (e.g. double-spacing)

   * line length and indenting

   * macros, strings, diversions, and traps

   * number registers

   * tabs, leaders, and fields

   * input and output conventions and character translation

   * overstrike, bracket, line drawing, and zero-width functions

   * local horizontal and vertical motions and the width function

   * three-part titles

   * output line numbering

   * conditional acceptance of input

   * environment switching

   * insertions from the standard input

   * input/output file switching

   * output and error messages


File: groff,  Node: Macro Package Intro,  Next: Preprocessor Intro,  Prev: groff Capabilities,  Up: Introduction

Macro Packages
==============

   Since `groff' provides such low-level facilities, it can be quite
difficult to use by itself.  However, `groff' provides a "macro"
facility to specify how certain routine operations (e.g. starting
paragraphs, printing headers and footers, etc.) should be done.  These
macros can be collected together into a "macro package".  There are a
number of macro packages available; the most common (and the ones
described in this manual) are `man', `mdoc', `me', `ms', and `mm'.


File: groff,  Node: Preprocessor Intro,  Next: Output device intro,  Prev: Macro Package Intro,  Up: Introduction

Preprocessors
=============

   Although `groff' provides most functions needed to format a
document, some operations would be unwieldy (e.g. to draw pictures).
Therefore, programs called "preprocessors" were written which
understand their own language and produce the necessary `groff'
operations.  These preprocessors are able to differentiate their own
input from the rest of the document via markers.

   To use a preprocessor, UNIX pipes are used to feed the output from
the preprocessor into `groff'.  Any number of preprocessors may be used
on a given document; in this case, the preprocessors are linked
together into one pipeline.  However, with `groff', the user does not
need to construct the pipe, but only tell `groff' what preprocessors to
use.

   `groff' currently has preprocessors for producing tables (`tbl'),
typesetting equations (`eqn'), drawing pictures (`pic' and `grn'), and
for processing bibliographies (`refer').  An associated program which
is useful when dealing with preprocessors is `soelim'.

   A free implementation of `grap', a preprocessor for drawing graphs,
can be obtained as an extra package; `groff' can use `grap' also.

   There are other preprocessors in existence, but, unfortunately, no
free implementations are available.  Among them are preprocessors for
drawing mathematical pictures (`ideal') and chemical structures
(`chem').


File: groff,  Node: Output device intro,  Next: Credits,  Prev: Preprocessor Intro,  Up: Introduction

Output Devices
==============

   `groff' actually produces device independent code which may be fed
into a postprocessor to produce output for a particular device.
Currently, `groff' has postprocessors for POSTSCRIPT devices, character
terminals, X Windows (for previewing), TeX DVI format, HP LaserJet 4
and Canon LBP printers (which use CAPSL), and HTML.


File: groff,  Node: Credits,  Prev: Output device intro,  Up: Introduction

Credits
=======

   Large portions of this manual were taken from existing documents,
most notably, the manual pages for the `groff' package by James Clark,
and Eric Allman's papers on the `me' macro package.

   The section on the `man' macro package is partly based on Susan G.
Kleinmann's `groff_man' manual page written for the Debian GNU/Linux
system.

   Larry Kollar contributed the section in the `ms' macro package.


File: groff,  Node: Invoking groff,  Next: Tutorial for Macro Users,  Prev: Introduction,  Up: Top

Invoking `groff'
****************

   This section focuses on how to invoke the `groff' front end.  This
front end takes care of the details of constructing the pipeline among
the preprocessors, `gtroff' and the postprocessor.

   It has become a tradition that GNU programs get the prefix `g' to
distinguish it from its original counterparts provided by the host (see
*Note Environment::, for more details).  Thus, for example, `geqn' is
GNU `eqn'.  On operating systems like GNU/Linux or the Hurd, which
don't contain proprietary versions of `troff', and on
MS-DOS/MS-Windows, where `troff' and associated programs are not
available at all, this prefix is omitted since GNU `troff' is the only
used incarnation of `troff'.  Exception: `groff' is never replaced by
`roff'.

   In this document, we consequently say `gtroff' when talking about
the GNU `troff' program.  All other implementations of `troff' are
called AT&T `troff' which is the common origin of all `troff' derivates
(with more or less compatible changes).  Similarly, we say `gpic',
`geqn', etc.

* Menu:

* Groff Options::
* Environment::
* Macro Directories::
* Font Directories::
* Invocation Examples::


File: groff,  Node: Groff Options,  Next: Environment,  Prev: Invoking groff,  Up: Invoking groff

Options
=======

   `groff' normally runs the `gtroff' program and a postprocessor
appropriate for the selected device.  The default device is `ps' (but
it can be changed when `groff' is configured and built).  It can
optionally preprocess with any of `gpic', `geqn', `gtbl', `ggrn',
`grap', `grefer', or `gsoelim'.

   This section only documents options to the `groff' front end.  Many
of the arguments to `groff' are passed on to `gtroff', therefore those
are also included.  Arguments to pre- or postprocessors can be found in
*Note Invoking gpic::, *Note Invoking geqn::, *Note Invoking gtbl::,
*Note Invoking ggrn::, *Note Invoking grefer::, *Note Invoking
gsoelim::, *Note Invoking grotty::, *Note Invoking grops::, *Note
Invoking grohtml::, *Note Invoking grodvi::, *Note Invoking grolj4::,
*Note Invoking grolbp::, and *Note Invoking gxditview::.

   The command line format for `groff' is:


     groff [ -abceghilpstvzCEGNRSUVXZ ] [ -FDIR ] [ -mNAME ]
           [ -TDEF ] [ -fFAM ] [ -wNAME ] [ -WNAME ]
           [ -MDIR ] [ -dCS ] [ -rCN ] [ -nNUM ]
           [ -oLIST ] [ -PARG ] [ -LARG ] [ -IDIR ]
           [ FILES... ]

   The command line format for `gtroff' is as follows.


     gtroff [ -abcivzCERU ] [ -wNAME ] [ -WNAME ] [ -dCS ]
            [ -fFAM ] [ -mNAME ] [ -nNUM ]
            [ -oLIST ] [ -rCN ] [ -TNAME ]
            [ -FDIR ] [ -MDIR ] [ FILES... ]

Obviously, many of the options to `groff' are actually passed on to
`gtroff'.

   Options without an argument can be grouped behind a single `-'.  A
filename of `-' denotes the standard input.  It is possible to have
whitespace between an option and its parameter.

   The `grog' command can be used to guess the correct `groff' command
to format a file.

   Here's the description of the command-line options:

`-h'
     Print a help message.

`-e'
     Preprocess with `geqn'.

`-t'
     Preprocess with `gtbl'.

`-g'
     Preprocess with `ggrn'.

`-G'
     Preprocess with `grap'.

`-p'
     Preprocess with `gpic'.

`-s'
     Preprocess with `gsoelim'.

`-c'
     Suppress color output.

`-R'
     Preprocess with `grefer'.  No mechanism is provided for passing
     arguments to `grefer' because most `grefer' options have
     equivalent commands which can be included in the file.  *Note
     grefer::, for more details.

     Note that `gtroff' also accepts a `-R' option, which is not
     accessible via `groff'.  This option prevents the loading of the
     `troffrc' and `troffrc-end' files.

`-v'
     Make programs run by `groff' print out their version number.

`-V'
     Print the pipeline on `stdout' instead of executing it.

`-z'
     Suppress output from `gtroff'.  Only error messages are printed.

`-Z'
     Do not postprocess the output of `gtroff'.  Normally `groff'
     automatically runs the appropriate postprocessor.

`-PARG'
     Pass ARG to the postprocessor.  Each argument should be passed
     with a separate `-P' option.  Note that `groff' does not prepend
     `-' to ARG before passing it to the postprocessor.

`-l'
     Send the output to a spooler for printing.  The command used for
     this is specified by the `print' command in the device description
     file (see *Note Font Files::, for more info).  If not present,
     `-l' is ignored.

`-LARG'
     Pass ARG to the spooler.  Each argument should be passed with a
     separate `-L' option.  Note that `groff' does not prepend a `-' to
     ARG before passing it to the postprocessor.  If the `print'
     keyword in the device description file is missing, `-L' is ignored.

`-TDEV'
     Prepare output for device DEV.  The default device is `ps', unless
     changed when `groff' was configured and built.  The following are
     the output devices currently available:

    `ps'
          For POSTSCRIPT printers and previewers.

    `dvi'
          For TeX DVI format.

    `X75'
          For a 75dpi X11 previewer.

    `X75-12'
          For a 75dpi X11 previewer with a 12pt base font in the
          document.

    `X100'
          For a 100dpi X11 previewer.

    `X100-12'
          For a 100dpi X11 previewer with a 12pt base font in the
          document.

    `ascii'
          For typewriter-like devices using the (7-bit) ASCII character
          set.

    `latin1'
          For typewriter-like devices that support the Latin-1
          (ISO 8859-1) character set.

    `utf8'
          For typewriter-like devices which use the Unicode (ISO 10646)
          character set with UTF-8 encoding.

    `cp1047'
          For typewriter-like devices which use the EBCDIC encoding IBM
          cp1047.

    `lj4'
          For HP LaserJet4-compatible (or other PCL5-compatible)
          printers.

    `lbp'
          For Canon CAPSL printers (LBP-4 and LBP-8 series laser
          printers).

    `html'
          To produce HTML output.  Note that the HTML driver consists
          of two parts, a preprocessor (`pre-grohtml') and a
          postprocessor (`post-grohtml').

     The predefined `gtroff' string register `.T' contains the current
     output device; the read-only number register `.T' is set to 1 if
     this option is used (which is always true if `groff' is used to
     call `gtroff').  *Note Built-in Registers::.

     The postprocessor to be used for a device is specified by the
     `postpro' command in the device description file.  (*Note Font
     Files::, for more info.)  This can be overridden with the `-X'
     option.

`-X'
     Preview with `gxditview' instead of using the usual postprocessor.
     This is unlikely to produce good results except with `-Tps'.

     Note that this is not the same as using `-TX75' or `-TX100' to
     view a document with `gxditview': The former uses the metrics of
     the specified device, whereas the latter uses X-specific fonts and
     metrics.

`-N'
     Don't allow newlines with `eqn' delimiters.  This is the same as
     the `-N' option in `geqn'.

`-S'
     Safer mode.  Pass the `-S' option to `gpic' and disable the
     `open', `opena', `pso', `sy', and `pi' requests.  For security
     reasons, this is enabled by default.

`-U'
     Unsafe mode.  This enables the `open', `opena', `pso', `sy', and
     `pi' requests.

`-a'
     Generate an ASCII approximation of the typeset output.  The
     read-only register `.A' is then set to 1.  *Note Built-in
     Registers::.  A typical example is


          groff -a -man -Tdvi troff.man | less

     which shows how lines are broken for the DVI device.  Note that
     this option is rather useless today since graphic output devices
     are available virtually everywhere.

`-b'
     Print a backtrace with each warning or error message.  This
     backtrace should help track down the cause of the error.  The line
     numbers given in the backtrace may not always be correct: `gtroff'
     can get confused by `as' or `am' requests while counting line
     numbers.

`-i'
     Read the standard input after all the named input files have been
     processed.

`-wNAME'
     Enable warning NAME.  Available warnings are described in *Note
     Debugging::.  Multiple `-w' options are allowed.

`-WNAME'
     Inhibit warning NAME.  Multiple `-W' options are allowed.

`-E'
     Inhibit all error messages.

`-C'
     Enable compatibility mode.  *Note Implementation Differences::,
     for the list of incompatibilities between `groff' and AT&T `troff'.

`-dCS'
`-dNAME=S'
     Define C or NAME to be a string S.  C must be a one-letter name;
     NAME can be of arbitrary length.  All string assignments happen
     before loading any macro file (including the start-up file).

`-fFAM'
     Use FAM as the default font family.  *Note Font Families::.

`-mNAME'
     Read in the file `NAME.tmac'.  Normally `groff' searches for this
     in its macro directories.  If it isn't found, it tries `tmac.NAME'
     (searching in the same directories).

`-nNUM'
     Number the first page NUM.

`-oLIST'
     Output only pages in LIST, which is a comma-separated list of page
     ranges; `N' means print page N, `M-N' means print every page
     between M and N, `-N' means print every page up to N, `N-' means
     print every page beginning with N.  `gtroff' exits after printing
     the last page in the list.  All the ranges are inclusive on both
     ends.

     Within `gtroff', this information can be extracted with the `.P'
     register.  *Note Built-in Registers::.

     If your document restarts page numbering at the beginning of each
     chapter, then `gtroff' prints the specified page range for each
     chapter.

`-rCN'
`-rNAME=N'
     Set number register C or NAME to the value N.  C must be a
     one-letter name; NAME can be of arbitrary length.  N can be any
     `gtroff' numeric expression.  All register  assignments happen
     before loading any macro file (including the start-up file).

`-FDIR'
     Search `DIR' for subdirectories `devNAME' (NAME is the name of the
     device), for the `DESC' file, and for font files before looking in
     the standard directories (*note Font Directories::).  This option
     is passed to all pre- and postprocessors using the
     `GROFF_FONT_PATH' environment variable.

`-MDIR'
     Search directory `DIR' for macro files before the standard
     directories (*note Macro Directories::).

`-IDIR'
     This option is as described in *Note gsoelim::.  It implies the
     `-s' option.


File: groff,  Node: Environment,  Next: Macro Directories,  Prev: Groff Options,  Up: Invoking groff

Environment
===========

   There are also several environment variables (of the operating
system, not within `gtroff') which can modify the behavior of `groff'.

`GROFF_COMMAND_PREFIX'
     If this is set to X, then `groff' runs `Xtroff' instead of
     `gtroff'.  This also applies to `tbl', `pic', `eqn', `grn',
     `refer', and `soelim'.  It does not apply to `grops', `grodvi',
     `grotty', `pre-grohtml', `post-grohtml', `grolj4', and `gxditview'.

     The default command prefix is determined during the installation
     process.  If a non-GNU troff system is found, prefix `g' is used,
     none otherwise.

`GROFF_TMAC_PATH'
     A colon-separated list of directories in which to search for macro
     files (before the default directories are tried).  *Note Macro
     Directories::.

`GROFF_TYPESETTER'
     The default output device.

`GROFF_FONT_PATH'
     A colon-separated list of directories in which to search for the
     `dev'NAME directory (before the default directories are tried).
     *Note Font Directories::.

`GROFF_BIN_PATH'
     This search path, followed by `PATH', is used for commands executed
     by `groff'.

`GROFF_TMPDIR'
     The directory in which `groff' creates temporary files.  If this is
     not set and `TMPDIR' is set, temporary files are created in that
     directory.  Otherwise temporary files are created in a
     system-dependent default directory (on Unix and GNU/Linux systems,
     this is usually `/tmp').  `grops', `grefer', `pre-grohtml', and
     `post-grohtml' can create temporary files in this directory.

   Note that MS-DOS and MS-Windows ports of `groff' use semi-colons,
rather than colons, to separate the directories in the lists described
above.


File: groff,  Node: Macro Directories,  Next: Font Directories,  Prev: Environment,  Up: Invoking groff

Macro Directories
=================

   All macro file names must be named `NAME.tmac' or `tmac.NAME' to
make the `-mNAME' command line option work.  The `mso' request doesn't
have this restriction; any file name can be used, and `gtroff' won't
try to append or prepend the `tmac' string.

   Macro files are kept in the "tmac directories", all of which
constitute the "tmac path".  The elements of the search path for macro
files are (in that order):

   * The directories specified with `gtroff''s or `groff''s `-M'
     command line option.

   * The directories given in the `GROFF_TMAC_PATH' environment
     variable.

   * The current directory (only if in unsafe mode using the `-U'
     command line switch).

   * The home directory.

   * A platform-dependent directory, a site-specific
     (platform-independent) directory, and the main tmac directory; the
     default locations are


          /usr/local/lib/groff/site-tmac
          /usr/local/share/groff/site-tmac
          /usr/local/share/groff/1.18/tmac

     assuming that the version of `groff' is 1.18, and the installation
     prefix was `/usr/local'.  It is possible to fine-tune those
     directories during the installation process.


File: groff,  Node: Font Directories,  Next: Invocation Examples,  Prev: Macro Directories,  Up: Invoking groff

Font Directories
================

   Basically, there is no restriction how font files for `groff' are
named and how long font names are; however, to make the font family
mechanism work (*note Font Families::), fonts within a family should
start with the family name, followed by the shape.  For example, the
Times family uses `T' for the family name and `R', `B', `I', and `BI'
to indicate the shapes `roman', `bold', `italic', and `bold italic',
respectively.  Thus the final font names are `TR', `TB', `TI', and
`TBI'.

   All font files are kept in the "font directories" which constitute
the "font path".  The file search functions will always append the
directory `dev'NAME, where NAME is the name of the output device.
Assuming, say, DVI output, and `/foo/bar' as a font directory, the font
files for `grodvi' must be in `/foo/bar/devdvi'.

   The elements of the search path for font files are (in that order):

   * The directories specified with `gtroff''s or `groff''s `-F'
     command line option.  All device drivers and some preprocessors
     also have this option.

   * The directories given in the `GROFF_FONT_PATH' environment
     variable.

   * A site-specific directory and the main font directory; the default
     locations are


          /usr/local/share/groff/site-font
          /usr/local/share/groff/1.18/font

     assuming that the version of `groff' is 1.18, and the installation
     prefix was `/usr/local'.  It is possible to fine-tune those
     directories during the installation process.


File: groff,  Node: Invocation Examples,  Prev: Font Directories,  Up: Invoking groff

Invocation Examples
===================

   This section lists several common uses of `groff' and the
corresponding command lines.


     groff file

This command processes `file' without a macro package or a
preprocessor.  The output device is the default, `ps', and the output
is sent to `stdout'.


     groff -t -mandoc -Tascii file | less

This is basically what a call to the `man' program does.  `gtroff'
processes the manual page `file' with the `mandoc' macro file (which in
turn either calls the `man' or the `mdoc' macro package), using the
`tbl' preprocessor and the ASCII output device.  Finally, the `less'
pager displays the result.


     groff -X -m me file

Preview `file' with `gxditview', using the `me' macro package.  Since
no `-T' option is specified, use the default device (`ps').  Note that
you can either say `-m me' or `-me'; the latter is an anachronism from
the early days of UNIX.(1) (*note Invocation Examples-Footnote-1::)


     groff -man -rD1 -z file

Check `file' with the `man' macro package, forcing double-sided
printing - don't produce any output.

* Menu:

* grog::


File: groff,  Node: Invocation Examples-Footnotes,  Up: Invocation Examples

   (1) The same is true for the other main macro packages that come
with `groff': `man', `mdoc', `ms', `mm', and `mandoc'.  This won't work
in general; for example, to load `trace.tmac', either `-mtrace' or
`-m trace' must be used.


File: groff,  Node: grog,  Prev: Invocation Examples,  Up: Invocation Examples

`grog'
------

   `grog' reads files, guesses which of the `groff' preprocessors
and/or macro packages are required for formatting them, and prints the
`groff' command including those options on the standard output.  It
generates one or more of the options `-e', `-man', `-me', `-mm',
`-mom', `-ms', `-mdoc', `-mdoc-old', `-p', `-R', `-g', `-G', `-s', and
`-t'.

   A special file name `-' refers to the standard input.  Specifying no
files also means to read the standard input.  Any specified options are
included in the printed command.  No space is allowed between options
and their arguments.  The only options recognized are `-C' (which is
also passed on) to enable compatibility mode, and `-v' to print the
version number and exit.

   For example,


     grog -Tdvi paper.ms

guesses the appropriate command to print `paper.ms' and then prints it
to the command line after adding the `-Tdvi' option.  For direct
execution, enclose the call to `grog' in backquotes at the UNIX shell
prompt:


     `grog -Tdvi paper.ms` > paper.dvi

As seen in the example, it is still necessary to redirect the output to
something meaningful (i.e. either a file or a pager program like
`less').


File: groff,  Node: Tutorial for Macro Users,  Next: Macro Packages,  Prev: Invoking groff,  Up: Top

Tutorial for Macro Users
************************

   Most users tend to use a macro package to format their papers.  This
means that the whole breadth of `groff' is not necessary for most
people.  This chapter covers the material needed to efficiently use a
macro package.

* Menu:

* Basics::
* Common Features::


File: groff,  Node: Basics,  Next: Common Features,  Prev: Tutorial for Macro Users,  Up: Tutorial for Macro Users

Basics
======

   This section covers some of the basic concepts necessary to
understand how to use a macro package.(1) (*note Basics-Footnote-1::)
References are made throughout to more detailed information, if desired.

   `gtroff' reads an input file prepared by the user and outputs a
formatted document suitable for publication or framing.  The input
consists of text, or words to be printed, and embedded commands
("requests" and "escapes"), which tell `gtroff' how to format the
output.  For more detail on this, see *Note Embedded Commands::.

   The word "argument" is used in this chapter to mean a word or number
which appears on the same line as a request, and which modifies the
meaning of that request.  For example, the request


     .sp

spaces one line, but


     .sp 4

spaces four lines.  The number 4 is an argument to the `sp' request
which says to space four lines instead of one.  Arguments are separated
from the request and from each other by spaces (_no_ tabs).  More
details on this can be found in *Note Request Arguments::.

   The primary function of `gtroff' is to collect words from input
lines, fill output lines with those words, justify the right-hand margin
by inserting extra spaces in the line, and output the result.  For
example, the input:


     Now is the time
     for all good men
     to come to the aid
     of their party.
     Four score and seven
     years ago, etc.

is read, packed onto output lines, and justified to produce:

     Now is the time for all good men to come to the aid of their party.
     Four score and seven years ago, etc.

   Sometimes a new output line should be started even though the current
line is not yet full; for example, at the end of a paragraph.  To do
this it is possible to cause a "break", which starts a new output line.
Some requests cause a break automatically, as normally do blank input
lines and input lines beginning with a space.

   Not all input lines are text to be formatted.  Some input lines are
requests which describe how to format the text.  Requests always have a
period (`.') or an apostrophe (`'') as the first character of the input
line.

   The text formatter also does more complex things, such as
automatically numbering pages, skipping over page boundaries, putting
footnotes in the correct place, and so forth.

   Here are a few hints for preparing text for input to `gtroff'.

   * First, keep the input lines short.  Short input lines are easier to
     edit, and `gtroff' packs words onto longer lines anyhow.

   * In keeping with this, it is helpful to begin a new line after every
     comma or phrase, since common corrections are to add or delete
     sentences or phrases.

   * End each sentence with two spaces - or better, start each sentence
     on a new line.  `gtroff' recognizes characters that usually end a
     sentence, and inserts sentence space accordingly.

   * Do not hyphenate words at the end of lines - `gtroff' is smart
     enough to hyphenate words as needed, but is not smart enough to
     take hyphens out and join a word back together.  Also, words such
     as "mother-in-law" should not be broken over a line, since then a
     space can occur where not wanted, such as "mother- in-law".

   `gtroff' double-spaces output text automatically if you use the
request `.ls 2'.  Reactivate single-spaced mode by typing `.ls 1'.(2)
(*note Basics-Footnote-2::)

   A number of requests allow to change the way the output looks,
sometimes called the "layout" of the output page.  Most of these
requests adjust the placing of "whitespace" (blank lines or spaces).

   The `bp' request starts a new page, causing a line break.

   The request `.sp N' leaves N lines of blank space.  N can be omitted
(meaning skip a single line) or can be of the form Ni (for N inches) or
Nc (for N centimeters).  For example, the input:


     .sp 1.5i
     My thoughts on the subject
     .sp

leaves one and a half inches of space, followed by the line "My
thoughts on the subject", followed by a single blank line (more
measurement units are available, see *Note Measurements::).

   Text lines can be centered by using the `ce' request.  The line
after `ce' is centered (horizontally) on the page.  To center more than
one line, use `.ce N' (where N is the number of lines to center),
followed by the N lines.  To center many lines without counting them,
type:


     .ce 1000
     lines to center
     .ce 0

The `.ce 0' request tells `groff' to center zero more lines, in other
words, stop centering.

   All of these requests cause a break; that is, they always start a new
line.  To start a new line without performing any other action, use
`br'.


File: groff,  Node: Basics-Footnotes,  Up: Basics

   (1) This section is derived from `Writing Papers with nroff using
-me' by Eric P. Allman.

   (2) If you need finer granularity of the vertical space, use the
`pvs' request (*note Changing Type Sizes::).


File: groff,  Node: Common Features,  Prev: Basics,  Up: Tutorial for Macro Users

Common Features
===============

   `gtroff' provides very low-level operations for formatting a
document.  There are many common routine operations which are done in
all documents.  These common operations are written into "macros" and
collected into a "macro package".

   All macro packages provide certain common capabilities which fall
into the following categories.

* Menu:

* Paragraphs::
* Sections and Chapters::
* Headers and Footers::
* Page Layout Adjustment::
* Displays::
* Footnotes and Annotations::
* Table of Contents::
* Indices::
* Paper Formats::
* Multiple Columns::
* Font and Size Changes::
* Predefined Strings::
* Preprocessor Support::
* Configuration and Customization::


File: groff,  Node: Paragraphs,  Next: Sections and Chapters,  Prev: Common Features,  Up: Common Features

Paragraphs
----------

   One of the most common and most used capability is starting a
paragraph.  There are a number of different types of paragraphs, any of
which can be initiated with macros supplied by the macro package.
Normally, paragraphs start with a blank line and the first line
indented, like the text in this manual.  There are also block style
paragraphs, which omit the indentation:


     Some   men  look   at  constitutions   with  sanctimonious
     reverence, and deem them like the ark of the covenant, too
     sacred to be touched.

And there are also indented paragraphs which begin with a tag or label
at the margin and the remaining text indented.


     one   This is  the first paragraph.  Notice  how the first
           line of  the resulting  paragraph lines up  with the
           other lines in the paragraph.


     longlabel
           This  paragraph   had  a  long   label.   The  first
           character of text on the first line does not line up
           with  the  text  on  second  and  subsequent  lines,
           although they line up with each other.

   A variation of this is a bulleted list.


     .     Bulleted lists start with a bullet.   It is possible
           to use other glyphs instead of the bullet.  In nroff
           mode using the ASCII character set for output, a dot
           is used instead of a real bullet.


File: groff,  Node: Sections and Chapters,  Next: Headers and Footers,  Prev: Paragraphs,  Up: Common Features

Sections and Chapters
---------------------

   Most macro packages supply some form of section headers.  The
simplest kind is simply the heading on a line by itself in bold type.
Others supply automatically numbered section heading or different
heading styles at different levels.  Some, more sophisticated, macro
packages supply macros for starting chapters and appendices.


File: groff,  Node: Headers and Footers,  Next: Page Layout Adjustment,  Prev: Sections and Chapters,  Up: Common Features

Headers and Footers
-------------------

   Every macro package gives some way to manipulate the "headers" and
"footers" (also called "titles") on each page.  This is text put at the
top and bottom of each page, respectively, which contain data like the
current page number, the current chapter title, and so on.  Its
appearance is not affected by the running text.  Some packages allow
for different ones on the even and odd pages (for material printed in a
book form).

   The titles are called "three-part titles", that is, there is a
left-justified part, a centered part, and a right-justified part.  An
automatically generated page number may be put in any of these fields
with the `%' character (see *Note Page Layout::, for more details).


File: groff,  Node: Page Layout Adjustment,  Next: Displays,  Prev: Headers and Footers,  Up: Common Features

Page Layout
-----------

   Most macro packages let the user specify top and bottom margins and
other details about the appearance of the printed pages.


File: groff,  Node: Displays,  Next: Footnotes and Annotations,  Prev: Page Layout Adjustment,  Up: Common Features

Displays
--------

   "Displays" are sections of text to be set off from the body of the
paper.  Major quotes, tables, and figures are types of displays, as are
all the examples used in this document.

   "Major quotes" are quotes which are several lines long, and hence
are set in from the rest of the text without quote marks around them.

   A "list" is an indented, single-spaced, unfilled display.  Lists
should be used when the material to be printed should not be filled and
justified like normal text, such as columns of figures or the examples
used in this paper.

   A "keep" is a display of lines which are kept on a single page if
possible.  An example for a keep might be a diagram.  Keeps differ from
lists in that lists may be broken over a page boundary whereas keeps are
not.

   "Floating keeps" move relative to the text.  Hence, they are good for
things which are referred to by name, such as "See figure 3".  A
floating keep appears at the bottom of the current page if it fits;
otherwise, it appears at the top of the next page.  Meanwhile, the
surrounding text `flows' around the keep, thus leaving no blank areas.


File: groff,  Node: Footnotes and Annotations,  Next: Table of Contents,  Prev: Displays,  Up: Common Features

Footnotes and Annotations
-------------------------

   There are a number of requests to save text for later printing.

   "Footnotes" are printed at the bottom of the current page.

   "Delayed text" is very similar to a footnote except that it is
printed when called for explicitly.  This allows a list of references to
appear (for example) at the end of each chapter, as is the convention in
some disciplines.

   Most macro packages which supply this functionality also supply a
means of automatically numbering either type of annotation.


File: groff,  Node: Table of Contents,  Next: Indices,  Prev: Footnotes and Annotations,  Up: Common Features

Table of Contents
-----------------

   "Tables of contents" are a type of delayed text having a tag
(usually the page number) attached to each entry after a row of dots.
The table accumulates throughout the paper until printed, usually after
the paper has ended.  Many macro packages provide the ability to have
several tables of contents (e.g. a standard table of contents, a list
of tables, etc).


File: groff,  Node: Indices,  Next: Paper Formats,  Prev: Table of Contents,  Up: Common Features

Indices
-------

   While some macro packages use the term "index", none actually
provide that functionality.  The facilities they call indices are
actually more appropriate for tables of contents.

   To produce a real index in a document, external tools like the
`makeindex' program are necessary.


File: groff,  Node: Paper Formats,  Next: Multiple Columns,  Prev: Indices,  Up: Common Features

Paper Formats
-------------

   Some macro packages provide stock formats for various kinds of
documents.  Many of them provide a common format for the title and
opening pages of a technical paper.  The `mm' macros in particular
provide formats for letters and memoranda.


File: groff,  Node: Multiple Columns,  Next: Font and Size Changes,  Prev: Paper Formats,  Up: Common Features

Multiple Columns
----------------

   Some macro packages (but not `man') provide the ability to have two
or more columns on a page.


File: groff,  Node: Font and Size Changes,  Next: Predefined Strings,  Prev: Multiple Columns,  Up: Common Features

Font and Size Changes
---------------------

   The built-in font and size functions are not always intuitive, so all
macro packages provide macros to make these operations simpler.


File: groff,  Node: Predefined Strings,  Next: Preprocessor Support,  Prev: Font and Size Changes,  Up: Common Features

Predefined Strings
------------------

   Most macro packages provide various predefined strings for a variety
of uses; examples are sub- and superscripts, printable dates, quotes and
various special characters.


File: groff,  Node: Preprocessor Support,  Next: Configuration and Customization,  Prev: Predefined Strings,  Up: Common Features

Preprocessor Support
--------------------

   All macro packages provide support for various preprocessors and may
extend their functionality.

   For example, all macro packages mark tables (which are processed with
`gtbl') by placing them between `TS' and `TE' macros.  The `ms' macro
package has an option, `.TS H', that prints a caption at the top of a
new page (when the table is too long to fit on a single page).


File: groff,  Node: Configuration and Customization,  Prev: Preprocessor Support,  Up: Common Features

Configuration and Customization
-------------------------------

   Some macro packages provide means of customizing many of the details
of how the package behaves.  This ranges from setting the default type
size to changing the appearance of section headers.


File: groff,  Node: Macro Packages,  Next: gtroff Reference,  Prev: Tutorial for Macro Users,  Up: Top

Macro Packages
**************

   This chapter documents the main macro packages that come with
`groff'.

* Menu:

* man::
* mdoc::
* ms::
* me::
* mm::


File: groff,  Node: man,  Next: mdoc,  Prev: Macro Packages,  Up: Macro Packages

`man'
=====

   This is the most popular and probably the most important macro
package of `groff'.  It is easy to use, and a vast majority of manual
pages are based on it.

* Menu:

* Man options::
* Man usage::
* Man font macros::
* Miscellaneous man macros::
* Predefined man strings::
* Preprocessors in man pages::


File: groff,  Node: Man options,  Next: Man usage,  Prev: man,  Up: man

Options
-------

   The command line format for using the `man' macros with `groff' is:


     groff -m man [ -rLL=LENGTH ] [ -rLT=LENGTH ]
           [ -rcR=1 ] [ -rC1 ] [ -rD1 ] [ -rPNNN ]
           [ -rSXX ] [ -rXNNN ] [ FILES... ]

It is possible to use `-man' instead of `-m man'.

`-rLL=LENGTH'
     Set line length to LENGTH.  If not specified, the line length
     defaults to 78 en in nroff mode (this is 78 characters per line)
     and 6.5 inch otherwise.

`-rLT=LENGTH'
     Set title length to LENGTH.  If not specified, the title length
     defaults to 78 en in nroff mode (this is 78 characters per line)
     and 6.5 inch otherwise.

`-rcR=1'
     This option (the default if a TTY output device is used) creates a
     single, very long page instead of multiple pages.  Use `-rcR=0' to
     disable it.

`-rC1'
     If more than one manual page is given on the command line, number
     the pages continuously, rather than starting each at 1.

`-rD1'
     Double-sided printing.  Footers for even and odd pages are
     formatted differently.

`-rPNNN'
     Page numbering starts with NNN rather than with 1.

`-rSXX'
     Use XX (which can be 10, 11, or 12pt) as the base document font
     size instead of the default value of 10pt.

`-rXNNN'
     After page NNN, number pages as NNNa, NNNb, NNNc, etc.  For
     example, the option `-rX2' produces the following page numbers: 1,
     2, 2a, 2b, 2c, etc.