path: root/man/roff.man

.ig
roff.man

Last update: 08 Jan 2002

This file is part of groff, the GNU roff type-setting system.

Copyright (C) 2000, 2001, 2002 Free Software Foundation, Inc.
written by Bernd Warken <bwarken@mayn.de>
maintained by Werner Lemberg <wl@gnu.org>

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 the
Invariant Sections being this .ig-section and AUTHORS, with no
Front-Cover Texts, and with no Back-Cover Texts.

A copy of the Free Documentation License is included as a file called
FDL in the main directory of the groff source package.
..
.
.\" --------------------------------------------------------------------
.\" Setup
.\" --------------------------------------------------------------------
.
.mso www.tmac
.
.if n \{\
.  mso tty-char.tmac
.  ftr CR R
.  ftr CI I
.  ftr CB B
.\}
.
.if '\*[.T]'dvi' \{\
.  ftr CB CW
.\}
.
.
.\" --------------------------------------------------------------------
.\" Begin of macro definitions
.eo
.
.de Text
.  nop \)\$*
..
.de ellipsis
.  Text .\|.\|.\&\"
..
.de esc
.  ds @1 \$1\"
.  shift
.  Text \f[B]\[rs]\*[@1]\f[]\$*
.  rm @1
..
.de option
.  ds @1 \$1\"
.  shift 1
.  Text \f[B]\*[@1]\f[]\$*
.  rm @1
..
.de quoted_char
.  ds @1 \$1
.  shift
.  nop `\fB\*[@1]\fP'\$*
.  rm @1
..
.de ShellCommand
.  br
.  IR "shell#" "\h'1m'\f[CB]\$*\f[]\/"
..
.de TP+
.  br
.  ns
.  TP \$1
..
.de Topic
.  TP 2m
.  Text \[bu]
..
.ds comment \[rs]"
.ec
.\" End of macro definitions
.
.
.\" --------------------------------------------------------------------
.\" Title
.\" --------------------------------------------------------------------
.
.TH ROFF @MAN7EXT@ "@MDATE@" "Groff Version @VERSION@"
.SH NAME
roff \- introduction and overview of roff typesetting
.
.
.\" --------------------------------------------------------------------
.SH DESCRIPTION
.\" --------------------------------------------------------------------
.
.I roff
is the general name for a set of type-setting programs, known under
names like
.IR troff ,
.IR nroff ,
.IR ditroff ,
.IR groff ,
etc.
.
A roff type-setting system consists of an extensible text formatting
language and a set of programs for printing and converting to other
text formats.
.
Traditionally, it is the main text processing system of Unix; every
Unix-like operating system still distributes a roff system as a core
package.
.
.P
The most common roff system today is the free software implementation
GNU roff,
.IR groff .
.
The pre-groff implementations are referred to as
.I classical
(dating back as long as 1973).
.
.I groff
implements the look-and-feel and functionality of its classical
ancestors, but has many extensions.
.
As
.I groff
is the only roff system that is available for every (or almost every)
computer system it is the de-facto roff standard today.
.
.P
In spite of its age, roff is in wide use today, e.g., the manual pages
on UNIX systems
.RI ( man\~pages\/ ),
many software books, system documentation, standards, and corporate
documents are written in roff.
.
The roff output for text devices is still unmatched, and its graphical
output has the same quality as other free type-setting programs and is
better than some of the commercial systems.
.
.P
This document gives only an overview and provides pointers to further
documentation, cf. section
.BR "SEE ALSO" .
.
.
.\" --------------------------------------------------------------------
.SH "HISTORY"
.\" --------------------------------------------------------------------
.
The
.I roff
text processing system has a very long history, dating back to the
1960s.
.
The roff system itself is intimately connected to the Unix operating
system, but roff had roots in the earlier operating systems CTSS and
Multics.
.
.P
.I roff
evolved from its predecessor
.I runoff
written by
.I Jerry Saltzer
on the
.I CTSS
operating system
.RI ( "Compatible Time Sharing System" )
in 1961, which was further developed into the famous Unix predecessor
operating system
.URL http://\:www.multicians.org "Multics" ,
available from 1963.
.
Both operating systems could only be run on very expensive computers
at that time, so they were mostly used in research and for official
and military tasks.
.
.P
The possibilities of the
.I runoff
program were quite limited as compared to roff.
.
Only text output was needed in the 1960s.
.
This could be implemented by a set of requests of length\~2, many of
which are still identically used in roff.
.
The runoff program was first written in
.IR PL/1 ,
later on in
.IR BCPL ,
the grandmother of the
.I C
programming language.
.
In the Multics operating system, the help system was handled by
runoff, similar to roff's task on the Unix manual pages.
.
There are still documents written in the runoff language; for examples
see Saltzer's homepage (follow the links on the Multics web page).
.
.P
In the 1970s, the Multics off-spring
.I Unix
became more and more popular because it could be run on affordable
machines and was free at that time.
.
At MIT (the Massachusetts Institute of Technology), there was a need to
drive the Wang
.I Graphic Systems CAT
typesetter, a graphical output device from a PDP-11 computer running
Unix.
.
As runoff was too limited for this task it was further developed into
a more powerful text formatting system by
.IR "Josef F. Osanna" ,
a main developer of Multics and runoff ports.
.
This was called
.IR roff ,
a short form for
.IR runoff .
.
The first version was written in the PDP-11 assembly language and
released in 1973.
.
.I Brian Kernighan
joined the roff development by rewriting it in the C programming
language.
.
The C version was released in 1975.
.
.P
This first roff system could produce output for only 2\~devices:
.B troff
.RI ( "typesetter roff\/" )
had a graphical output for the
.I CAT
typesetter as its only device, while
.B nroff
produced text output suitable for terminals or line printers.
.
.P
The syntax of the formatting language of the
.BR nroff / troff
programs was documented in the famous
.IR "Troff User's Manual [CSTR\~#54]" ,
first published in 1976, with further revisions up to 1992 by Brian
Kernighan.
.
The system described therein is referred to as the
.IR "classical troff" .
All later
.I roff
systems tried to establish compatibility with this specification.
.
.P
After Osanna had died in 1977 by a heart-attack at the age of about\~50
Kernighan went on with developping troff.
.
The next milestone was to equip troff with a general interface to
support more devices, the intermediate output format and the
postprocessor system.
.
This completed the structure of a
.I "roff system"
as it is still in use today; see section
.IR "USING ROFF" .
.
In 1979, these novelties were described in the paper
.IR "[CSTR\~#97]" .
This new troff version is the basis for all existing newer troff
systems, including
.IR groff .
.
.P
A major catastrophy occurred when the freely available Unix\~7
operating system was commercialized.
.
A whole bunch of divergent operating systems emerged, fighting each
other with incompatibilities, finally causing many different roff
systems.
.
All of them used Osanna/Kernighan's free source code and his troff
papers as their main documentation, but sold them together with
"their" system \[em] with only minor modifications.
.
Though most commercial roff systems added incompatible extensions, all
of them try to achieve compatibility with the original, free troff.
.
Some of these roff implementations were renamed into
.BR ditroff (@MAN1EXT@),
originating from
.IR "device independent troff" .
This name is an exaggeration.
.
.P
As a counter-measure to the galopping commercialization, more and more
free software projects emerged during the 1980s and 1990s.
.
The most important roff project was the GNU port of troff, created by
James Clark.
.
It was called
.I groff
.RI ( "GNU roff" ).
.
The groff system is actively developed.
.
Though being compatible with the classical troff, many extensions were
added that greatly simplify roff programming.
.
It is the first roff system that is available on almost all operating
systems \[em] and it is free.
.
This makes groff the de-facto roff standard today.
.
.
.\" --------------------------------------------------------------------
.SH "USING ROFF"
.\" --------------------------------------------------------------------
.
Most people won't even notice that they are actually using roff.
.
When you read a system manual page (man page) roff is working in the
background.
.
Arbitrary roff documents can be viewed with a native roff viewer
called
.BR xditview (1x),
a standard program of the
.BR X (7x)
window distribution.
.
But using roff explicitly isn't difficult either.
.
.P
Some roff implementations provide wrapper programs that make it easy
to use the roff system on the shell command line.
.
For example, the GNU roff implementation
.BR groff (@MAN1EXT@)
provides command line options to avoid the long command pipes of
classical troff; a program
.BR grog (@MAN1EXT@)
tries to guess from the document which arguments should be used for a
run of groff; people who do not like specifying command line options
should try the
.BR groffer (@MAN1EXT@)
program for graphically displaying groff files and man pages.
.
.
.\" --------------------------------------------------------------------
.SS "The roff Pipe"
.\" --------------------------------------------------------------------
.
Each roff system consists of preprocessors, roff formatter programs,
and a set of device postprocessors.
.
This concept makes heavily use of the
.I piping
mechanism, i.e. a series of programs is called one after the other,
where the output of each program in the queue is taken as the input
for the next program.
.
.P
.B cat
.I file
.B |
.ellipsis
.B | preproc |
.ellipsis
.B | troff
.I options
.B | postproc
.
.P
The preprocessors generate roff code that is fed into a roff formatter
(e.g. troff), which in turn generates
.I intermediate output
that is fed into a device postprocessor program for printing or final
output.
.
.P
All of these parts use programming languages of their own; each
language is totally unrelated to the other parts.
.
Moreover, roff macro packages can be inluded.
.
So most roff documents use the macros of some package, intermixed with
code for one or more preprocessors, but do not need many elements from
the plain roff language.
.
.
.\" --------------------------------------------------------------------
.SS "Preprocessors"
.\" --------------------------------------------------------------------
.
A roff preprocessor is any program that generates output that
syntactically obeys the rules of the roff formatting language.
.
Each preprocessor defines a language of its own that is translated
into roff code when run through the preprocessor program.
.
Parts written in these languages may be included within a roff
document; they are identified by special roff requests or macros.
.
Each document that is enhanced by preprocessor code must be run
through all corresponding preprocessors before it is fed into the
actual roff formatter program; for the formatter just ignores all
alien code.
.
The preprocessor programs extract and transform only the document
parts that are determined for them.
.
.P
There are a lot of free and commercial roff preprocessors.
.
Some of these aren't available on each system, but there is a small
set of preprocessors that are considered as an integral part of each
roff system.
.
The classical preprocessors are
.
.P
.RS
.PD 0
.TP
.B tbl
for tables
.TP
.B eqn
for mathematical formul\[ae]
.TP
.B pic
for drawing diagrams
.TP
.B refer
for bibliographic references
.TP
.B soelim
for including macro files from standard locations
.PD
.RE
.
.P
Other known preprocessors that are not available on all systems
include
.
.P
.RS
.PD 0
.TP
.B chem
for drawing chemical formul\[ae].
.TP
.B grap
for constructing graphical elements.
.TP
.B grn
for including
.BR gremlin (1)
pictures.
.PD
.RE
.
.
.\" --------------------------------------------------------------------
.SS "Formatter Programs"
.\" --------------------------------------------------------------------
.
A
.I roff formatter
is a program that parses documents written in the roff formatting
language or uses some of the roff macro packages.
.
It generates
.IR "intermediate output" ,
which is intended to be fed into a single device postprocessor that
must be specified by a command-line option to the formatter program.
.
The documents must have been run through all necessary preprocessors
before.
.
.P
The output produced by a roff formatter is represented in yet another
language, the
.IR "intermediate output format"
or
.IR "troff output" .
This language was first specified in
.IR "[CSTR\~#97]" ;
its GNU extension is documented in
.BR groff_out (@MAN5EXT@).
.
The intermediate output language is a kind of assembly language
compared to the high-level roff language.
.
The generated intermediate output is optimized for a special device,
but the language is the same for every device.
.
.P
The roff formatter is the heart of the roff system.
.
The traditional roff had two formatters,
.B nroff
for text devices and
.B troff
for graphical devices.
.
.P
Often, the name
.I troff
is used as a general term to refer to both formatters.
.
.
.\" --------------------------------------------------------------------
.SS "Devices and Postprocessors"
.\" --------------------------------------------------------------------
.
Devices are hardware interfaces like printers, text or graphical
terminals, etc., or software interfaces such as a conversion into a
different text or graphical format.
.
.P
A roff postprocessor is a program that transforms troff output into a
form suitable for a special device.
.
The roff postprocessors are like device drivers for the output target.
.
.P
For each device there is a postprocessor program that fits the device
optimally.
.
The postprocessor parses the generated intermediate output and
generates device-specific code that is sent directly to the device.
.
.P
The names of the devices and the postprocessor programs are not fixed
because they greatly depend on the software and hardware abilities of
the actual computer.
.
For example, the classical devices mentioned in
.I [CSTR\~#54]
have greatly changed since the classical times.
.
The old hardware doesn't exist any longer and the old graphical
conversions were quite imprecise when compared to their modern
counterparts.
.
.P
For example, the Postscript device
.I post
in classical troff had a resolution
of 720, while groff
.I ps
has 72000, a refinement of factor 100.
.
.P
Today the operating systems provide device drivers for most
printer-like hardware, so it isn't necessary to write a special
hardware postprocessor for each printer.
.
.
.\" --------------------------------------------------------------------
.SH "ROFF PROGRAMMING"
.\" --------------------------------------------------------------------
.
Documents using roff are normal text files decorated by roff
formatting elements.
.
The roff formatting language is quite powerful; it is almost a full
programming language and provides elements to enlarge the language.
.
With these, it became possible to develop macro packages that are
tailored for special applications.
.
Such macro packages are much handier than plain roff.
.
So most people will choose a macro package without worrying about the
internals of the roff language.
.
.
.\" --------------------------------------------------------------------
.SS "Macro Packages"
.\" --------------------------------------------------------------------
.
Macro packages are collections of macros that are suitable to format a
special kind of documents in a convenient way.
.
This greatly eases the usage of roff.
.
The macro definitions of a package are kept in a file called
.IB name .tmac
(classically
.BI tmac. name\c
).
.
All tmac files are stored in one or more directories at standardized
positions.
.
Details on the naming of macro packages and their placement is found
in
.BR groff_tmac (@MAN5EXT@).
.
.P
A macro package that is to be used in a document can be announced to
the formatter by the command line option
.option \-m ,
see
.BR troff (@MAN1EXT@),
or it can be specified within a document using the file inclusion
requests of the roff language, see
.BR groff (@MAN7EXT@).
.
.P
Famous classical macro packages are
.I man
for traditional man pages,
.I mdoc
for BSD-style manual pages;
the macro sets for books, articles, and letters are
.I me
(probably from the first name of its creator
.I Eric
Allman),
.I ms
(from
.IR "Manuscript Macros\/" ),
and
.I mm
(from
.IR "Memorandum Macros\/" ).
.
.
.\" --------------------------------------------------------------------
.SS "The roff Formatting Language"
.\" --------------------------------------------------------------------
.
The classical roff formatting language is documented in the
.I Troff User's Manual
.IR "[CSTR\~#54]" .
.
The roff language is a full programming language providing requests,
definition of macros, escape sequences, string variables, number or
size registers, and flow controls.
.
.P
.I Requests
are the predefined basic formatting commands similar to the commands
at the shell prompt.
.
The user can define request-like elements using predefined roff
elements.
.
These are then called
.IR macros .
.
A document writer will not note any difference in usage for requests
or macros; both are written on a line on their own starting with a dot
.quoted_char . .
.
.P
.I Escape sequences
are roff elements starting with a backslash
.quoted_char \[rs] .
They can be inserted anywhere, also in the midst of text in a line.
.
They are used to implement various features, including the insertion of
non-ASCII characters with
.esc ( ,
font changes with
.esc f ,
in-line comments with
.esc \[dq] ,
the escaping of special control characters like
.esc \[rs] ,
and many other features.
.
.P
.I Strings
are variables that can store a string.
.
A string is stored by the
.B .ds
request.
.
The stored string can be retrieved later by the
.B \[rs]*
escape sequence.
.
.P
.I Registers
store numbers and sizes.
.
A register can be set with the request
.B .nr
and its value can be retrieved by the escape sequence
.BR "\[rs]n" .
.
.
.\" --------------------------------------------------------------------
.SH "FILE NAME EXTENSIONS"
.\" --------------------------------------------------------------------
.
Manual pages (man pages) take the section number as a file name
extension, e.g., the filename for this document is
.IR roff.7 ,
i.e., it is kept in section\~7
of the man pages.
.
.P
The classical macro packages take the package name as an extension, e.g.
.IB file. me
for a document using the
.I me
macro package,
.IB file. mm
for
.IR mm ,
.IB file. ms
for
.IR ms ,
.IB file. pic
for
.I pic
files,
etc.
.
.P
But there is no general naming scheme for roff documents, though
.IB file. tr
for
.I troff file
is seen now and then.
.
Maybe there should be a standardization for the filename extensions of
roff files.
.
.P
File name extensions can be very handy in conjunction with the
.BR less (1)
pager.
.
It provides the possibility to feed all input into a command-line pipe
that is specified in the shell environment variable
.BR LESSOPEN .
This process is not well documented, so here an example:
.
.IP
.B LESSOPEN='|lesspipe %s'
.
.P
where
.B lesspipe
is either a system supplied command or a shell script of your own.
.
.
.\" --------------------------------------------------------------------
.SH "EDITING ROFF"
.\" --------------------------------------------------------------------
.
The best program for editing a roff document is Emacs (or Xemacs), see
.BR emacs (1).
It provides an
.I nroff
mode that is suitable for all kinds of roff dialects.
.
This mode can be activated by the following methods.
.
.P
When editing a file within Emacs the mode can be changed by typing
.RI ` "M-x nroff-mode" ',
where
.B M-x
means to hold down the
.B Meta
key (or
.BR Alt )
and hitting the
.BR x\~ key
at the same time.
.
.P
But it is also possible to have the mode automatically selected when
the file is loaded into the editor.
.
.Topic
There is a set of file name extensions, e.g. the man pages that
trigger the automatic activation of the nroff mode.
.Topic
Any file containing the character
sequence
.B \%-*-\ nroff\ -*-
in the first line is switched into nroff mode when loaded.
.
But do not use this, it confuses some applications such as the
.B man
program.
.
.Topic
The best method is to include the following 3 comment lines at the end
of the file.
.
.IP
.nf
.B .\*[comment] Local Variables:
.B .\*[comment] mode: nroff
.B .\*[comment] End:
.fi
.
.P
All roff processors handle automated spacing after the end of a
sentence.
.
The safest way to not disturb this or to mix it up with abbreviations
is to start each sentence on a line of its own without preceding white
space.
.
To additionally use the auto-fill mode in Emacs, it is best to insert
an empty roff request (a line consisting of a dot
.quoted_char .
only) after each sentence.
.
This suits the general roff rule to never use blank lines because they
can produce unexpected behavior in the vertical spacing; so each line
that is supposed to be empty or blank should instead use the line
comment
.B .\*[comment]
or the empty request, a line consisting of a dot only.
.
The following example shows how optimal roff editing could look.
.
.IP
.nf
This is a sentence.
.Text .
This is a longer sentence stretching over
several lines.
.Text .
etc.
.fi
.
.P
Besides Emacs, some other editors provide nroff style files too, e.g.\&
.BR vim (1),
an extension of the
.BR vi (1)
program.
.
.
.\" --------------------------------------------------------------------
.SH BUGS
.\" --------------------------------------------------------------------
.
.I UNIX\[rg]
is a registered trademark of the Open Group.
.
.
.\" --------------------------------------------------------------------
.SH "SEE ALSO"
.\" --------------------------------------------------------------------
.
There is a lot of documentation on roff.
.
The original papers on classical troff are still available, and all
aspects of groff are documented in great detail.
.
.
.\" --------------------------------------------------------------------
.SS "Historical roff Documentation"
.\" --------------------------------------------------------------------
.
Many classical
.troff
documents are still available on-line.
.
.P
The old history is best documented at the
.URL http://\:www.multicians.org "Multics site" .
This contains a lot of information on the MIT projects, CTSS, Multics,
early Unix, including runoff.
.
Especially useful are a glossary and the many links to other documents.
.
.P
The web site
.URL http://\:cm.bell-labs.com/\:cm/\:index.html \
     "Bell Labs Computing and Mathematical Sciences Research"
