troff
Version 2, June 1991
Copyright (C) 1989, 1991 Free Software Foundation, Inc. 59 Temple Place, Suite 330, Boston, MA 02111, USA Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.
The licenses for most software are designed to take away your freedom to share and change it. By contrast, the GNU General Public License is intended to guarantee your freedom to share and change free software -- to make sure the software is free for all its users. This General Public License applies to most of the Free Software Foundation's software and to any other program whose authors commit to using it. (Some other Free Software Foundation software is covered by the GNU Library General Public License instead.) You can apply it to your programs, too.
When we speak of free software, we are referring to freedom, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for this service if you wish), that you receive source code or can get it if you want it, that you can change the software or use pieces of it in new free programs; and that you know you can do these things.
To protect your rights, we need to make restrictions that forbid anyone to deny you these rights or to ask you to surrender the rights. These restrictions translate to certain responsibilities for you if you distribute copies of the software, or if you modify it.
For example, if you distribute copies of such a program, whether gratis or for a fee, you must give the recipients all the rights that you have. You must make sure that they, too, receive or can get the source code. And you must show them these terms so they know their rights.
We protect your rights with two steps: (1) copyright the software, and (2) offer you this license which gives you legal permission to copy, distribute and/or modify the software.
Also, for each author's protection and ours, we want to make certain that everyone understands that there is no warranty for this free software. If the software is modified by someone else and passed on, we want its recipients to know that what they have is not the original, so that any problems introduced by others will not reflect on the original authors' reputations.
Finally, any free program is threatened constantly by software patents. We wish to avoid the danger that redistributors of a free program will individually obtain patent licenses, in effect making the program proprietary. To prevent this, we have made it clear that any patent must be licensed for everyone's free use or not licensed at all.
The precise terms and conditions for copying, distribution and modification follow.
NO WARRANTY
If you develop a new program, and you want it to be of the greatest possible use to the public, the best way to achieve this is to make it free software which everyone can redistribute and change under these terms.
To do so, attach the following notices to the program. It is safest to attach them to the start of each source file to most effectively convey the exclusion of warranty; and each file should have at least the "copyright" line and a pointer to where the full notice is found.
one line to give the program's name and an idea of what it does. Copyright (C) 19yy name of author This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, USA.
Also add information on how to contact you by electronic and paper mail.
If the program is interactive, make it output a short notice like this when it starts in an interactive mode:
Gnomovision version 69, Copyright (C) 19yy name of author Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'. This is free software, and you are welcome to redistribute it under certain conditions; type `show c' for details.
The hypothetical commands `show w' and `show c' should show the appropriate parts of the General Public License. Of course, the commands you use may be called something other than `show 'w and `show c'; they could even be mouse-clicks or menu items -- whatever suits your program.
You should also get your employer (if you work as a programmer) or your school, if any, to sign a "copyright disclaimer" for the program, if necessary. Here is a sample; alter the names:
Yoyodyne, Inc., hereby disclaims all copyright interest in the program `Gnomovision' (which makes passes at compilers) written by James Hacker. signature of Ty Coon, 1 April 1989 Ty Coon, President of Vice
This General Public License does not permit incorporating your program into proprietary programs. If your program is a subroutine library, you may consider it more useful to permit linking proprietary applications with the library. If this is what you want to do, use the GNU Library General Public License instead of this License.
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 @acronym{UNIX} community.
groff?
groff belongs to an older generation of document preparation
systems, which operate more like compilers than the more recent
interactive @acronym{WYSIWYG}(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 which includes
an editor and a text formatter. Also, many word processors follow the
@acronym{WYSIWYG} paradigm which was discussed earlier.
Although @acronym{WYSIWYG} systems may be easier to use, they have a
number of disadvantages compared to troff:
troff is firmly entrenched in all @acronym{UNIX} systems.
"GUIs normally make it simple to accomplish simple actions and impossible to accomplish complex actions." --Doug Gwyn (22/Jun/91 in
comp.unix.wizards)
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 has then been rewritten as rf for the
PDP-7 (before having @acronym{UNIX}), and at the same time (1969), Doug
McIllroy rewrote an extended and simplified version of roff in
the @acronym{BCPL} programming language.
The first version of @acronym{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 which 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 @acronym{UNIX}.
The eqn preprocessor allowed mathematical formul@ae{} 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 an auto accident.
So, Brian Kernighan took on the task of rewriting troff. The
newly rewritten version produced a 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:
ditroff with many extensions.
soelim, pic, tbl, and eqn preprocessors.
troff also eliminated the need for a
separate nroff program with a postprocessor which would produce
@acronym{ASCII} output.
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 grohtml, an
output device to produce @acronym{HTML} output, have been added.
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:
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'.
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, @acronym{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, in 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).
groff actually produces device independent code which may be fed
into a postprocessor which will produce output for a particular device.
Currently, groff has postprocessors for @acronym{PostScript}
devices, character terminals, X Windows (for previewing), TeX DVI
format, HP LaserJet 4 and Canon LBP printers (which use
@acronym{CAPSL}), and @acronym{HTML}.
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.
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
section Environment, for more details). Thus, for example, geqn is
GNU eqn. On operating systems like Linux or the Hurd, which
don't contain proprietary software, 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.
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 section Invoking gpic, section Invoking geqn, section Invoking gtbl, section Invoking ggrn, section Invoking grefer, section Invoking gsoelim, section Invoking grotty, section Invoking grops, section Invoking grohtml, section Invoking grodvi, section Invoking grolj4, section Invoking grolbp, and section Invoking gxditview.
The command line format for groff is:
groff [ -abeghilpstvzCEGNRSUVXZ ] [ -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 [ -abivzCERU ] [ -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 @option{-}. 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:
geqn.
gtbl.
ggrn.
grap.
gpic.
gsoelim.
grefer. No mechanism is provided for passing
arguments to grefer because most grefer options have
equivalent commands which can be included in the file. See section grefer,
for more details.
Note that gtroff also accepts a @option{-R} option, which is not
accessible via groff. This option prevents the loading of the
`troffrc' and `troffrc-end' files.
groff print out their version number.
gtroff. Only error messages will be
printed.
gtroff. Normally groff
will automatically run the appropriate postprocessor.
groff does not
prepend `-' to arg before passing it to the postprocessor.
groff does not prepend a
`-' to arg before passing it to the postprocessor.
groff was configured and built. The
following are the output devices currently available:
ps
dvi
X75
X100
ascii
latin1
utf8
cp1047
lj4
lbp
html
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). See section Built-in Registers.
The postprocessor to be used for a device is specified by the
postpro command in the device description file. (See section Font Files, for more info.) This can be overridden with the @option{-X}
option.
gxditview instead of using the usual postprocessor.
This is unlikely to produce good results except with @option{-Tps}.
Note that this is not the same as using @option{-TX75} or
@option{-TX100} to view a document with gxditview: The former
will use the metrics of the specified device, whereas the latter will
use X-specific fonts and metrics.
eqn delimiters. This is the same as
the @option{-N} option in geqn.
gpic and use the
@option{-msafer} macros with gtroff (enabled by default).
.A is then set to 1. See section Built-in Registers.
gtroff can get
confused by as or am requests while counting line numbers.
groff and traditional Unix
troff.
groff.
gtroff will exit 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. See section Built-in Registers.
gtroff numeric expression.
gsoelim. It implies the
@option{-s} option.
There are also several environment variables (of the operating system,
not within gtroff) which can modify the behavior of groff.
GROFF_COMMAND_PREFIX
groff will run
Xtroff instead of gtroff. This also applies to
tbl, pic, eqn, grn, refer, and
soelim. It does not apply to grops, grodvi,
grotty, grohtml, grolj4, and gxditview.
GROFF_TMAC_PATH
GROFF_TYPESETTER
GROFF_FONT_PATH
devname directory.
PATH
groff.
GROFF_TMPDIR
grops and grefer commands
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.
This section will list several common uses of groff and the
command line which will accomplish it.
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. The
manual page `file' is processed with the `mandoc' macros
(which in turn either calls the `man' or the `mdoc' macro
package), using the tbl preprocessor and the @acronym{ASCII}
output device. Finally, the result is displayed with the less
pager.
groff -X -m me file
Preview `file' with gxditview, using the `me' macro
package. Since no @option{-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
@acronym{UNIX}.(2)
groff -man -rD1 -z file
Check `file' with the `man' macro package, forcing double-sided printing -- don't produce any output.
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.
The options generated are one of @option{-e}, @option{-man},
@option{-me}, @option{-mm}, @option{-ms}, @option{-p}, @option{-R},
@option{-g}, @option{-G}, @option{-s}, and @option{-t}.
A special file name `-' is taken to refer to the standard input. If no files are specified the standard input will be read. Any specified options will be included in the printed command. No space is allowed between options and their arguments. For example,
grog -Tdvi paper.ms
will guess the appropriate command to print `paper.ms' and then
print it to the command line after adding the @option{-Tdvi} option.
For direct execution, enclose the call to grog in backquotes at
the @acronym{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).
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.
This section covers some of the basic concepts necessary to understand how to use a macro package.(3) 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 section 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. More details
on this can be found in section 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,...
will be 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,...
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 do blank input lines and input lines beginning with a space.
Not all input lines are text to be formatted. Some of the 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 will pack words onto longer lines anyhow. In
keeping with this, it is helpful to begin a new line after every period,
comma, or phrase, since common corrections are to add or delete
sentences or phrases. Secondly, do not hyphenate words at the end of
lines -- gtroff is smart enough to hyphenate words for the user
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 will double space output text automatically if you use the
request `.ls 2'. Single spaced mode can be reactivated by
typing `.ls 1'.
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 white space (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.
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.
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.
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 will not line up
with the text on second and subsequent lines,
although they will line up with each other.
A variation of this is a bulleted list.
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.
Every macro package gives some way to manipulate the headers and footers (or titles) on each page. Some packages will 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 section Page Layout, for more details).
Most macro packages let the user specify top and bottom margins and other details about the appearance of the printed pages.
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 will not.
Floating keeps move relative to the text. Hence, they are good for things which will be referred to by name, such as "See figure 3". A floating keep will appear at the bottom of the current page if it will fit; otherwise, it will appear at the top of the next page. Meanwhile, the surrounding text will `flow' around the keep, thus leaving now blank areas.
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.
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 will provide the ability to have several tables of contents (i.e. one standard one, one for tables, etc).
While some macro packages will use the term index, none actually provide that functionality. The facilities they call indices are actually more appropriate for tables of contents.
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.
Some macro packages (but not `man') provide the ability to have two or more columns on a page.
The built-in font and size functions are not always intuitive, so all macro packages provide macros to make these operations simpler.
Most macro packages provide various predefined strings for a variety of uses; examples are sub- and superscripts, printable dates, quotes and various special characters.
All macro packages provide support for the various preprocessors.
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.
This chapter documents the main macro packages that come with
groff.
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.
The command line format for using the `man' macros with
groff is:
groff -m man [ -rC1 ] [ -rD1 ] [ -rPnnn ] [ -rSxx ]
[ -rXnnn ] [ files... ]
It is possible to use `-man' instead of `-m man'.
-rC1
-rD1
-rPnnn
-rSxx
-rXnnn
This section describes the available macros for manual pages. For further customization, put additional macros and requests into the file `man.local' which will be loaded immediately after `tmac.an'.
@Defmac{TH, title section [extra1] [extra2] [extra3]} Sets the title of the man page to title and the section to section, which must have a value between 1 and 8. The value of section may also have a string appended, e.g. `.pm', to indicate a specific subsection of the man pages.
Both title and section are positioned at the left and right in the header line (with section in parentheses immediately appended to title. extra1 will be positioned in the middle of the footer line. extra2 will be positioned at the left in the footer line (resp. at the left on even pages and at the right on odd pages if double-sided printing is active). extra3 is centered in the header line.
For @acronym{HTML} output, headers and footers are completely suppressed.
Additionally, this macro starts a new page; the new line number is 1
again (except if the @option{-rC1} option is given on the command line)
-- this feature is intended only for formatting multiple man pages; a
single man page should contain exactly one TH macro at the
beginning of the file.
@end_Defmac
@Defmac{SH, [heading]}
Sets up an unnumbered section heading sticking out to the left. Prints
out all the text following SH up to the end of the line (resp.
the text in the next line if there is no argument to SH) in bold
face, one size larger than the base document size. Additionally, the
left margin for the following text is reset to its default value.
@end_Defmac
@Defmac{SS, [heading]}
Sets up an unnumbered section heading. Prints out all the text
following SS up to the end of the line (resp. the text in the
next line if there is no argument to SS) in bold face, at the
same size as the base document size. Additionally, the left margin for
the following text is reset to its default value.
@end_Defmac
@Defmac{TP, [nnn]} Sets up an indented paragraph with label. The indentation is set to nnn if that argument is supplied (the default unit is `n' if omitted), otherwise it is set to the default indentation value.
The first line of text following this macro is interpreted as a string to be printed flush-left, as it is appropriate for a label. It is not interpreted as part of a paragraph, so there is no attempt to fill the first line with text from the following input lines. Nevertheless, if the label is not as wide as the indentation, then the paragraph starts at the same line (but indented), continuing on the following lines. If the label is wider than the indentation, then the descriptive part of the paragraph begins on the line following the label, entirely indented. Note that neither font shape nor font size of the label is set to a default value; on the other hand, the rest of the text will have default font settings. @end_Defmac
@Defmac{LP}
@Defmacx{PP}
@Defmacx{P}
These macros are mutual aliases. Any of them causes a line break at the
current position, followed by a vertical space downwards by the amount
specified by the PD macro. The font size and shape are reset to
the default value (10pt resp. Roman). Finally, the current left
margin is restored.
@end_Defmac
@Defmac{IP, [designator] [nnn]}
Sets up an indented paragraph, using designator as a tag to mark
its beginning. The indentation is set to nnn if that argument is
supplied (default unit is `n'), otherwise the default indentation
value is used. Font size and face of the paragraph (but not the
designator) are reset to their default values. To start an indented
paragraph with a particular indentation but without a designator, use
`""' (two double quotes) as the first argument of IP.
For example, to start a paragraph with bullets as the designator and 4en indentation, write
.IP \(bu 4
@end_Defmac
@Defmac{HP, [nnn]} Sets up a paragraph with hanging left indentation. The indentation is set to nnn if that argument is supplied (default unit is `n'), otherwise the default indentation value is used. Font size and face are reset to their default values. @end_Defmac
@Defmac{RS, [nnn]}
This macro moves the left margin to the right by the value nnn if
specified (default unit is `n'); otherwise the default indentation
value is used. Calls to the RS macro can be nested.
@end_Defmac
@Defmac{RE, [nnn]}
This macro moves the left margin back to level nnn; if no argument
is given, it moves one level back. The first level (i.e., no call to
RS yet) has number 1, and each call to RS increases
the level by 1.
@end_Defmac
To summarize, the following macros cause a line break with the insertion
of vertical space (which amount can be changed with the PD
macro): SH, SS, TP, LP (PP,
P), IP, and HP.
The macros RS and RE also cause a break but do not insert
vertical space.
The standard font is Roman; the default text size is 10 point.
@Defmac{SM, [text]} Causes the text on the same line or the text on the next line to appear in a font that is one point size smaller than the default font. @end_Defmac
@Defmac{SB, [text]} Causes the text on the same line or the text on the next line to appear in boldface font, one point size smaller than the default font. @end_Defmac
@Defmac{BI, text} Causes text on the same line to appear alternately in bold face and italic. The text must be on the same line as the macro call. Thus,
.BI this "word and" that
would cause "this" and "that" to appear in bold face, while "word and" appears in italics. @end_Defmac
@Defmac{IB, text} Causes text to appear alternately in italic and bold face. The text must be on the same line as the macro call. @end_Defmac
@Defmac{RI, text} Causes text on the same line to appear alternately in roman and italic. The text must be on the same line as the macro call. @end_Defmac
@Defmac{IR, text} Causes text on the same line to appear alternately in italic and roman. The text must be on the same line as the macro call. @end_Defmac
@Defmac{BR, text} Causes text on the same line to appear alternately in bold face and roman. The text must be on the same line as the macro call. @end_Defmac
@Defmac{RB, text} Causes text on the same line to appear alternately in roman and bold face. The text must be on the same line as the macro call. @end_Defmac
@Defmac{R, [text]} Causes text to appear in roman font. If no text is present on the line where the macro is called, then the text of the next line appears in roman. This is the default font to which text is returned at the end of processing of the other macros. @end_Defmac
@Defmac{B, [text]} Causes text to appear in bold face. If no text is present on the line where the macro is called, then the text of the next line appears in bold face. @end_Defmac
@Defmac{I, [text]} Causes text to appear in italic. If no text is present on the line where the macro is called, then the text of the next line appears in italic. @end_Defmac
The default indentation is 7.2n for all output devices except for
grohtml which uses 1.2i instead.
@Defmac{DT}
Sets tabs every 0.5 inches. Since this macro is always called
during a TH request, it makes sense to call it only if the tab
positions have been changed.
@end_Defmac
@Defmac{PD, [nnn]} Adjusts the empty space before a new paragraph (resp. section). The optional argument gives the amount of space (default units are `v'); without parameter, the value is reset to its default value (1 line for tty devices, 0.4v otherwise). @end_Defmac
This affects the macros SH, SS, TP, LP
(resp. PP and P), IP, and HP.
The following strings are defined:
@Defmac{\\*S} Switch back to the default font size. @end_Defmac
@Defmac{\\*R} The `registered' sign. @end_Defmac
@Defmac{\\*(Tm} The `trademark' sign. @end_Defmac
@Defmac{\\*(lq}
@Defmacx{\\*(rq}
Left and right quote.
This is equal to \(lq and \(rq, respectively.
@end_Defmac
If a preprocessor like gtbl or geqn is needed, it has
become common usage to make the first line of the man page look like
this:
.\" word
Note the single space character after the double quote. word
consists of letters for the needed preprocessors: `e' for
geqn, `r' for grefer, `t' for gtbl.
Modern implementations of the man program read this first line
and automatically call the right preprocessor(s).
This chapter covers all of the facilities of gtroff.
Users of macro packages may skip it if not interested in details.
gtroff input files contain text with control commands
interspersed throughout. But, even without control codes, gtroff
will still do several things with the input text: filling and adjusting,
adding additional space after sentences, hyphenating and inserting
implicit line breaks.
When gtroff reads in text it collects words from input and fits
as many of them together on one output line as it can. This is known as
filling.
Once gtroff has a filled line it will try to adjust
it. This means it will widen the spacing between words until the text
reaches the right margin (in the default adjustment mode). Extra spaces
between words are preserved, but spaces at the end of lines are ignored.
Spaces at the front of a line will cause a break (breaks will be
explained in section Implicit Line Breaks)
See section Manipulating Filling and Adjusting.
Since the odds are not great for finding a set of words, for every
output line, which will fit nicely on a line without inserting excessive
amounts of space between words, gtroff will hyphenate words so
that lines can be justified without there being too much space between
words. It uses an internal hyphenation algorithm (a simplified version
of the algorithm used within TeX) to indicate which words can be
hyphenated and how to do so. When a word is hyphenated the first part
of the word will be added to the current filled line being output (with
an attached hyphen), and the other portion will be added to the next
line to be filled.
See section Manipulating Hyphenation.
Although it is often debated, some typesetting rules say there should be different amounts of space after various punctuation marks. For example, the Chicago typsetting manual says that a period at the end of a sentence should have twice as much space following it as would a comma or a period as part of an abbreviation.
gtroff does this by flagging certain characters (normally
`!', `?' and `.') as end of sentence characters.
When gtroff encounters one of these characters at the end of a
line it will append two sentence spaces in the formatted output.
(This justifies one of the conventions mentioned in section Input Conventions.)
In addition, the following characters resp. glyphs are treated
transparently while handling end of sentence characters: `"',
`'', `)', `]', `*', dg, and rq.
See the cflags request in section Using Symbols, for more details.
To prevent the insertion of extra space after an end of sentence
character (at the end of a line), append \&.
gtroff translates tabulator characters, also called
tabs (normally code point @acronym{ASCII} 0x09 resp.
@acronym{EBCDIC} 0x05), in the input into movements to the next
tabulator stop. These tab stops are initially located every half inch
across the page. Using this, simple tables can easily be made.
However, it can often be deceptive as the appearance (and width) of the
text on a terminal and the results from gtroff can vary greatly.
Also, a possible sticking point is that lines beginning with tab characters will still be filled, again producing unexpected results. For example, the following input
An important concept in gtroff is the break. When a break
occurs, gtroff will output the partially filled line
(unjustified), and resume collecting and filling text on the next output
line.
There are several ways to cause a break in gtroff. A blank line
will not only cause a break, but it will also cause a one line vertical
space (effectively a blank line) to be output.
A line which begins with a space will cause a break and the space will be output at the beginning of the next line. Note that this space isn't adjusted, even in fill mode.
The end of file will also cause a break -- otherwise the last line of the document may vanish!
Certain requests also cause breaks, implicitly or explicitly. This will be discussed in section Manipulating Filling and Adjusting.
Since gtroff does filling automatically, it is traditional in
groff not to try and type things in as nicely formatted
paragraphs. These are some conventions commonly used when typing
gtroff text:
gtroff (like any other programs) requires numeric parameters to
specify various measurements. Most numeric parameters(4) may have a
measurement unit attached. These units are specified as a single
character which immediately follows the number or expression. Each of
these units are understood, by gtroff, to be a multiple of its
basic unit. So, whenever a different measurement unit is
specified gtroff converts this into its basic units. This
basic unit, represented by a `u', is a device dependent measurement
which is quite small, ranging from 1/75th to 1/72000th of an inch. The
values may be given as fractional numbers; however, fractional basic
units are always rounded to integers.
Some of the measurement units are completely independent of any of the
current settings (e.g. type size) of gtroff.
i
c
p
P
s
z
The other measurements understood by gtroff are dependent on
settings currently in effect in gtroff. These are very useful
for specifying measurements which should look proper with any size of
text.
m
n
v
M
Many requests take a default unit. While this can be helpful at times, it can cause strange errors in some expressions. For example, the line length request expects em units. Here are several attempts to get a line length of 3.5 inches and their results:
3.5i => 3.5i 7/2 => 0i 7/2i => 0i 7i/2 => 0.1i 7i/2u => 3.5i
Everything will be converted to basic units first. In the above example it is assumed that 1i equals 240u, and 1m equals 10p (thus 1m equals 33u). The value 7i/2 will be first handled as 7i/2m, then converted to 1680u/66u which is 25u, and this is approximately 0.1i.
As a conclusion, the safest way to specify measurements is to always attach a scaling indicator. If you want to multiply or divide by a certain scalar value, use `u' as the unit for that value.
gtroff has most of operators common to other languages:
gtroff only provides integer arithmetic. The internal type used
for computing results is `int', which is usually a 32bit
signed integer.
if and while requests). See
below for the use of unary operators in motion requests.
(c;e). Evaluate e using c as
the default scaling indicator. If c is missing, ignore scaling
indicators in the evaluation of e.
Parentheses may be used as in any other language. However, in
gtroff they are necessary to ensure order of evaluation.
gtroff has no operator precedence; expressions are evaluated left
to right. This means that `3+5*4' is evaluated as if it were
parenthesized like `(3+5)*4', not as `3+(5*4)', as might be
expected.
For many requests which cause a motion on the page, the unary operators
work differently. The `+' and `-' operators then indicate a
motion relative to the current position (down or up, respectively), and
the `|' operator indicates an absolute position on the page or
input line.
`+' and `-' are also treated differently by the following
requests and escapes: bp, in, ll, lt,
nm, nr, pl, pn, po, ps,
rt, ti, \R, and \s. Here the plus and minus
signs indicate increments resp. decrements.
See section Setting Registers.
Due to the way arguments are parsed, spaces are not allowed in expressions, unless the entire expression is surrounded by parentheses.
See section Request Arguments, and section Conditionals and Loops.
Like any other language, gtroff has rules for properly formed
identifiers. In gtroff, an identifier can be made up of
almost any printable character, with the exception of the following
characters:
0x08 resp. @acronym{EBCDIC}@w{
}0x16) and character code 0x01.
groff runs on a machine based on @acronym{ASCII}, causing a
warning message of type `input' (see section Debugging, for more
details): 0x00, 0x0B, 0x0D-0x1F,
0x80-0x9F.
And here are the invalid input characters if groff runs on an
@acronym{EBCDIC} host: 0x00, 0x08, 0x09,
0x0B, 0x0D-0x14, 0x17-0x1F,
0x30-0x3F.
Currently, some of these reserved codepoints are used internally, thus
making it non-trivial to extend gtroff to cover Unicode or other
character sets resp. encodings which use characters of these ranges.
Note that invalid characters will be removed before parsing; an
identifier foo, followed by an invalid character, followed by
bar will be treated as foobar.
For example, any of the following is valid.
br PP (l end-list @_
Note that identifiers longer than two characters with a closing bracket (`]') in its name can't be accessed with escape sequences which expect an identifier as a parameter. For example, `\[foo]]' will access the glyph `foo', followed by `]', whereas `\C'foo]'' really asks for glyph `foo]'.
@Deffn{Escape, \\A, ident}
Whether an identifier ident is valid in gtroff can be
tested with the \A escape. It expands to the character 1
or 0 according to whether its argument (usually delimited by quotes)
is or is not acceptable as the name of a string, macro, diversion,
number register, environment, or font. It will return 0 if no
argument is given. This is useful for looking up user input in some
sort of associative table.
\A'end-list'
=> 1
@end_Deffn
See section Escapes, for details on parameter delimiting characters.
Identifiers in gtroff can be any length, but, in some contexts,
gtroff needs to be told where identifiers end and text begins
(and in different ways depending on their length):
gtroff only). Must be bracketed with `['
and `]' in some situations. Any length identifier can be put
in brackets.
Unlike many other programming languages, undefined identifiers are silently ignored or expanded to nothing.
See section Interpolating Registers, and section Strings.
Most documents need more functionality beyond filling, adjusting and
implicit line breaking. In order to gain further functionality,
gtroff allows commands to be embedded into the text, in two ways.
The first is a request which takes up an entire line, and does some large scale operation (e.g. break lines, start new pages).
The other is an escape which can be embedded anywhere in the text, or even as an argument to a request. Escapes generally do more minor operations like sub- and superscripts, print a symbol, etc.
A request line begins with a control character, which is either a single quote (`'', the no-break control character) or a period (`.', the normal control character). These can be changed; see section Character Translations, for details. After this there may be optional tabs or spaces followed by an identifier which is the name of the request. This may be followed by any number of space-separated arguments.
To begin a line with a control character without it being interpreted,
precede it with \&. This represents a zero width space, which
means it will not affect the output.
In most cases the period is used as a control character. Several requests will cause a break implicitly; using the single quote control character will prevent this.
Arguments to requests (and macros) are processed much like the shell: The line is split into arguments according to spaces. An argument which is intended to contain spaces can either be enclosed in quotes (single or double), or have the spaces escaped with backslashes.
Here are a few examples:
.uh The Mouse Problem .uh "The Mouse Problem" .uh The\ Mouse\ Problem
The first line is the uh macro being called with 3 arguments,
`The', `Mouse', and `Problem'. The latter two have the
same effect or calling the uh macro with one argument, `The
Mouse Problem'.(5)
Note, however, that the ds request works differently.
See section Strings, for more details.
gtroff has a macro facility for defining a series of lines
which can be invoked by name. They are called in the same manner as
requests -- arguments also may be passed in the same manner.
See section Writing Macros, and section Request Arguments.
Escapes may occur anywhere in the input to gtroff. They usually
begin with a backslash and are followed by a single character which
indicates the function to be performed. The escape character can be
changed; see section Character Translations.
Escape sequences which require an identifier as a parameter accept three possible syntax forms.
Examples:
\fB \n(XX \*[TeX]
Other escapes may require several arguments and/or some special format. In such cases the argument is traditionally enclosed in single quotes (and quotes are always used in this manual for the definitions of escape sequences). The enclosed text is then processed according to what that escape expects. Example:
\l'1.5i\(bu'
Note that the quote character can be replaced with any other character
which does not occur in the argument (even a newline or a space
character) in the following escapes: \o, \b, and
\X. This makes e.g.
A caf \o e\' in Paris => A caf'e in Paris
possible, but it is better not to use this feature to avoid confusion.
The following escapes sequences (which are handled similarly to
characters since they don't take a parameter) are also allowed as
delimiters: \%, `\ ', \|, \^, \{,
\}, \', \`, \-, \_, \!,
\?, \@, \), \/, \,, \&,
\~, \0, \a, \c, \d, \e,
\E, \p, \r, \t, and \u. Again, don't
use these if possible.
No newline characters as delimiters are allowed in the following
escapes: \A, \Z, \C, and \w.
Finally, the escapes \D, \h, \H, \l,
\L, \N, \R, \s, \S, \v, and
\x can't use the following characters as delimiters:
0-9.
\%, \{, \},
\', \`, \-, \_, \!, \@,
\/, \c, \e, and \p.
To have a backslash (resp. the current escape character) appear in the
output several escapes are defined: \\, \e or \E.
These are very similar, and only differ with respect to being used in
macros or diversions. See section Copy-in Mode, and section Diversions, for
more information.
See section Identifiers, and section Character Translations.
Probably one of the most(6) common forms of escapes is the comment.
@Deffn{Escape, \\"} Start a comment. Everything to the end of the input line is ignored.
This may sound simple, but it can be tricky to keep the comments from interfering with the appearance of the final output.
If the escape is to the right of some text or a request, that portion of
the line will be ignored, but the space leading up to it will be noticed
by gtroff. This only affects the .ds request.
One possibly irritating idiosyncracy is that tabs must not be used to line up comments. Tabs are not treated as white space between the request and macro arguments.
A comment on a line by itself will be treated as a blank line, because after eliminating the comment, that is all that remains:
Test \" comment Test
will produce
Test Test
As a consequence, it is common to start the line with .\" which
will cause the line to be treated as an undefined request and thus
ignored completely.
Another commenting scheme seen sometimes is three consecutive single
quotes ("') at the beginning of a line. This works, but
gtroff will give a warning about an undefined macro (namely
"), which is harmless, but irritating.
@end_Deffn
@Deffn{Escape, \\#}
To avoid all this, gtroff has a new comment mechanism using
the \# escape. This escape works the same as \" except
that the newline is also ignored:
Test \# comment Test
will produce
Test Test
as expected. @end_Deffn
For commenting away large blocks of text, the ig request may be
useful.
See section Strings.
Numeric variables in gtroff are called registers. There
are a number of built-in registers, supplying anything from the date to
details of formatting parameters.
See section Identifiers, for details on register identifiers.
Registers are defined resp. set via the nr request or the
\R escape.
@Deffn{Request, nr, ident value} @Deffnx{Escape, \\R, ident value} Set number register ident to value. If ident doesn't exist, it will be created.
The argument to \R has to be enclosed in quotes usually.
See section Escapes, for details on parameter delimiting characters.
@end_Deffn
For example, the following two lines are equivalent:
.nr a 1 \R'a 1'
Both nr and \R have two additional special forms to
increment resp. decrement a register.
@Deffn{Request, nr, ident +value} @Deffnx{Request, nr, ident -value} @Deffnx{Escape, \\R, ident +value} @Deffnx{Escape, \\R, ident -value} Increment (decrement) register ident by value.
.nr a 1
.nr a +1
\na
=> 2
To assign the negated value of a register to another register, some care must be taken to get the desired result:
.nr a 7
.nr b 3
.nr a -\nb
\na
=> 4
.nr a (-\nb)
\na
=> -3
The surrounding parentheses prevent the interpretation of the minus sign as a decrementing operator. An alternative is to start the assignment with a `0':
.nr a 7
.nr b -3
.nr a \nb
\na
=> 4
.nr a 0\nb
\na
=> -3
@end_Deffn
@Deffn{Request, rr, ident} Remove number register ident. If ident doesn't exist, the request is ignored. @end_Deffn
@Deffn{Request, rnn, ident1 ident2} Rename number register ident1 to ident2. If either ident1 or ident2 doesn't exist, the request is ignored. @end_Deffn
@Deffn{Request, aln, ident1 ident2} This request creates an alias ident1 for a number register ident2. The new name and the old name will be exactly equivalent. If ident1 is undefined, a warning of type `reg' will be generated, and the request will be ignored. See section Debugging, for information about warnings. @end_Deffn
Numeric registers can be accessed via the \n escape.
@Deffn{Escape, \\n, ident}
Interpolate number register ident. This means that the value of
the register is expanded in-place while gtroff is parsing the
input line.
.nr a 5
.nr as \na+\na
\n(as
=> 10
@end_Deffn
Number registers can also be auto-incremented and auto-decremented. The
increment resp. decrement factor can be specified with a third
argument to the nr request or \R escape.
@Deffn{Request, nr, ident value incr}
Set number register ident to value; the increment for
auto-incrementing is set to incr. Note that the \R escape
doesn't support this notation.
@end_Deffn
To activate auto-incrementing, the escape \n has a special syntax
form.
@Deffn{Escape, \\n, +ident}
@Deffnx{Escape, \\n, -ident}
Before interpolating, increment resp. decrement ident by the
auto-increment value as specified with the nr request (or the
\R escape). If no auto-increment value has been specified, both
syntax forms are identical to \n.
@end_Deffn
For example,
.nr a 0 1 .nr xx 0 5 .nr foo 0 -2 \n+a, \n+a, \n+a, \n+a, \n+a .br \n-(xx, \n-(xx, \n-(xx, \n-(xx, \n-(xx .br \n+[foo], \n+[foo], \n+[foo], \n+[foo], \n+[foo]
produces
1, 2, 3, 4, 5 -5, -10, -15, -20, -25 -2, -4, -6, -8, -10
To change the increment value without changing the value of a register, the following can be used:
.nr a \na 10
When a register is used in the text of an input file (as opposed to part
of an expression), it is textually replaced (or interpolated) with a
representation of that number. This output format can be changed to a
variety of formats (numbers, Roman numerals, etc.). This is done using
the af request.
@Deffn{Request, af, ident format} Change the output format of a number register. The first argument ident is the name of the number register to be changed, and the second argument format is the output format. The following output formats are available:
1
0...0
gtroff only counts
how many digits are specified. As a consequence, af's default
format `1' could be specified as `0' also (and exactly this is
returned by the \g escape, see below).
I
i
A
a
Omitting the number register format will cause a warning of type `missing'. See section Debugging, for more details. Specifying a nonexistent format causes an error.
The following example will produce `10, X, j, 010':
.nr a 10 .af a 1 \" the default format \na, .af a I \na, .af a a \na, .af a 001 \na
The largest number representable for the `i' and `I' formats
is 39999 (resp. -39999); @acronym{UNIX} troff uses `z' and
`w' to represent 10000 and 5000 in Roman numerals, and so does
gtroff. Currently, the correct glyphs of Roman numeral five
thousand and Roman numeral ten thousand (Unicode code points
U+2182 and U+2181, respectively) are not available.
If ident doesn't exist, it will be created.
Changing the output format of a read-only register causes an error. It
is necessary to first copy the register's value to a writeable register,
then apply the af request to this other register.
@end_Deffn
@Deffn{Escape, \\g, ident} Return the current format of the specified register ident. For example, `\ga' after the previous example would produce the string `000'. If the register hasn't been defined yet, nothing is returned. @end_Deffn
The following lists some built-in registers which are not described elsewhere in this manual. Any register which begins with a `.' is read-only. A complete listing of all built-in registers can be found in section Register Index.
.H
.V
dw
dy
mo
year
yr
troff had a year 2000 bug: It
incorrectly claimed that yr contains the last two digits of the
year. That claim has never been true of either traditional troff
or GNU troff. Old troff input that looks like this:
'\" The following line stopped working after 1999 This document was formatted in 19\n(yr.can be corrected as follows:
This document was formatted in \n[year].or, to be portable to older
troff versions, as follows:
.nr y4 1900+\n(yr This document was formatted in \n(y4.
.c
c.
gtroff extension) is writable also,
affecting both `.c' and `c.'.
ln
nm
request to activate line numbering.
.x
.x will contain `1'.
.y
.y will contain `03'.
.Y
groff.
.g
troff.
.A
.P
.T
gtroff is called with the @option{-T} command line option, the
number register .T is set to 1, and zero otherwise.
See section Options.
Additionally, gtroff predefines a single (read/write) string
register .T which contains the current output device (for
example, `latin1' or `ps').
Various ways of causing breaks were given in section Implicit Line Breaks. The br request will likewise cause a break. Several
other requests will also cause breaks, but implicitly. These are
bp, ce, cf, fi, fl, in,
nf, rj, sp, ti, and trf.
@Deffn{Request, br, } Break the current line, i.e., the input collected so far will be emitted without adjustment.
If the no-break control character is used, no break will happen:
a
'br
b
=> a b
@end_Deffn
Initially, gtroff will fill and adjust text to both margins.
Filling can be disabled via the nf request and re-enabled with
the fi request.
@Deffn{Request, fi, }
Activate fill mode (which is the default). This request implicitly
enables adjusting; it will also cause a break in the text currently
being filled. The number register .u is set to 1.
The fill mode status is associated with the current environment (see section Environments). @end_Deffn
@Deffn{Request, nf, }
Activate no-fill mode. Input lines are output as-is, retaining line
breaks. The current line length will be ignored. This command
implicitly disables adjusting; it also causes a break. The number
register .u will be set to 0.
The fill mode status is associated with the current environment (see section Environments). @end_Deffn
@Deffn{Request, ad, [mode]} Set adjusting mode.
Activation and deactivation of adjusting will be implicitly done with
calls to the fi resp. nf requests.
mode can have one of the following values:
l
r
c
ce request which
only centers text without filling.
b
n
gtroff.
With no argument, gtroff will adjust lines in the same way it did
before adjusting has been deactivated (with a call to na, for
example).
text .ad r text .ad c text .na text .ad \" back to centering text
The current adjustment mode is available in the number register
.j; it can be stored and subsequently used to set adjustment.
The adjustment mode status is associated with the current environment (see section Environments). @end_Deffn
@Deffn{Request, na, }
Disable adjusting. This request won't change the current adjustment
mode: A call to ad afterwards will use the previous adjustment
setting.
The adjustment mode status is associated with the current environment (see section Environments). @end_Deffn
@Deffn{Escape, \\p, } Adjust the current line and cause a break.
In most cases this will produce very ugly results, since gtroff
doesn't have a sophisticated paragraph building algorithm (as TeX
does, for example); instead, gtroff fills and adjusts a paragraph
line by line:
This is an uninteresting sentence. This is an uninteresting sentence.\p This is an uninteresting sentence.
is formatted as
This is an uninteresting sentence. This is an uninteresting sentence. This is an uninteresting sentence.
@end_Deffn
@Deffn{Request, ss, word_space_size [sentence_space_size]} Change the minimum size of a space between filled words. It takes its units as one twelfth of the space width parameter for the current font. Initially both the word_space_size and sentence_space_size are 12.
If two arguments are given to the ss request, the second argument
sets the sentence space size. If the second argument is not given,
sentence space size will be set to word_space_size. The sentence
space size is used in two circumstances: if the end of a sentence occurs
at the end of a line in fill mode, then both an inter-word space and a
sentence space will be added; if two spaces follow the end of a sentence
in the middle of a line, then the second space will be a sentence space.
Note that the behaviour of @acronym{UNIX} troff will be exactly
that exhibited by GNU troff if a second argument is never given
to the ss request. In GNU troff, as in @acronym{UNIX}
troff, a sentence should always be followed by either a newline
or two spaces.
The number registers .ss and .sss hold the values of the
parameters set by the first and second arguments of the ss
request.
The word space and sentence space values are associated with the current environment (see section Environments).
This request is ignored in nroff mode; it is also ignored if there is no parameter. @end_Deffn
@Deffn{Request, ce, [nnn]}
Center text. While the `.ad c' request will also center text,
it has the side effect of filling the text. ce will not fill the
text it affects. This request causes a break.
With no arguments, ce will center the next line of text.
nnn specifies the number of lines to be centered. If
the argument is zero or negative, centering is disabled.
The basic length for centering text is the line length (as set with the
ll request) minus the indentation (as set with the in
request). Temporary indentation is ignored.
A common idiom is to turn on centering for a large number of lines, and to turn off centering after text to be centered. This is useful for any request which takes a number of lines as an argument.
.ce 1000 replace this with something more interesting ... .ce 0
The .ce number register contains the number of lines remaining to
be centered, as set by the ce request.
@end_Deffn
@Deffn{Request, rj, [nnn]}
Justify unfilled text to the right margin. Arguments are identical to
the ce request. The .rj number register is the number of
lines to be right-justified as set by the rj request. This
request causes a line break.
@end_Deffn
As discussed in section Hyphenation, gtroff will hyphenate words.
There are a number of ways to influence hyphenation.
@Deffn{Request, hy, [mode]} Enable hyphenation. The request has an optional numeric argument, mode, to restrict hyphenation if necessary:
1
gtroff.
2
4
8
Values in the previous table are additive. For example, the value
12 causes gtroff to neither hyphenate the last two nor the first
two characters of a word.
The current hyphenation restrictions can be found in the number register `.hy'.
The hyphenation mode is associated with the current environment (see section Environments). @end_Deffn
@Deffn{Request, nh, }
Disable hyphenation (i.e., set the hyphenation mode to zero). Note that
the hyphenation mode of the last call to hy is not remembered.
The hyphenation mode is associated with the current environment (see section Environments). @end_Deffn
@Deffn{Request, hlm, [nnn]}
Set the maximum number of consecutive hyphenated lines to nnn. If
this number is negative, there is no maximum. The default value is
-1 if nnn is omitted. This value is associated with the current
environment (see section Environments). Only lines output from a given
environment count towards the maximum associated with that environment.
Hyphens resulting from \% are counted; explicit hyphens are not.
The current setting of hlm is available in the .hlm
register. Also the number of immediately preceding consecutive
hyphenated lines are available in the number register `.hlc'.
@end_Deffn
@Deffn{Request, hw, word1 word2 ...} Define how word1, word2, etc. are to be hyphenated. The words must be given with hyphens at the hyphenation points. For example:
.hw in-sa-lub-rious
Besides the space character, any character whose hyphenation code value
is zero can be used to separate the arguments of hw (see the
documentation for the hcode request below for more information).
In addition, this request can be used more than once.
Hyphenation exceptions specified with the hw request are
associated with the current hyphenation language; it will cause an error
if there is no current hyphenation language.
This request is ignored if there is no parameter.
In old versions of troff there was a limited amount of space to
store such information; fortunately, with gtroff, this is no
longer a restriction.
@end_Deffn
@Deffn{Escape, \\%, }
To tell gtroff how to hyphenate words on the fly, the \%
escape, also known as the hyphenation character, can be used.
Preceding a word with this character will prevent it from being
hyphenated, putting it in a word will indicate to gtroff that the
word may be hyphenated at that point. Note that this mechanism will
only affect that one occurrence of the word; to change the hyphenation
of a word for the entire document, use the hw request.
@end_Deffn
@Deffn{Request, hc, [char]}
Change the hyphenation character to char. This character will
then work the same as the \% escape, and thus, no longer appear
in the output. Without an argument, hc will reset the
hyphenation character to be \% (the default) only.
The hyphenation character is associated with the current environment (see section Environments). @end_Deffn
@Deffn{Request, hpf, pattern_file} Read in a file of hyphenation patterns. This file will be searched for in the same way as `tmac.name' is searched for if the @option{-mname} option is specified.
It should have the same format as the argument to the \patterns
primitive in TeX (without using TeX's macro expansion); the
letters appearing in this file are interpreted as hyphenation codes. A
`%' character in the patterns file introduces a comment that
continues