provides a search facility for tracking information on the early
developers.
.
.P
The best documentation on the issues of the original, free Unix with
its standard programs are the papers in the series
.URL http://\:cm.bell-labs.com/\:cm/\:cs/\:cstr.html "Bell Labs CSTR" .
.
These also contain the two main documents of the early nroff/troff,
being
.TP
.I [CSTR\~#54]
The 1992\~revision of Osanna/Kernighan's 1976\~paper
.URL http://\:cm.bell-labs.com/\:cm/\:cs/\:54.ps \
     "Nroff/\:Troff User's Manual" .
.TP
.I [CSTR\~#97]
Brian Kernighan's 1979\~paper
.URL http://\:cm.bell-labs.com/\:cm/\:cs/\:97.ps \
     "A Typesetter-independent TROFF" .
.
.
.\" --------------------------------------------------------------------
.SS "Manual Pages"
.\" --------------------------------------------------------------------
.
The
.I manual pages
or shortly
.I man pages
are the main documentation system on many operating system.
.
Due to its complex structure, a full roff system has many man pages,
each describing a single aspect of roff.
.
.P
A reference to a man page looks like this:
.BR groff (@MAN7EXT@).
.
This refers to the manual page on
.I groff
in section\~\c
.IR 7 .
.
To read the example, call from the shell prompt
.
.P
.ShellCommand man @MAN7EXT@ groff
.
.P
For more details, see the documentation of the
.B man
program in section\~1, i.e.
.BR man (@MAN1EXT@).
.
.P
For the different roff implementations, there is no general naming
scheme for its documentation.
.
In
.IR groff ,
the man page
.BR groff (@MAN1EXT@)
contains a survey of all documentation available in groff.
.
On other systems, you are on your own, but
.BR troff (1)
might be a good starting point.
.
.
.\" --------------------------------------------------------------------
.SH AUTHORS
.\" --------------------------------------------------------------------
.
Copyright (C) 2000, 2001, 2002 Free Software Foundation, Inc.
.
.P
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
.URL http://\:www.gnu.org/\:copyleft/\:fdl.html "GNU copyleft site" .
.
.P
This document is part of
.IR groff ,
the GNU roff distribution.
.
It was written by
.MTO bwarken@mayn.de "Bernd Warken" ;
it is maintained by
.MTO wl@gnu.org "Werner Lemberg".
.
.
.\" --------------------------------------------------------------------
.\" Emacs setup
.\" --------------------------------------------------------------------
.
.\" Local Variables:
.\" mode: nroff
.\" End: