14442 lines
452 KiB
Plaintext
14442 lines
452 KiB
Plaintext
\input texinfo @c -*-texinfo-*-
|
||
|
||
@c
|
||
@c Please convert this manual with `texi2dvi -e groff.texinfo' due to a bug
|
||
@c in texinfo regarding expansion of user-defined macros.
|
||
@c
|
||
@c You need texinfo 4.2 or newer to format this document!
|
||
@c
|
||
|
||
@c %**start of header (This is for running Texinfo on a region.)
|
||
@setfilename groff
|
||
@settitle The GNU Troff Manual
|
||
@setchapternewpage odd
|
||
@footnotestyle separate
|
||
@c %**end of header (This is for running Texinfo on a region.)
|
||
|
||
|
||
@smallbook
|
||
|
||
@finalout
|
||
|
||
|
||
@copying
|
||
This manual documents GNU @code{troff} version 1.18.
|
||
|
||
Copyright @copyright{} 1994-2000, 2001, 2002 Free Software Foundation, Inc.
|
||
|
||
@quotation
|
||
Permission is granted to copy, distribute and/or modify this document
|
||
under the terms of the GNU Free Documentation License, Version 1.1 or
|
||
any later version published by the Free Software Foundation; with no
|
||
Invariant Sections, with the Front-Cover texts being `A GNU Manual,''
|
||
and with the Back-Cover Texts as in (a) below. A copy of the
|
||
license is included in the section entitled `GNU Free Documentation
|
||
License.''
|
||
|
||
(a) The FSF's Back-Cover Text is: `You have freedom to copy and modify
|
||
this GNU Manual, like GNU software. Copies published by the Free
|
||
Software Foundation raise funds for GNU development.''
|
||
@end quotation
|
||
@end copying
|
||
|
||
|
||
@c We use the following indices:
|
||
@c
|
||
@c cindex: concepts
|
||
@c rqindex: requests
|
||
@c esindex: escapes
|
||
@c vindex: registers
|
||
@c kindex: commands in font files
|
||
@c pindex: programs and files
|
||
@c tindex: environment variables
|
||
@c maindex: macros
|
||
@c stindex: strings
|
||
@c opindex: operators
|
||
@c
|
||
@c tindex and cindex are merged.
|
||
|
||
@defcodeindex rq
|
||
@defcodeindex es
|
||
@defcodeindex ma
|
||
@defcodeindex st
|
||
@defcodeindex op
|
||
@syncodeindex tp cp
|
||
|
||
|
||
@c to avoid uppercasing in @deffn while converting to info, we define
|
||
@c our special @Var{}
|
||
@c
|
||
@c due to a (not officially documented) `feature' in makeinfo 4.0,
|
||
@c macros are not expanded in @deffn (but the macro definition is
|
||
@c properly removed), so we have to define @Var{} directly in TeX also
|
||
|
||
@macro Var{arg}
|
||
\arg\
|
||
@end macro
|
||
@tex
|
||
\gdef\Var#1{\var{#1}}
|
||
@end tex
|
||
|
||
|
||
@c To assure correct HTML translation, some ugly hacks are necessary.
|
||
@c While processing a @def... request, the HTML translator looks at the
|
||
@c next line to decide whether it should start indentation or not. If
|
||
@c it is something starting with @def... (e.g. @deffnx), it doesn't.
|
||
@c So we must assure during macro expansion that a @def... is seen.
|
||
@c
|
||
@c The following macros have to be used:
|
||
@c
|
||
@c One item:
|
||
@c
|
||
@c @Def...
|
||
@c
|
||
@c Two items:
|
||
@c
|
||
@c @Def...List
|
||
@c @Def...ListEnd
|
||
@c
|
||
@c More than two:
|
||
@c
|
||
@c @Def...List
|
||
@c @Def...Item
|
||
@c @Def...Item
|
||
@c ...
|
||
@c @Def...ListEnd
|
||
@c
|
||
@c The definition block must end with
|
||
@c
|
||
@c @endDef...
|
||
@c
|
||
@c The above is valid for texinfo 4.0f.
|
||
|
||
|
||
@c a dummy macro to assure the `@def...'
|
||
|
||
@macro defdummy
|
||
@end macro
|
||
|
||
|
||
@c definition of requests
|
||
|
||
@macro Defreq{name, arg}
|
||
@deffn Request @t{.\name\} \arg\
|
||
@rqindex \name\
|
||
@end macro
|
||
|
||
@macro DefreqList{name, arg}
|
||
@deffn Request @t{.\name\} \arg\
|
||
@defdummy
|
||
@rqindex \name\
|
||
@end macro
|
||
|
||
@macro DefreqItem{name, arg}
|
||
@deffnx Request @t{.\name\} \arg\
|
||
@defdummy
|
||
@rqindex \name\
|
||
@end macro
|
||
|
||
@macro DefreqListEnd{name, arg}
|
||
@deffnx Request @t{.\name\} \arg\
|
||
@rqindex \name\
|
||
@end macro
|
||
|
||
@macro endDefreq
|
||
@end deffn
|
||
@end macro
|
||
|
||
|
||
@c definition of escapes
|
||
|
||
@macro Defesc{name, delimI, arg, delimII}
|
||
@deffn Escape @t{\name\\delimI\}@var{\arg\}@t{\delimII\}
|
||
@esindex \name\
|
||
@end macro
|
||
|
||
@macro DefescList{name, delimI, arg, delimII}
|
||
@deffn Escape @t{\name\\delimI\}@var{\arg\}@t{\delimII\}
|
||
@defdummy
|
||
@esindex \name\
|
||
@end macro
|
||
|
||
@macro DefescItem{name, delimI, arg, delimII}
|
||
@deffnx Escape @t{\name\\delimI\}@var{\arg\}@t{\delimII\}
|
||
@defdummy
|
||
@esindex \name\
|
||
@end macro
|
||
|
||
@macro DefescListEnd{name, delimI, arg, delimII}
|
||
@deffnx Escape @t{\name\\delimI\}@var{\arg\}@t{\delimII\}
|
||
@esindex \name\
|
||
@end macro
|
||
|
||
@macro endDefesc
|
||
@end deffn
|
||
@end macro
|
||
|
||
|
||
@c definition of registers
|
||
|
||
@macro Defreg{name}
|
||
@deffn Register @t{\\n[\name\]}
|
||
@vindex \name\
|
||
@end macro
|
||
|
||
@macro DefregList{name}
|
||
@deffn Register @t{\\n[\name\]}
|
||
@defdummy
|
||
@vindex \name\
|
||
@end macro
|
||
|
||
@macro DefregItem{name}
|
||
@deffnx Register @t{\\n[\name\]}
|
||
@defdummy
|
||
@vindex \name\
|
||
@end macro
|
||
|
||
@macro DefregListEnd{name}
|
||
@deffnx Register @t{\\n[\name\]}
|
||
@vindex \name\
|
||
@end macro
|
||
|
||
@macro endDefreg
|
||
@end deffn
|
||
@end macro
|
||
|
||
|
||
@c definition of registers specific to macro packages, preprocessors, etc.
|
||
|
||
@macro Defmpreg{name, package}
|
||
@deffn Register @t{\\n[\name\]}
|
||
@vindex \name\ @r{[}\package\@r{]}
|
||
@end macro
|
||
|
||
@macro DefmpregList{name, package}
|
||
@deffn Register @t{\\n[\name\]}
|
||
@defdummy
|
||
@vindex \name\ @r{[}\package\@r{]}
|
||
@end macro
|
||
|
||
@macro DefmpregItem{name, package}
|
||
@deffnx Register @t{\\n[\name\]}
|
||
@defdummy
|
||
@vindex \name\ @r{[}\package\@r{]}
|
||
@end macro
|
||
|
||
@macro DefmpregListEnd{name, package}
|
||
@deffnx Register @t{\\n[\name\]}
|
||
@vindex \name\ @r{[}\package\@r{]}
|
||
@end macro
|
||
|
||
@macro endDefmpreg
|
||
@end deffn
|
||
@end macro
|
||
|
||
|
||
@c definition of macros
|
||
|
||
@macro Defmac{name, arg, package}
|
||
@defmac @t{.\name\} \arg\
|
||
@maindex \name\ @r{[}\package\@r{]}
|
||
@end macro
|
||
|
||
@macro DefmacList{name, arg, package}
|
||
@defmac @t{.\name\} \arg\
|
||
@defdummy
|
||
@maindex \name\ @r{[}\package\@r{]}
|
||
@end macro
|
||
|
||
@macro DefmacItem{name, arg, package}
|
||
@defmacx @t{.\name\} \arg\
|
||
@defdummy
|
||
@maindex \name\ @r{[}\package\@r{]}
|
||
@end macro
|
||
|
||
@macro DefmacListEnd{name, arg, package}
|
||
@defmacx @t{.\name\} \arg\
|
||
@maindex \name\ @r{[}\package\@r{]}
|
||
@end macro
|
||
|
||
@macro endDefmac
|
||
@end defmac
|
||
@end macro
|
||
|
||
|
||
@c definition of strings
|
||
|
||
@macro Defstr{name, package}
|
||
@deffn String @t{\\*[\name\]}
|
||
@stindex \name\ @r{[}\package\@r{]}
|
||
@end macro
|
||
|
||
@macro DefstrList{name, package}
|
||
@deffn String @t{\\*[\name\]}
|
||
@defdummy
|
||
@stindex \name\ @r{[}\package\@r{]}
|
||
@end macro
|
||
|
||
@macro DefstrItem{name, package}
|
||
@deffnx String @t{\\*[\name\]}
|
||
@defdummy
|
||
@stindex \name\ @r{[}\package\@r{]}
|
||
@end macro
|
||
|
||
@macro DefstrListEnd{name, package}
|
||
@deffnx String @t{\\*[\name\]}
|
||
@stindex \name\ @r{[}\package\@r{]}
|
||
@end macro
|
||
|
||
@macro endDefstr
|
||
@end deffn
|
||
@end macro
|
||
|
||
|
||
@c our example macro
|
||
|
||
@macro Example
|
||
@example
|
||
@group
|
||
@end macro
|
||
|
||
@macro endExample
|
||
@end group
|
||
@end example
|
||
@end macro
|
||
|
||
|
||
@c <text>
|
||
|
||
@tex
|
||
\gdef\angles#1{\angleleft{}\r{#1}\angleright{}}
|
||
@end tex
|
||
|
||
@macro angles{text}
|
||
<\text\>
|
||
@end macro
|
||
|
||
|
||
@c a <= sign
|
||
|
||
@tex
|
||
\gdef\LE{\le}
|
||
@end tex
|
||
|
||
@macro LE
|
||
<=
|
||
@end macro
|
||
|
||
|
||
@c due to a bug in texinfo 4.2, the spacing of `<' is bad in @item
|
||
|
||
@tex
|
||
\gdef\LT{\string<}
|
||
@end tex
|
||
|
||
@macro LT
|
||
<
|
||
@end macro
|
||
|
||
|
||
@c We need special parentheses and brackets:
|
||
@c
|
||
@c . Real parentheses in @deffn produce an error while compiling with
|
||
@c TeX
|
||
@c . Real brackets use the wrong font in @deffn, overriding @t{}.
|
||
@c
|
||
@c Since macros aren't expanded in @deffn during -E, the following
|
||
@c definitions are for non-TeX only.
|
||
@c
|
||
@c This is true for texinfo 4.0.
|
||
|
||
@macro lparen
|
||
(
|
||
@end macro
|
||
@macro rparen
|
||
)
|
||
@end macro
|
||
@macro lbrack
|
||
[
|
||
@end macro
|
||
@macro rbrack
|
||
]
|
||
@end macro
|
||
|
||
|
||
@tex
|
||
\gdef\gobblefirst#1#2{#2}
|
||
\gdef\putwordAppendix{\gobblefirst}
|
||
@end tex
|
||
|
||
|
||
@c Note: We say `Roman numerals' but `roman font'.
|
||
|
||
|
||
@dircategory Miscellaneous
|
||
@direntry
|
||
* Groff: (groff). The GNU troff document formatting system.
|
||
@end direntry
|
||
|
||
|
||
@titlepage
|
||
@title groff
|
||
@subtitle The GNU implementation of @code{troff}
|
||
@subtitle Edition 1.18
|
||
@subtitle Spring 2002
|
||
@author by Trent A.@w{ }Fisher
|
||
@author and Werner Lemberg (@email{bug-groff@@gnu.org})
|
||
|
||
@page
|
||
@vskip 0pt plus 1filll
|
||
@insertcopying
|
||
@end titlepage
|
||
|
||
|
||
@contents
|
||
|
||
@ifinfo
|
||
@node Top, Introduction, (dir), (dir)
|
||
@top GNU troff
|
||
|
||
@insertcopying
|
||
@end ifinfo
|
||
|
||
@ifhtml
|
||
@node Top, Introduction, (dir), (dir)
|
||
@top GNU troff
|
||
|
||
@insertcopying
|
||
@end ifhtml
|
||
|
||
@menu
|
||
* Introduction::
|
||
* Invoking groff::
|
||
* Tutorial for Macro Users::
|
||
* Macro Packages::
|
||
* gtroff Reference::
|
||
* Preprocessors::
|
||
* Output Devices::
|
||
* File formats::
|
||
* Installation::
|
||
* Copying This Manual::
|
||
* Request Index::
|
||
* Escape Index::
|
||
* Operator Index::
|
||
* Register Index::
|
||
* Macro Index::
|
||
* String Index::
|
||
* Glyph Name Index::
|
||
* Font File Keyword Index::
|
||
* Program and File Index::
|
||
* Concept Index::
|
||
@end menu
|
||
|
||
|
||
|
||
@c =====================================================================
|
||
@c =====================================================================
|
||
|
||
@node Introduction, Invoking groff, Top, Top
|
||
@chapter Introduction
|
||
@cindex introduction
|
||
|
||
GNU @code{troff} (or @code{groff}) is a system for typesetting
|
||
documents. @code{troff} is very flexible and has been in existence (and
|
||
use) for about 3@w{ }decades. It is quite widespread and firmly
|
||
entrenched in the @acronym{UNIX} community.
|
||
|
||
@menu
|
||
* What Is groff?::
|
||
* History::
|
||
* groff Capabilities::
|
||
* Macro Package Intro::
|
||
* Preprocessor Intro::
|
||
* Output device intro::
|
||
* Credits::
|
||
@end menu
|
||
|
||
|
||
@c =====================================================================
|
||
|
||
@node What Is groff?, History, Introduction, Introduction
|
||
@section What Is @code{groff}?
|
||
@cindex what is @code{groff}?
|
||
@cindex @code{groff} -- what is it?
|
||
|
||
@code{groff} belongs to an older generation of document preparation
|
||
systems, which operate more like compilers than the more recent
|
||
interactive @acronym{WYSIWYG}@footnote{What You See Is What You Get}
|
||
systems. @code{groff} and its contemporary counterpart, @TeX{}, both
|
||
work using a @dfn{batch} paradigm: The input (or @dfn{source}) files are
|
||
normal text files with embedded formatting commands. These files can
|
||
then be processed by @code{groff} to produce a typeset document on a
|
||
variety of devices.
|
||
|
||
Likewise, @code{groff} should not be confused with a @dfn{word
|
||
processor}, since that term connotes an integrated system that includes
|
||
an editor and a text formatter. Also, many word processors follow the
|
||
@acronym{WYSIWYG} paradigm discussed earlier.
|
||
|
||
Although @acronym{WYSIWYG} systems may be easier to use, they have a
|
||
number of disadvantages compared to @code{troff}:
|
||
|
||
@itemize @bullet
|
||
@item
|
||
They must be used on a graphics display to work on a document.
|
||
|
||
@item
|
||
Most of the @acronym{WYSIWYG} systems are either non-free or are not
|
||
very portable.
|
||
|
||
@item
|
||
@code{troff} is firmly entrenched in all @acronym{UNIX} systems.
|
||
|
||
@item
|
||
It is difficult to have a wide range of capabilities available within
|
||
the confines of a GUI/window system.
|
||
|
||
@item
|
||
It is more difficult to make global changes to a document.
|
||
@end itemize
|
||
|
||
@quotation
|
||
``GUIs normally make it simple to accomplish simple actions and
|
||
impossible to accomplish complex actions.'' --Doug Gwyn (22/Jun/91 in
|
||
@code{comp.unix.wizards})
|
||
@end quotation
|
||
|
||
|
||
@c =====================================================================
|
||
|
||
@node History, groff Capabilities, What Is groff?, Introduction
|
||
@section History
|
||
@cindex history
|
||
|
||
@cindex @code{runoff}, the program
|
||
@cindex @code{rf}, the program
|
||
@code{troff} can trace its origins back to a formatting program called
|
||
@code{runoff}, written by J.@w{ }E.@w{ }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 @code{roff} (an abbreviation
|
||
of @code{runoff}). It was rewritten as @code{rf} for the @w{PDP-7}
|
||
(before having @acronym{UNIX}), and at the same time (1969), Doug
|
||
McIllroy rewrote an extended and simplified version of @code{roff} in
|
||
the @acronym{BCPL} programming language.
|
||
|
||
@cindex @code{roff}, the program
|
||
The first version of @acronym{UNIX} was developed on a @w{PDP-7} which
|
||
was sitting around Bell Labs. In 1971 the developers wanted to get a
|
||
@w{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 @acronym{AT&T} patents
|
||
division. This first formatting program was a reimplementation of
|
||
McIllroy's @code{roff}, written by J.@w{ }F.@w{ }Ossanna.
|
||
|
||
@cindex @code{nroff}, the program
|
||
When they needed a more flexible language, a new version of @code{roff}
|
||
called @code{nroff} (``Newer @code{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 @code{nroff} that would drive it. It was dubbed
|
||
@code{troff}, for ``typesetter @code{roff}'', although many people have
|
||
speculated that it actually means ``Times @code{roff}'' because of the
|
||
use of the Times font family in @code{troff} by default. As such, the
|
||
name @code{troff} is pronounced `@w{t-roff}' rather than `trough'.
|
||
|
||
With @code{troff} came @code{nroff} (they were actually the same program
|
||
except for some @samp{#ifdef}s), which was for producing output for line
|
||
printers and character terminals. It understood everything @code{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
|
||
@code{troff}, work on several preprocessors began. These programs would
|
||
transform certain parts of a document into @code{troff}, which made a
|
||
very natural use of pipes in @acronym{UNIX}.
|
||
|
||
The @code{eqn} preprocessor allowed mathematical formul@ae{} to be
|
||
specified in a much simpler and more intuitive manner. @code{tbl} is a
|
||
preprocessor for formatting tables. The @code{refer} preprocessor (and
|
||
the similar program, @code{bib}) processes citations in a document
|
||
according to a bibliographic database.
|
||
|
||
Unfortunately, Ossanna's @code{troff} was written in @w{PDP-11} assembly
|
||
language and produced output specifically for the CAT phototypesetter.
|
||
He rewrote it in C, although it was now 7000@w{ }lines of uncommented
|
||
code and still dependent on the CAT. As the CAT became less common, and
|
||
was no longer supported by the manufacturer, the need to make it support
|
||
other devices became a priority. However, before this could be done,
|
||
Ossanna was killed in a car accident.
|
||
|
||
@pindex ditroff
|
||
@cindex @code{ditroff}, the program
|
||
So, Brian Kernighan took on the task of rewriting @code{troff}. The
|
||
newly rewritten version produced device independent code which was
|
||
very easy for postprocessors to read and translate to the appropriate
|
||
printer codes. Also, this new version of @code{troff} (called
|
||
@code{ditroff} for ``device independent @code{troff}'') had several
|
||
extensions, which included drawing functions.
|
||
|
||
Due to the additional abilities of the new version of @code{troff},
|
||
several new preprocessors appeared. The @code{pic} preprocessor
|
||
provides a wide range of drawing functions. Likewise the @code{ideal}
|
||
preprocessor did the same, although via a much different paradigm. The
|
||
@code{grap} preprocessor took specifications for graphs, but, unlike
|
||
other preprocessors, produced @code{pic} code.
|
||
|
||
James Clark began work on a GNU implementation of @code{ditroff} in
|
||
early@w{ }1989. The first version, @code{groff}@w{ }0.3.1, was released
|
||
June@w{ }1990. @code{groff} included:
|
||
|
||
@itemize @bullet
|
||
@item
|
||
A replacement for @code{ditroff} with many extensions.
|
||
|
||
@item
|
||
The @code{soelim}, @code{pic}, @code{tbl}, and @code{eqn} preprocessors.
|
||
|
||
@item
|
||
Postprocessors for character devices, @sc{PostScript}, @TeX{} DVI, and
|
||
X@w{ }Windows. GNU @code{troff} also eliminated the need for a
|
||
separate @code{nroff} program with a postprocessor which would produce
|
||
@acronym{ASCII} output.
|
||
|
||
@item
|
||
A version of the @file{me} macros and an implementation of the
|
||
@file{man} macros.
|
||
@end itemize
|
||
|
||
Also, a front-end was included which could construct the, sometimes
|
||
painfully long, pipelines required for all the post- and preprocessors.
|
||
|
||
Development of GNU @code{troff} progressed rapidly, and saw the
|
||
additions of a replacement for @code{refer}, an implementation of the
|
||
@file{ms} and @file{mm} macros, and a program to deduce how to format a
|
||
document (@code{grog}).
|
||
|
||
It was declared a stable (i.e.@: non-beta) package with the release of
|
||
version@w{ }1.04 around November@w{ }1991.
|
||
|
||
Beginning in@w{ }1999, @code{groff} has new maintainers (the package was
|
||
an orphan for a few years). As a result, new features and programs like
|
||
@code{grn}, a preprocessor for gremlin images, and an output device to
|
||
produce @acronym{HTML} output have been added.
|
||
|
||
|
||
@c =====================================================================
|
||
|
||
@node groff Capabilities, Macro Package Intro, History, Introduction
|
||
@section @code{groff} Capabilities
|
||
@cindex @code{groff} capabilities
|
||
@cindex capabilities of @code{groff}
|
||
|
||
So what exactly is @code{groff} capable of doing? @code{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 @code{groff}:
|
||
|
||
@itemize @bullet
|
||
@item
|
||
text filling, adjusting, and centering
|
||
|
||
@item
|
||
hyphenation
|
||
|
||
@item
|
||
page control
|
||
|
||
@item
|
||
font and glyph size control
|
||
|
||
@item
|
||
vertical spacing (e.g.@: double-spacing)
|
||
|
||
@item
|
||
line length and indenting
|
||
|
||
@item
|
||
macros, strings, diversions, and traps
|
||
|
||
@item
|
||
number registers
|
||
|
||
@item
|
||
tabs, leaders, and fields
|
||
|
||
@item
|
||
input and output conventions and character translation
|
||
|
||
@item
|
||
overstrike, bracket, line drawing, and zero-width functions
|
||
|
||
@item
|
||
local horizontal and vertical motions and the width function
|
||
|
||
@item
|
||
three-part titles
|
||
|
||
@item
|
||
output line numbering
|
||
|
||
@item
|
||
conditional acceptance of input
|
||
|
||
@item
|
||
environment switching
|
||
|
||
@item
|
||
insertions from the standard input
|
||
|
||
@item
|
||
input/output file switching
|
||
|
||
@item
|
||
output and error messages
|
||
@end itemize
|
||
|
||
|
||
@c =====================================================================
|
||
|
||
@node Macro Package Intro, Preprocessor Intro, groff Capabilities, Introduction
|
||
@section Macro Packages
|
||
@cindex macro packages
|
||
|
||
Since @code{groff} provides such low-level facilities, it can be quite
|
||
difficult to use by itself. However, @code{groff} provides a
|
||
@dfn{macro} facility to specify how certain routine operations (e.g.@w{
|
||
}starting paragraphs, printing headers and footers, etc.)@: should be
|
||
done. These macros can be collected together into a @dfn{macro
|
||
package}. There are a number of macro packages available; the most
|
||
common (and the ones described in this manual) are @file{man},
|
||
@file{mdoc}, @file{me}, @file{ms}, and @file{mm}.
|
||
|
||
|
||
@c =====================================================================
|
||
|
||
@node Preprocessor Intro, Output device intro, Macro Package Intro, Introduction
|
||
@section Preprocessors
|
||
@cindex preprocessors
|
||
|
||
Although @code{groff} provides most functions needed to format a
|
||
document, some operations would be unwieldy (e.g.@: to draw pictures).
|
||
Therefore, programs called @dfn{preprocessors} were written which
|
||
understand their own language and produce the necessary @code{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 @code{groff}. Any number of preprocessors
|
||
may be used on a given document; in this case, the preprocessors are
|
||
linked together into one pipeline. However, with @code{groff}, the user
|
||
does not need to construct the pipe, but only tell @code{groff} what
|
||
preprocessors to use.
|
||
|
||
@code{groff} currently has preprocessors for producing tables
|
||
(@code{tbl}), typesetting equations (@code{eqn}), drawing pictures
|
||
(@code{pic} and @code{grn}), and for processing bibliographies
|
||
(@code{refer}). An associated program which is useful when dealing with
|
||
preprocessors is @code{soelim}.
|
||
|
||
A free implementation of @code{grap}, a preprocessor for drawing graphs,
|
||
can be obtained as an extra package; @code{groff} can use @code{grap}
|
||
also.
|
||
|
||
There are other preprocessors in existence, but, unfortunately, no free
|
||
implementations are available. Among them are preprocessors for drawing
|
||
mathematical pictures (@code{ideal}) and chemical structures
|
||
(@code{chem}).
|
||
|
||
|
||
@c =====================================================================
|
||
|
||
@node Output device intro, Credits, Preprocessor Intro, Introduction
|
||
@section Output Devices
|
||
@cindex postprocessors
|
||
@cindex output devices
|
||
@cindex devices for output
|
||
|
||
@code{groff} actually produces device independent code which may be
|
||
fed into a postprocessor to produce output for a particular device.
|
||
Currently, @code{groff} has postprocessors for @sc{PostScript}
|
||
devices, character terminals, X@w{ }Windows (for previewing), @TeX{}
|
||
DVI format, HP LaserJet@w{ }4 and Canon LBP printers (which use
|
||
@acronym{CAPSL}), and @acronym{HTML}.
|
||
|
||
|
||
@c =====================================================================
|
||
|
||
@node Credits, , Output device intro, Introduction
|
||
@section Credits
|
||
@cindex credits
|
||
|
||
Large portions of this manual were taken from existing documents, most
|
||
notably, the manual pages for the @code{groff} package by James Clark,
|
||
and Eric Allman's papers on the @file{me} macro package.
|
||
|
||
The section on the @file{man} macro package is partly based on Susan@w{
|
||
}G.@: Kleinmann's @file{groff_man} manual page written for the Debian
|
||
GNU/Linux system.
|
||
|
||
Larry Kollar contributed the section in the @file{ms} macro package.
|
||
|
||
|
||
|
||
@c =====================================================================
|
||
@c =====================================================================
|
||
|
||
@node Invoking groff, Tutorial for Macro Users, Introduction, Top
|
||
@chapter Invoking @code{groff}
|
||
@cindex invoking @code{groff}
|
||
@cindex @code{groff} invocation
|
||
|
||
This section focuses on how to invoke the @code{groff} front end. This
|
||
front end takes care of the details of constructing the pipeline among
|
||
the preprocessors, @code{gtroff} and the postprocessor.
|
||
|
||
It has become a tradition that GNU programs get the prefix @samp{g} to
|
||
distinguish it from its original counterparts provided by the host (see
|
||
@ref{Environment}, for more details). Thus, for example, @code{geqn} is
|
||
GNU @code{eqn}. On operating systems like GNU/Linux or the Hurd, which
|
||
don't contain proprietary versions of @code{troff}, and on
|
||
MS-DOS/MS-Windows, where @code{troff} and associated programs are not
|
||
available at all, this prefix is omitted since GNU @code{troff} is the
|
||
only used incarnation of @code{troff}. Exception: @samp{groff} is never
|
||
replaced by @samp{roff}.
|
||
|
||
In this document, we consequently say @samp{gtroff} when talking about
|
||
the GNU @code{troff} program. All other implementations of @code{troff}
|
||
are called @acronym{AT&T} @code{troff} which is the common origin of
|
||
all @code{troff} derivates (with more or less compatible changes).
|
||
Similarly, we say @samp{gpic}, @samp{geqn}, etc.
|
||
|
||
@menu
|
||
* Groff Options::
|
||
* Environment::
|
||
* Macro Directories::
|
||
* Font Directories::
|
||
* Invocation Examples::
|
||
@end menu
|
||
|
||
|
||
@c =====================================================================
|
||
|
||
@node Groff Options, Environment, Invoking groff, Invoking groff
|
||
@section Options
|
||
@cindex options
|
||
|
||
@pindex groff
|
||
@pindex gtroff
|
||
@pindex gpic
|
||
@pindex geqn
|
||
@pindex ggrn
|
||
@pindex grap
|
||
@pindex gtbl
|
||
@pindex grefer
|
||
@pindex gsoelim
|
||
@code{groff} normally runs the @code{gtroff} program and a postprocessor
|
||
appropriate for the selected device. The default device is @samp{ps}
|
||
(but it can be changed when @code{groff} is configured and built). It
|
||
can optionally preprocess with any of @code{gpic}, @code{geqn},
|
||
@code{gtbl}, @code{ggrn}, @code{grap}, @code{grefer}, or @code{gsoelim}.
|
||
|
||
This section only documents options to the @code{groff} front end. Many
|
||
of the arguments to @code{groff} are passed on to @code{gtroff},
|
||
therefore those are also included. Arguments to pre- or postprocessors
|
||
can be found in @ref{Invoking gpic}, @ref{Invoking geqn}, @ref{Invoking
|
||
gtbl}, @ref{Invoking ggrn}, @ref{Invoking grefer}, @ref{Invoking
|
||
gsoelim}, @ref{Invoking grotty}, @ref{Invoking grops}, @ref{Invoking
|
||
grohtml}, @ref{Invoking grodvi}, @ref{Invoking grolj4}, @ref{Invoking
|
||
grolbp}, and @ref{Invoking gxditview}.
|
||
|
||
The command line format for @code{groff} is:
|
||
|
||
@Example
|
||
groff [ -abceghilpstvzCEGNRSUVXZ ] [ -F@var{dir} ] [ -m@var{name} ]
|
||
[ -T@var{def} ] [ -f@var{fam} ] [ -w@var{name} ] [ -W@var{name} ]
|
||
[ -M@var{dir} ] [ -d@var{cs} ] [ -r@var{cn} ] [ -n@var{num} ]
|
||
[ -o@var{list} ] [ -P@var{arg} ] [ -L@var{arg} ] [ -I@var{dir} ]
|
||
[ @var{files}@dots{} ]
|
||
@endExample
|
||
|
||
The command line format for @code{gtroff} is as follows.
|
||
|
||
@Example
|
||
gtroff [ -abcivzCERU ] [ -w@var{name} ] [ -W@var{name} ] [ -d@var{cs} ]
|
||
[ -f@var{fam} ] [ -m@var{name} ] [ -n@var{num} ]
|
||
[ -o@var{list} ] [ -r@var{cn} ] [ -T@var{name} ]
|
||
[ -F@var{dir} ] [ -M@var{dir} ] [ @var{files}@dots{} ]
|
||
@endExample
|
||
|
||
@noindent
|
||
Obviously, many of the options to @code{groff} are actually passed on to
|
||
@code{gtroff}.
|
||
|
||
Options without an argument can be grouped behind a single@w{ }@option{-}.
|
||
A filename of@w{ }@file{-} denotes the standard input. It is possible to
|
||
have whitespace between an option and its parameter.
|
||
|
||
The @code{grog} command can be used to guess the correct @code{groff}
|
||
command to format a file.
|
||
|
||
Here's the description of the command-line options:
|
||
|
||
@cindex command-line options
|
||
@table @samp
|
||
@item -h
|
||
Print a help message.
|
||
|
||
@item -e
|
||
Preprocess with @code{geqn}.
|
||
|
||
@item -t
|
||
Preprocess with @code{gtbl}.
|
||
|
||
@item -g
|
||
Preprocess with @code{ggrn}.
|
||
|
||
@item -G
|
||
Preprocess with @code{grap}.
|
||
|
||
@item -p
|
||
Preprocess with @code{gpic}.
|
||
|
||
@item -s
|
||
Preprocess with @code{gsoelim}.
|
||
|
||
@item -c
|
||
Suppress color output.
|
||
|
||
@item -R
|
||
Preprocess with @code{grefer}. No mechanism is provided for passing
|
||
arguments to @code{grefer} because most @code{grefer} options have
|
||
equivalent commands which can be included in the file. @xref{grefer},
|
||
for more details.
|
||
|
||
@pindex troffrc
|
||
@pindex troffrc-end
|
||
Note that @code{gtroff} also accepts a @option{-R} option, which is not
|
||
accessible via @code{groff}. This option prevents the loading of the
|
||
@file{troffrc} and @file{troffrc-end} files.
|
||
|
||
@item -v
|
||
Make programs run by @code{groff} print out their version number.
|
||
|
||
@item -V
|
||
Print the pipeline on @code{stdout} instead of executing it.
|
||
|
||
@item -z
|
||
Suppress output from @code{gtroff}. Only error messages are printed.
|
||
|
||
@item -Z
|
||
Do not postprocess the output of @code{gtroff}. Normally @code{groff}
|
||
automatically runs the appropriate postprocessor.
|
||
|
||
@item -P@var{arg}
|
||
Pass @var{arg} to the postprocessor. Each argument should be passed
|
||
with a separate @option{-P} option. Note that @code{groff} does not
|
||
prepend @samp{-} to @var{arg} before passing it to the postprocessor.
|
||
|
||
@item -l
|
||
Send the output to a spooler for printing. The command used for this is
|
||
specified by the @code{print} command in the device description file
|
||
(see @ref{Font Files}, for more info). If not present, @option{-l} is
|
||
ignored.
|
||
|
||
@item -L@var{arg}
|
||
Pass @var{arg} to the spooler. Each argument should be passed with a
|
||
separate @option{-L} option. Note that @code{groff} does not prepend
|
||
a @samp{-} to @var{arg} before passing it to the postprocessor.
|
||
If the @code{print} keyword in the device description file is missing,
|
||
@option{-L} is ignored.
|
||
|
||
@item -T@var{dev}
|
||
Prepare output for device @var{dev}. The default device is @samp{ps},
|
||
unless changed when @code{groff} was configured and built. The
|
||
following are the output devices currently available:
|
||
|
||
@table @code
|
||
@item ps
|
||
For @sc{PostScript} printers and previewers.
|
||
|
||
@item dvi
|
||
For @TeX{} DVI format.
|
||
|
||
@item X75
|
||
For a 75@dmn{dpi} X11 previewer.
|
||
|
||
@item X75-12
|
||
For a 75@dmn{dpi} X11 previewer with a 12@dmn{pt} base font in the
|
||
document.
|
||
|
||
@item X100
|
||
For a 100@dmn{dpi} X11 previewer.
|
||
|
||
@item X100-12
|
||
For a 100@dmn{dpi} X11 previewer with a 12@dmn{pt} base font in the
|
||
document.
|
||
|
||
@item ascii
|
||
@cindex encoding, @acronym{ASCII}
|
||
@cindex @acronym{ASCII}, encoding
|
||
For typewriter-like devices using the (7-bit) @acronym{ASCII}
|
||
character set.
|
||
|
||
@item latin1
|
||
@cindex encoding, latin-1
|
||
@cindex latin-1, encoding
|
||
For typewriter-like devices that support the @w{Latin-1} (@w{ISO
|
||
8859-1}) character set.
|
||
|
||
@item utf8
|
||
@cindex encoding, utf-8
|
||
@cindex utf-8, encoding
|
||
For typewriter-like devices which use the Unicode (@w{ISO 10646})
|
||
character set with @w{UTF-8} encoding.
|
||
|
||
@item cp1047
|
||
@cindex @acronym{EBCDIC} encoding
|
||
@cindex encoding, @acronym{EBCDIC}
|
||
@cindex encoding, cp1047
|
||
@cindex cp1047
|
||
@cindex IBM cp1047
|
||
For typewriter-like devices which use the @acronym{EBCDIC} encoding IBM
|
||
cp1047.
|
||
|
||
@item lj4
|
||
For HP LaserJet4-compatible (or other PCL5-compatible) printers.
|
||
|
||
@item lbp
|
||
For Canon @acronym{CAPSL} printers (@w{LBP-4} and @w{LBP-8} series laser
|
||
printers).
|
||
|
||
@pindex pre-grohtml
|
||
@pindex post-grohtml
|
||
@cindex @code{grohtml}, the program
|
||
@item html
|
||
To produce @acronym{HTML} output. Note that the @acronym{HTML} driver
|
||
consists of two parts, a preprocessor (@code{pre-grohtml}) and a
|
||
postprocessor (@code{post-grohtml}).
|
||
@end table
|
||
|
||
@cindex output device name string register (@code{.T})
|
||
@cindex output device usage number register (@code{.T})
|
||
The predefined @code{gtroff} string register @code{.T} contains the
|
||
current output device; the read-only number register @code{.T} is set
|
||
to@w{ }1 if this option is used (which is always true if @code{groff} is
|
||
used to call @code{gtroff}). @xref{Built-in Registers}.
|
||
|
||
The postprocessor to be used for a device is specified by the
|
||
@code{postpro} command in the device description file. (@xref{Font
|
||
Files}, for more info.) This can be overridden with the @option{-X}
|
||
option.
|
||
|
||
@item -X
|
||
Preview with @code{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 @code{gxditview}: The former
|
||
uses the metrics of the specified device, whereas the latter uses
|
||
X-specific fonts and metrics.
|
||
|
||
@item -N
|
||
Don't allow newlines with @code{eqn} delimiters. This is the same as
|
||
the @option{-N} option in @code{geqn}.
|
||
|
||
@item -S
|
||
@cindex @code{open} request, and safer mode
|
||
@cindex @code{opena} request, and safer mode
|
||
@cindex @code{pso} request, and safer mode
|
||
@cindex @code{sy} request, and safer mode
|
||
@cindex @code{pi} request, and safer mode
|
||
@cindex safer mode
|
||
@cindex mode, safer
|
||
Safer mode. Pass the @option{-S} option to @code{gpic} and disable the
|
||
@code{open}, @code{opena}, @code{pso}, @code{sy}, and @code{pi}
|
||
requests. For security reasons, this is enabled by default.
|
||
|
||
@item -U
|
||
@cindex mode, unsafe
|
||
@cindex unsafe mode
|
||
Unsafe mode. This enables the @code{open}, @code{opena}, @code{pso},
|
||
@code{sy}, and @code{pi} requests.
|
||
|
||
@item -a
|
||
@cindex @acronym{ASCII} approximation output register (@code{.A})
|
||
Generate an @acronym{ASCII} approximation of the typeset output. The
|
||
read-only register @code{.A} is then set to@w{ }1. @xref{Built-in
|
||
Registers}. A typical example is
|
||
|
||
@Example
|
||
groff -a -man -Tdvi troff.man | less
|
||
@endExample
|
||
|
||
@noindent
|
||
which shows how lines are broken for the DVI device. Note that this
|
||
option is rather useless today since graphic output devices are
|
||
available virtually everywhere.
|
||
|
||
@item -b
|
||
Print a backtrace with each warning or error message. This backtrace
|
||
should help track down the cause of the error. The line numbers given
|
||
in the backtrace may not always be correct: @code{gtroff} can get
|
||
confused by @code{as} or @code{am} requests while counting line numbers.
|
||
|
||
@item -i
|
||
Read the standard input after all the named input files have been
|
||
processed.
|
||
|
||
@item -w@var{name}
|
||
Enable warning @var{name}. Available warnings are described in
|
||
@ref{Debugging}. Multiple @option{-w} options are allowed.
|
||
|
||
@item -W@var{name}
|
||
Inhibit warning @var{name}. Multiple @option{-W} options are allowed.
|
||
|
||
@item -E
|
||
Inhibit all error messages.
|
||
|
||
@item -C
|
||
Enable compatibility mode. @xref{Implementation Differences}, for the
|
||
list of incompatibilities between @code{groff} and @acronym{AT&T}
|
||
@code{troff}.
|
||
|
||
@item -d@var{c}@var{s}
|
||
@itemx -d@var{name}=@var{s}
|
||
Define @var{c} or @var{name} to be a string@w{ }@var{s}. @var{c}@w{ }must
|
||
be a one-letter name; @var{name} can be of arbitrary length. All string
|
||
assignments happen before loading any macro file (including the start-up
|
||
file).
|
||
|
||
@item -f@var{fam}
|
||
Use @var{fam} as the default font family. @xref{Font Families}.
|
||
|
||
@item -m@var{name}
|
||
Read in the file @file{@var{name}.tmac}. Normally @code{groff} searches
|
||
for this in its macro directories. If it isn't found, it tries
|
||
@file{tmac.@var{name}} (searching in the same directories).
|
||
|
||
@item -n@var{num}
|
||
Number the first page @var{num}.
|
||
|
||
@item -o@var{list}
|
||
@cindex print current page register (@code{.P})
|
||
Output only pages in @var{list}, which is a comma-separated list of page
|
||
ranges; @samp{@var{n}} means print page@w{ }@var{n}, @samp{@var{m}-@var{n}}
|
||
means print every page between @var{m} and@w{ }@var{n}, @samp{-@var{n}}
|
||
means print every page up to@w{ }@var{n}, @samp{@var{n}-} means print every
|
||
page beginning with@w{ }@var{n}. @code{gtroff} exits after printing the
|
||
last page in the list. All the ranges are inclusive on both ends.
|
||
|
||
Within @code{gtroff}, this information can be extracted with the
|
||
@samp{.P} register. @xref{Built-in Registers}.
|
||
|
||
If your document restarts page numbering at the beginning of each
|
||
chapter, then @code{gtroff} prints the specified page range for each
|
||
chapter.
|
||
|
||
@item -r@var{c}@var{n}
|
||
@itemx -r@var{name}=@var{n}
|
||
Set number register@w{ }@var{c} or @var{name} to the value@w{ }@var{n}.
|
||
@var{c}@w{ }must be a one-letter name; @var{name} can be of arbitrary
|
||
length. @var{n}@w{ }can be any @code{gtroff} numeric expression. All
|
||
register assignments happen before loading any macro file (including
|
||
the start-up file).
|
||
|
||
@item -F@var{dir}
|
||
Search @file{@var{dir}} for subdirectories @file{dev@var{name}}
|
||
(@var{name} is the name of the device), for the @file{DESC} file, and
|
||
for font files before looking in the standard directories (@pxref{Font
|
||
Directories}). This option is passed to all pre- and postprocessors
|
||
using the @env{GROFF_FONT_PATH} environment variable.
|
||
|
||
@item -M@var{dir}
|
||
Search directory @file{@var{dir}} for macro files before the standard
|
||
directories (@pxref{Macro Directories}).
|
||
|
||
@item -I@var{dir}
|
||
This option is as described in @ref{gsoelim}. It implies the
|
||
@option{-s} option.
|
||
@end table
|
||
|
||
|
||
@c =====================================================================
|
||
|
||
@node Environment, Macro Directories, Groff Options, Invoking groff
|
||
@section Environment
|
||
@cindex environment variables
|
||
@cindex variables in environment
|
||
|
||
There are also several environment variables (of the operating system,
|
||
not within @code{gtroff}) which can modify the behavior of @code{groff}.
|
||
|
||
@table @code
|
||
@item GROFF_COMMAND_PREFIX
|
||
@tindex GROFF_COMMAND_PREFIX@r{, environment variable}
|
||
@cindex command prefix
|
||
@cindex prefix, for commands
|
||
If this is set to@w{ }@var{X}, then @code{groff} runs @code{@var{X}troff}
|
||
instead of @code{gtroff}. This also applies to @code{tbl}, @code{pic},
|
||
@code{eqn}, @code{grn}, @code{refer}, and @code{soelim}. It does not
|
||
apply to @code{grops}, @code{grodvi}, @code{grotty}, @code{pre-grohtml},
|
||
@code{post-grohtml}, @code{grolj4}, and @code{gxditview}.
|
||
|
||
The default command prefix is determined during the installation process.
|
||
If a non-GNU troff system is found, prefix @samp{g} is used, none
|
||
otherwise.
|
||
|
||
@item GROFF_TMAC_PATH
|
||
@tindex GROFF_TMAC_PATH@r{, environment variable}
|
||
A colon-separated list of directories in which to search for macro files
|
||
(before the default directories are tried). @xref{Macro Directories}.
|
||
|
||
@item GROFF_TYPESETTER
|
||
@tindex GROFF_TYPESETTER@r{, environment variable}
|
||
The default output device.
|
||
|
||
@item GROFF_FONT_PATH
|
||
@tindex GROFF_FONT_PATH@r{, environment variable}
|
||
A colon-separated list of directories in which to search for the
|
||
@code{dev}@var{name} directory (before the default directories are
|
||
tried). @xref{Font Directories}.
|
||
|
||
@item GROFF_BIN_PATH
|
||
@tindex GROFF_BIN_PATH@r{, environment variable}
|
||
This search path, followed by @code{PATH}, is used for commands executed
|
||
by @code{groff}.
|
||
|
||
@item GROFF_TMPDIR
|
||
@tindex GROFF_TMPDIR@r{, environment variable}
|
||
@tindex TMPDIR@r{, environment variable}
|
||
The directory in which @code{groff} creates temporary files. If this is
|
||
not set and @env{TMPDIR} is set, temporary files are created in that
|
||
directory. Otherwise temporary files are created in a system-dependent
|
||
default directory (on Unix and GNU/Linux systems, this is usually
|
||
@file{/tmp}). @code{grops}, @code{grefer}, @code{pre-grohtml}, and
|
||
@code{post-grohtml} can create temporary files in this directory.
|
||
@end table
|
||
|
||
Note that MS-DOS and MS-Windows ports of @code{groff} use semi-colons,
|
||
rather than colons, to separate the directories in the lists described
|
||
above.
|
||
|
||
|
||
@c =====================================================================
|
||
|
||
@node Macro Directories, Font Directories, Environment, Invoking groff
|
||
@section Macro Directories
|
||
@cindex macro directories
|
||
@cindex directories for macros
|
||
@cindex searching macros
|
||
@cindex macros, searching
|
||
|
||
All macro file names must be named @code{@var{name}.tmac} or
|
||
@code{tmac.@var{name}} to make the @option{-m@var{name}} command line
|
||
option work. The @code{mso} request doesn't have this restriction; any
|
||
file name can be used, and @code{gtroff} won't try to append or prepend
|
||
the @samp{tmac} string.
|
||
|
||
@cindex tmac, directory
|
||
@cindex directory, for tmac files
|
||
@cindex tmac, path
|
||
@cindex path, for tmac files
|
||
@cindex searching macro files
|
||
@cindex macro files, searching
|
||
@cindex files, macro, searching
|
||
Macro files are kept in the @dfn{tmac directories}, all of which
|
||
constitute the @dfn{tmac path}. The elements of the search path for
|
||
macro files are (in that order):
|
||
|
||
@itemize @bullet
|
||
@item
|
||
The directories specified with @code{gtroff}'s or @code{groff}'s
|
||
@option{-M} command line option.
|
||
|
||
@item
|
||
@tindex GROFF_TMAC_PATH@r{, environment variable}
|
||
The directories given in the @env{GROFF_TMAC_PATH} environment
|
||
variable.
|
||
|
||
@item
|
||
@cindex safer mode
|
||
@cindex mode, safer
|
||
@cindex unsafe mode
|
||
@cindex mode, unsafe
|
||
@cindex current directory
|
||
@cindex directory, current
|
||
The current directory (only if in unsafe mode using the @option{-U}
|
||
command line switch).
|
||
|
||
@item
|
||
@cindex home directory
|
||
@cindex directory, home
|
||
The home directory.
|
||
|
||
@item
|
||
@cindex site-specific directory
|
||
@cindex directory, site-specific
|
||
@cindex platform-specific directory
|
||
@cindex directory, platform-specific
|
||
A platform-dependent directory, a site-specific (platform-independent)
|
||
directory, and the main tmac directory; the default locations are
|
||
|
||
@Example
|
||
/usr/local/lib/groff/site-tmac
|
||
/usr/local/share/groff/site-tmac
|
||
/usr/local/share/groff/1.18/tmac
|
||
@endExample
|
||
|
||
@noindent
|
||
assuming that the version of @code{groff} is 1.18, and the installation
|
||
prefix was @file{/usr/local}. It is possible to fine-tune those
|
||
directories during the installation process.
|
||
@end itemize
|
||
|
||
|
||
@c =====================================================================
|
||
|
||
@node Font Directories, Invocation Examples, Macro Directories, Invoking groff
|
||
@section Font Directories
|
||
@cindex font directories
|
||
@cindex directories for fonts
|
||
@cindex searching fonts
|
||
@cindex fonts, searching
|
||
|
||
Basically, there is no restriction how font files for @code{groff} are
|
||
named and how long font names are; however, to make the font family
|
||
mechanism work (@pxref{Font Families}), fonts within a family should
|
||
start with the family name, followed by the shape. For example, the
|
||
Times family uses @samp{T} for the family name and @samp{R}, @samp{B},
|
||
@samp{I}, and @samp{BI} to indicate the shapes `roman', `bold',
|
||
`italic', and `bold italic', respectively. Thus the final font names
|
||
are @samp{TR}, @samp{TB}, @samp{TI}, and @samp{TBI}.
|
||
|
||
@cindex font path
|
||
@cindex path, for font files
|
||
All font files are kept in the @dfn{font directories} which constitute
|
||
the @dfn{font path}. The file search functions will always append the
|
||
directory @code{dev}@var{name}, where @var{name} is the name of the
|
||
output device. Assuming, say, DVI output, and @file{/foo/bar} as a
|
||
font directory, the font files for @code{grodvi} must be in
|
||
@file{/foo/bar/devdvi}.
|
||
|
||
The elements of the search path for font files are (in that order):
|
||
|
||
@itemize @bullet
|
||
@item
|
||
The directories specified with @code{gtroff}'s or @code{groff}'s
|
||
@option{-F} command line option. All device drivers and some
|
||
preprocessors also have this option.
|
||
|
||
@item
|
||
@tindex GROFF_FONT_PATH@r{, environment variable}
|
||
The directories given in the @env{GROFF_FONT_PATH} environment
|
||
variable.
|
||
|
||
@item
|
||
@cindex site-specific directory
|
||
@cindex directory, site-specific
|
||
A site-specific directory and the main font directory; the default
|
||
locations are
|
||
|
||
@Example
|
||
/usr/local/share/groff/site-font
|
||
/usr/local/share/groff/1.18/font
|
||
@endExample
|
||
|
||
@noindent
|
||
assuming that the version of @code{groff} is 1.18, and the installation
|
||
prefix was @file{/usr/local}. It is possible to fine-tune those
|
||
directories during the installation process.
|
||
@end itemize
|
||
|
||
|
||
@c =====================================================================
|
||
|
||
@node Invocation Examples, , Font Directories, Invoking groff
|
||
@section Invocation Examples
|
||
@cindex invocation examples
|
||
@cindex examples of invocation
|
||
|
||
This section lists several common uses of @code{groff} and the
|
||
corresponding command lines.
|
||
|
||
@Example
|
||
groff file
|
||
@endExample
|
||
|
||
@noindent
|
||
This command processes @file{file} without a macro package or a
|
||
preprocessor. The output device is the default, @samp{ps}, and the
|
||
output is sent to @code{stdout}.
|
||
|
||
@Example
|
||
groff -t -mandoc -Tascii file | less
|
||
@endExample
|
||
|
||
@noindent
|
||
This is basically what a call to the @code{man} program does.
|
||
@code{gtroff} processes the manual page @file{file} with the
|
||
@file{mandoc} macro file (which in turn either calls the @file{man} or
|
||
the @file{mdoc} macro package), using the @code{tbl} preprocessor and
|
||
the @acronym{ASCII} output device. Finally, the @code{less} pager
|
||
displays the result.
|
||
|
||
@Example
|
||
groff -X -m me file
|
||
@endExample
|
||
|
||
@noindent
|
||
Preview @file{file} with @code{gxditview}, using the @file{me} macro
|
||
package. Since no @option{-T} option is specified, use the default
|
||
device (@samp{ps}). Note that you can either say @w{@samp{-m me}} or
|
||
@w{@samp{-me}}; the latter is an anachronism from the early days of
|
||
@acronym{UNIX}.@footnote{The same is true for the other main macro
|
||
packages that come with @code{groff}: @file{man}, @file{mdoc},
|
||
@file{ms}, @file{mm}, and @file{mandoc}. This won't work in general;
|
||
for example, to load @file{trace.tmac}, either @samp{-mtrace} or
|
||
@w{@samp{-m trace}} must be used.}
|
||
|
||
@Example
|
||
groff -man -rD1 -z file
|
||
@endExample
|
||
|
||
@noindent
|
||
Check @file{file} with the @file{man} macro package, forcing
|
||
double-sided printing -- don't produce any output.
|
||
|
||
@menu
|
||
* grog::
|
||
@end menu
|
||
|
||
@c ---------------------------------------------------------------------
|
||
|
||
@node grog, , Invocation Examples, Invocation Examples
|
||
@subsection @code{grog}
|
||
|
||
@pindex grog
|
||
@code{grog} reads files, guesses which of the @code{groff} preprocessors
|
||
and/or macro packages are required for formatting them, and prints the
|
||
@code{groff} command including those options on the standard output. It
|
||
generates one or more of the options @option{-e}, @option{-man},
|
||
@option{-me}, @option{-mm}, @option{-mom}, @option{-ms}, @option{-mdoc},
|
||
@option{-mdoc-old}, @option{-p}, @option{-R}, @option{-g}, @option{-G},
|
||
@option{-s}, and @option{-t}.
|
||
|
||
A special file name@w{ }@file{-} refers to the standard input. Specifying
|
||
no files also means to read the standard input. Any specified options
|
||
are included in the printed command. No space is allowed between
|
||
options and their arguments. The only options recognized are
|
||
@option{-C} (which is also passed on) to enable compatibility mode, and
|
||
@option{-v} to print the version number and exit.
|
||
|
||
For example,
|
||
|
||
@Example
|
||
grog -Tdvi paper.ms
|
||
@endExample
|
||
|
||
@noindent
|
||
guesses the appropriate command to print @file{paper.ms} and then prints
|
||
it to the command line after adding the @option{-Tdvi} option. For
|
||
direct execution, enclose the call to @code{grog} in backquotes at the
|
||
@acronym{UNIX} shell prompt:
|
||
|
||
@Example
|
||
`grog -Tdvi paper.ms` > paper.dvi
|
||
@endExample
|
||
|
||
@noindent
|
||
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
|
||
@code{less}).
|
||
|
||
|
||
|
||
@c =====================================================================
|
||
@c =====================================================================
|
||
|
||
@node Tutorial for Macro Users, Macro Packages, Invoking groff, Top
|
||
@chapter Tutorial for Macro Users
|
||
@cindex tutorial for macro users
|
||
@cindex macros, tutorial for users
|
||
@cindex user's tutorial for macros
|
||
@cindex user's macro tutorial
|
||
|
||
Most users tend to use a macro package to format their papers. This
|
||
means that the whole breadth of @code{groff} is not necessary for most
|
||
people. This chapter covers the material needed to efficiently use a
|
||
macro package.
|
||
|
||
@menu
|
||
* Basics::
|
||
* Common Features::
|
||
@end menu
|
||
|
||
|
||
@c =====================================================================
|
||
|
||
@node Basics, Common Features, Tutorial for Macro Users, Tutorial for Macro Users
|
||
@section Basics
|
||
@cindex basics of macros
|
||
@cindex macro basics
|
||
|
||
This section covers some of the basic concepts necessary to understand
|
||
how to use a macro package.@footnote{This section is derived from
|
||
@cite{Writing Papers with nroff using -me} by Eric P.@w{ }Allman.}
|
||
References are made throughout to more detailed information, if desired.
|
||
|
||
@code{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
|
||
(@dfn{requests} and @dfn{escapes}), which tell @code{gtroff} how to
|
||
format the output. For more detail on this, see @ref{Embedded
|
||
Commands}.
|
||
|
||
The word @dfn{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
|
||
|
||
@Example
|
||
.sp
|
||
@endExample
|
||
|
||
@noindent
|
||
spaces one line, but
|
||
|
||
@Example
|
||
.sp 4
|
||
@endExample
|
||
|
||
@noindent
|
||
spaces four lines. The number@w{ }4 is an argument to the @code{sp}
|
||
request which says to space four lines instead of one. Arguments are
|
||
separated from the request and from each other by spaces (@emph{no}
|
||
tabs). More details on this can be found in @ref{Request Arguments}.
|
||
|
||
The primary function of @code{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:
|
||
|
||
@Example
|
||
Now is the time
|
||
for all good men
|
||
to come to the aid
|
||
of their party.
|
||
Four score and seven
|
||
years ago, etc.
|
||
@endExample
|
||
|
||
@noindent
|
||
is read, packed onto output lines, and justified to produce:
|
||
|
||
@quotation
|
||
Now is the time for all good men to come to the aid of their party.
|
||
Four score and seven years ago, etc.
|
||
@end quotation
|
||
|
||
@cindex break
|
||
@cindex line break
|
||
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 @dfn{break}, which starts a new output
|
||
line. Some requests cause a break automatically, as normally do blank
|
||
input lines and input lines beginning with a space.
|
||
|
||
Not all input lines are text to be formatted. Some input lines are
|
||
requests which describe how to format the text. Requests always have a
|
||
period (@samp{.}) or an apostrophe (@samp{'}) 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 @code{gtroff}.
|
||
|
||
@itemize @bullet
|
||
@item
|
||
First, keep the input lines short. Short input lines are easier to
|
||
edit, and @code{gtroff} packs words onto longer lines anyhow.
|
||
|
||
@item
|
||
In keeping with this, it is helpful to begin a new line after every
|
||
comma or phrase, since common corrections are to add or delete sentences
|
||
or phrases.
|
||
|
||
@item
|
||
End each sentence with two spaces -- or better, start each sentence on a
|
||
new line. @code{gtroff} recognizes characters that usually end a
|
||
sentence, and inserts sentence space accordingly.
|
||
|
||
@item
|
||
Do not hyphenate words at the end of lines -- @code{gtroff} is smart
|
||
enough to hyphenate words as needed, but is not smart enough to take
|
||
hyphens out and join a word back together. Also, words such as
|
||
``mother-in-law'' should not be broken over a line, since then a space
|
||
can occur where not wanted, such as ``@w{mother- in}-law''.
|
||
@end itemize
|
||
|
||
@cindex double-spacing (@code{ls})
|
||
@cindex spacing
|
||
@code{gtroff} double-spaces output text automatically if you use the
|
||
request @w{@samp{.ls 2}}. Reactivate single-spaced mode by typing
|
||
@w{@samp{.ls 1}}.@footnote{If you need finer granularity of the
|
||
vertical space, use the @code{pvs} request (@pxref{Changing Type
|
||
Sizes}).}
|
||
|
||
A number of requests allow to change the way the output looks,
|
||
sometimes called the @dfn{layout} of the output page. Most of these
|
||
requests adjust the placing of @dfn{whitespace} (blank lines or
|
||
spaces).
|
||
|
||
@cindex new page (@code{bp})
|
||
The @code{bp} request starts a new page, causing a line break.
|
||
|
||
@cindex blank line (@code{sp})
|
||
@cindex empty line (@code{sp})
|
||
@cindex line, empty (@code{sp})
|
||
The request @w{@samp{.sp @var{N}}} leaves @var{N}@w{ }lines of blank
|
||
space. @var{N}@w{ }can be omitted (meaning skip a single line) or can
|
||
be of the form @var{N}i (for @var{N}@w{ }inches) or @var{N}c (for
|
||
@var{N}@w{ }centimeters). For example, the input:
|
||
|
||
@Example
|
||
.sp 1.5i
|
||
My thoughts on the subject
|
||
.sp
|
||
@endExample
|
||
|
||
@noindent
|
||
leaves one and a half inches of space, followed by the line ``My
|
||
thoughts on the subject'', followed by a single blank line (more
|
||
measurement units are available, see @ref{Measurements}).
|
||
|
||
@cindex centering lines (@code{ce})
|
||
@cindex lines, centering (@code{ce})
|
||
Text lines can be centered by using the @code{ce} request. The line
|
||
after @code{ce} is centered (horizontally) on the page. To center more
|
||
than one line, use @w{@samp{.ce @var{N}}} (where @var{N} is the number
|
||
of lines to center), followed by the @var{N}@w{ }lines. To center many
|
||
lines without counting them, type:
|
||
|
||
@Example
|
||
.ce 1000
|
||
lines to center
|
||
.ce 0
|
||
@endExample
|
||
|
||
@noindent
|
||
The @w{@samp{.ce 0}} request tells @code{groff} to center zero more
|
||
lines, in other words, stop centering.
|
||
|
||
@cindex line break (@code{br})
|
||
@cindex break (@code{br})
|
||
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
|
||
@code{br}.
|
||
|
||
|
||
@c =====================================================================
|
||
|
||
@node Common Features, , Basics, Tutorial for Macro Users
|
||
@section Common Features
|
||
@cindex common features
|
||
@cindex features, common
|
||
|
||
@code{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 @dfn{macros}
|
||
and collected into a @dfn{macro package}.
|
||
|
||
All macro packages provide certain common capabilities which fall into
|
||
the following categories.
|
||
|
||
@menu
|
||
* Paragraphs::
|
||
* Sections and Chapters::
|
||
* Headers and Footers::
|
||
* Page Layout Adjustment::
|
||
* Displays::
|
||
* Footnotes and Annotations::
|
||
* Table of Contents::
|
||
* Indices::
|
||
* Paper Formats::
|
||
* Multiple Columns::
|
||
* Font and Size Changes::
|
||
* Predefined Strings::
|
||
* Preprocessor Support::
|
||
* Configuration and Customization::
|
||
@end menu
|
||
|
||
@c ---------------------------------------------------------------------
|
||
|
||
@node Paragraphs, Sections and Chapters, Common Features, Common Features
|
||
@subsection Paragraphs
|
||
@cindex paragraphs
|
||
|
||
One of the most common and most used capability is starting a
|
||
paragraph. There are a number of different types of paragraphs, any
|
||
of which can be initiated with macros supplied by the macro package.
|
||
Normally, paragraphs start with a blank line and the first line
|
||
indented, like the text in this manual. There are also block style
|
||
paragraphs, which omit the indentation:
|
||
|
||
@Example
|
||
Some men look at constitutions with sanctimonious
|
||
reverence, and deem them like the ark of the covenant, too
|
||
sacred to be touched.
|
||
@endExample
|
||
|
||
@noindent
|
||
And there are also indented paragraphs which begin with a tag or label
|
||
at the margin and the remaining text indented.
|
||
|
||
@Example
|
||
one This is the first paragraph. Notice how the first
|
||
line of the resulting paragraph lines up with the
|
||
other lines in the paragraph.
|
||
@endExample
|
||
@Example
|
||
longlabel
|
||
This paragraph had a long label. The first
|
||
character of text on the first line does not line up
|
||
with the text on second and subsequent lines,
|
||
although they line up with each other.
|
||
@endExample
|
||
|
||
A variation of this is a bulleted list.
|
||
|
||
@Example
|
||
. Bulleted lists start with a bullet. It is possible
|
||
to use other glyphs instead of the bullet. In nroff
|
||
mode using the ASCII character set for output, a dot
|
||
is used instead of a real bullet.
|
||
@endExample
|
||
|
||
|
||
@c ---------------------------------------------------------------------
|
||
|
||
@node Sections and Chapters, Headers and Footers, Paragraphs, Common Features
|
||
@subsection Sections and Chapters
|
||
|
||
Most macro packages supply some form of section headers. The simplest
|
||
kind is simply the heading on a line by itself in bold type. Others
|
||
supply automatically numbered section heading or different heading
|
||
styles at different levels. Some, more sophisticated, macro packages
|
||
supply macros for starting chapters and appendices.
|
||
|
||
@c ---------------------------------------------------------------------
|
||
|
||
@node Headers and Footers, Page Layout Adjustment, Sections and Chapters, Common Features
|
||
@subsection Headers and Footers
|
||
|
||
Every macro package gives some way to manipulate the @dfn{headers} and
|
||
@dfn{footers} (also called @dfn{titles}) on each page. This is text
|
||
put at the top and bottom of each page, respectively, which contain
|
||
data like the current page number, the current chapter title, and so
|
||
on. Its appearance is not affected by the running text. Some packages
|
||
allow for different ones on the even and odd pages (for material printed
|
||
in a book form).
|
||
|
||
The titles are called @dfn{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 @samp{%} character (see @ref{Page Layout}, for more details).
|
||
|
||
@c ---------------------------------------------------------------------
|
||
|
||
@node Page Layout Adjustment, Displays, Headers and Footers, Common Features
|
||
@subsection Page Layout
|
||
|
||
Most macro packages let the user specify top and bottom margins and
|
||
other details about the appearance of the printed pages.
|
||
|
||
@c ---------------------------------------------------------------------
|
||
|
||
@node Displays, Footnotes and Annotations, Page Layout Adjustment, Common Features
|
||
@subsection Displays
|
||
@cindex displays
|
||
|
||
@dfn{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.
|
||
|
||
@cindex quotes, major
|
||
@cindex major quotes
|
||
@dfn{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.
|
||
|
||
@cindex list
|
||
A @dfn{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.
|
||
|
||
@cindex keep
|
||
A @dfn{keep} is a display of lines which are kept on a single page if
|
||
possible. An example for a keep might be a diagram. Keeps differ from
|
||
lists in that lists may be broken over a page boundary whereas keeps are
|
||
not.
|
||
|
||
@cindex keep, floating
|
||
@cindex floating keep
|
||
@dfn{Floating keeps} move relative to the text. Hence, they are good for
|
||
things which are referred to by name, such as ``See figure@w{ }3''. A
|
||
floating keep appears at the bottom of the current page if it fits;
|
||
otherwise, it appears at the top of the next page. Meanwhile, the
|
||
surrounding text `flows' around the keep, thus leaving no blank areas.
|
||
|
||
@c ---------------------------------------------------------------------
|
||
|
||
@node Footnotes and Annotations, Table of Contents, Displays, Common Features
|
||
@subsection Footnotes and Annotations
|
||
@cindex footnotes
|
||
@cindex annotations
|
||
|
||
There are a number of requests to save text for later printing.
|
||
|
||
@dfn{Footnotes} are printed at the bottom of the current page.
|
||
|
||
@cindex delayed text
|
||
@dfn{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.
|
||
|
||
@c ---------------------------------------------------------------------
|
||
|
||
@node Table of Contents, Indices, Footnotes and Annotations, Common Features
|
||
@subsection Table of Contents
|
||
@cindex table of contents
|
||
@cindex contents, table of
|
||
|
||
@dfn{Tables of contents} are a type of delayed text having a tag
|
||
(usually the page number) attached to each entry after a row of dots.
|
||
The table accumulates throughout the paper until printed, usually after
|
||
the paper has ended. Many macro packages provide the ability to have
|
||
several tables of contents (e.g.@: a standard table of contents, a list
|
||
of tables, etc).
|
||
|
||
@c ---------------------------------------------------------------------
|
||
|
||
@node Indices, Paper Formats, Table of Contents, Common Features
|
||
@subsection Indices
|
||
@cindex index, in macro package
|
||
|
||
While some macro packages use the term @dfn{index}, none actually
|
||
provide that functionality. The facilities they call indices are
|
||
actually more appropriate for tables of contents.
|
||
|
||
@pindex makeindex
|
||
To produce a real index in a document, external tools like the
|
||
@code{makeindex} program are necessary.
|
||
|
||
@c ---------------------------------------------------------------------
|
||
|
||
@node Paper Formats, Multiple Columns, Indices, Common Features
|
||
@subsection Paper Formats
|
||
@cindex paper formats
|
||
|
||
Some macro packages provide stock formats for various kinds of
|
||
documents. Many of them provide a common format for the title and
|
||
opening pages of a technical paper. The @file{mm} macros in particular
|
||
provide formats for letters and memoranda.
|
||
|
||
@c ---------------------------------------------------------------------
|
||
|
||
@node Multiple Columns, Font and Size Changes, Paper Formats, Common Features
|
||
@subsection Multiple Columns
|
||
|
||
Some macro packages (but not @file{man}) provide the ability to have two
|
||
or more columns on a page.
|
||
|
||
@c ---------------------------------------------------------------------
|
||
|
||
@node Font and Size Changes, Predefined Strings, Multiple Columns, Common Features
|
||
@subsection Font and Size Changes
|
||
|
||
The built-in font and size functions are not always intuitive, so all
|
||
macro packages provide macros to make these operations simpler.
|
||
|
||
@c ---------------------------------------------------------------------
|
||
|
||
@node Predefined Strings, Preprocessor Support, Font and Size Changes, Common Features
|
||
@subsection Predefined Strings
|
||
|
||
Most macro packages provide various predefined strings for a variety of
|
||
uses; examples are sub- and superscripts, printable dates, quotes and
|
||
various special characters.
|
||
|
||
@c ---------------------------------------------------------------------
|
||
|
||
@node Preprocessor Support, Configuration and Customization, Predefined Strings, Common Features
|
||
@subsection Preprocessor Support
|
||
|
||
All macro packages provide support for various preprocessors and may
|
||
extend their functionality.
|
||
|
||
For example, all macro packages mark tables (which are processed with
|
||
@code{gtbl}) by placing them between @code{TS} and @code{TE} macros.
|
||
The @file{ms} macro package has an option, @samp{.TS@w{ }H}, that prints
|
||
a caption at the top of a new page (when the table is too long to fit on
|
||
a single page).
|
||
|
||
@c ---------------------------------------------------------------------
|
||
|
||
@node Configuration and Customization, , Preprocessor Support, Common Features
|
||
@subsection Configuration and Customization
|
||
|
||
Some macro packages provide means of customizing many of the details of
|
||
how the package behaves. This ranges from setting the default type size
|
||
to changing the appearance of section headers.
|
||
|
||
|
||
|
||
@c =====================================================================
|
||
@c =====================================================================
|
||
|
||
@node Macro Packages, gtroff Reference, Tutorial for Macro Users, Top
|
||
@chapter Macro Packages
|
||
@cindex macro packages
|
||
@cindex packages, macros
|
||
|
||
This chapter documents the main macro packages that come with
|
||
@code{groff}.
|
||
|
||
@menu
|
||
* man::
|
||
* mdoc::
|
||
* ms::
|
||
* me::
|
||
* mm::
|
||
@end menu
|
||
|
||
|
||
@c =====================================================================
|
||
|
||
@node man, mdoc, Macro Packages, Macro Packages
|
||
@section @file{man}
|
||
@cindex manual pages
|
||
@cindex man pages
|
||
@pindex an.tmac
|
||
@pindex man.tmac
|
||
@pindex man-old.tmac
|
||
|
||
This is the most popular and probably the most important macro package
|
||
of @code{groff}. It is easy to use, and a vast majority of manual pages
|
||
are based on it.
|
||
|
||
@menu
|
||
* Man options::
|
||
* Man usage::
|
||
* Man font macros::
|
||
* Miscellaneous man macros::
|
||
* Predefined man strings::
|
||
* Preprocessors in man pages::
|
||
@end menu
|
||
|
||
@c ---------------------------------------------------------------------
|
||
|
||
@node Man options, Man usage, man, man
|
||
@subsection Options
|
||
|
||
The command line format for using the @file{man} macros with
|
||
@code{groff} is:
|
||
|
||
@Example
|
||
groff -m man [ -rLL=@var{length} ] [ -rLT=@var{length} ]
|
||
[ -rcR=1 ] [ -rC1 ] [ -rD1 ] [ -rP@var{nnn} ]
|
||
[ -rS@var{xx} ] [ -rX@var{nnn} ] [ @var{files}@dots{} ]
|
||
@endExample
|
||
|
||
@noindent
|
||
It is possible to use @samp{-man} instead of @w{@samp{-m man}}.
|
||
|
||
@table @code
|
||
@item -rLL=@var{length}
|
||
Set line length to @var{length}. If not specified, the line length
|
||
defaults to 78@w{ }en in nroff mode (this is 78@w{ }characters per
|
||
line) and 6.5@w{ }inch otherwise.
|
||
|
||
@item -rLT=@var{length}
|
||
Set title length to @var{length}. If not specified, the title length
|
||
defaults to 78@w{ }en in nroff mode (this is 78@w{ }characters per
|
||
line) and 6.5@w{ }inch otherwise.
|
||
|
||
@item -rcR=1
|
||
This option (the default if a TTY output device is used) creates a
|
||
single, very long page instead of multiple pages. Use @code{-rcR=0}
|
||
to disable it.
|
||
|
||
@item -rC1
|
||
If more than one manual page is given on the command line, number the
|
||
pages continuously, rather than starting each at@w{ }1.
|
||
|
||
@item -rD1
|
||
Double-sided printing. Footers for even and odd pages are formatted
|
||
differently.
|
||
|
||
@item -rP@var{nnn}
|
||
Page numbering starts with @var{nnn} rather than with@w{ }1.
|
||
|
||
@item -rS@var{xx}
|
||
Use @var{xx} (which can be 10, 11, or@w{ }12@dmn{pt}) as the base
|
||
document font size instead of the default value of@w{ }10@dmn{pt}.
|
||
|
||
@item -rX@var{nnn}
|
||
After page @var{nnn}, number pages as @var{nnn}a, @var{nnn}b,
|
||
@var{nnn}c, etc. For example, the option @option{-rX2} produces the
|
||
following page numbers: 1, 2, 2a, 2b, 2c, etc.
|
||
@end table
|
||
|
||
@c ---------------------------------------------------------------------
|
||
|
||
@node Man usage, Man font macros, Man options, man
|
||
@subsection Usage
|
||
@cindex @code{man} macros
|
||
@cindex macros for manual pages [@code{man}]
|
||
|
||
@pindex man.local
|
||
This section describes the available macros for manual pages. For
|
||
further customization, put additional macros and requests into the file
|
||
@file{man.local} which is loaded immediately after the @file{man}
|
||
package.
|
||
|
||
@Defmac {TH, title section [@Var{extra1} [@Var{extra2} [@Var{extra3}]]], man}
|
||
Set the title of the man page to @var{title} and the section to
|
||
@var{section}, which must have a value between 1 and@w{ }8. The value
|
||
of @var{section} may also have a string appended, e.g.@: @samp{.pm},
|
||
to indicate a specific subsection of the man pages.
|
||
|
||
Both @var{title} and @var{section} are positioned at the left and right
|
||
in the header line (with @var{section} in parentheses immediately
|
||
appended to @var{title}. @var{extra1} is positioned in the middle of
|
||
the footer line. @var{extra2} is positioned at the left in the footer
|
||
line (or at the left on even pages and at the right on odd pages if
|
||
double-sided printing is active). @var{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@w{ }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 @code{TH} macro at the
|
||
beginning of the file.
|
||
@endDefmac
|
||
|
||
@Defmac {SH, [@Var{heading}], man}
|
||
Set up an unnumbered section heading sticking out to the left. Prints
|
||
out all the text following @code{SH} up to the end of the line (or the
|
||
text in the next line if there is no argument to @code{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.
|
||
@endDefmac
|
||
|
||
@Defmac {SS, [@Var{heading}], man}
|
||
Set up an unnumbered (sub)section heading. Prints out all the text
|
||
following @code{SS} up to the end of the line (or the text in the next
|
||
line if there is no argument to @code{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.
|
||
@endDefmac
|
||
|
||
@Defmac {TP, [@Var{nnn}], man}
|
||
Set up an indented paragraph with label. The indentation is set to
|
||
@var{nnn} if that argument is supplied (the default unit is @samp{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 has
|
||
default font settings.
|
||
@endDefmac
|
||
|
||
@DefmacList {LP, , man}
|
||
@DefmacItem {PP, , man}
|
||
@DefmacListEnd {P, , man}
|
||
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 @code{PD} macro. The font size and shape are
|
||
reset to the default value (10@dmn{pt} roman if no @option{-rS} option
|
||
is given on the command line). Finally, the current left margin is
|
||
restored.
|
||
@endDefmac
|
||
|
||
@Defmac {IP, [@Var{designator} [@Var{nnn}]], man}
|
||
Set up an indented paragraph, using @var{designator} as a tag to mark
|
||
its beginning. The indentation is set to @var{nnn} if that argument
|
||
is supplied (default unit is @samp{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 @samp{""} (two double quotes) as the first argument of
|
||
@code{IP}.
|
||
|
||
For example, to start a paragraph with bullets as the designator and
|
||
4@w{ }en indentation, write
|
||
|
||
@Example
|
||
.IP \(bu 4
|
||
@endExample
|
||
@endDefmac
|
||
|
||
@Defmac {HP, [@Var{nnn}], man}
|
||
@cindex hanging indentation [@code{man}]
|
||
@cindex @code{man} macros, hanging indentation
|
||
Set up a paragraph with hanging left indentation. The indentation is
|
||
set to @var{nnn} if that argument is supplied (default unit is
|
||
@samp{n}), otherwise the default indentation value is used. Font size
|
||
and face are reset to their default values.
|
||
@endDefmac
|
||
|
||
@Defmac {RS, [@Var{nnn}], man}
|
||
@cindex left margin, how to move [@code{man}]
|
||
@cindex @code{man} macros, moving left margin
|
||
Move the left margin to the right by the value @var{nnn} if specified
|
||
(default unit is @samp{n}); otherwise the default indentation value
|
||
is used. Calls to the @code{RS} macro can be nested.
|
||
@endDefmac
|
||
|
||
@Defmac {RE, [@Var{nnn}], man}
|
||
Move the left margin back to level @var{nnn}; if no argument is given,
|
||
it moves one level back. The first level (i.e., no call to @code{RS}
|
||
yet) has number@w{ }1, and each call to @code{RS} increases the level
|
||
by@w{ }1.
|
||
@endDefmac
|
||
|
||
@cindex line breaks, with vertical space [@code{man}]
|
||
@cindex @code{man} macros, line breaks with vertical space
|
||
To summarize, the following macros cause a line break with the insertion
|
||
of vertical space (which amount can be changed with the @code{PD}
|
||
macro): @code{SH}, @code{SS}, @code{TP}, @code{LP} (@code{PP},
|
||
@code{P}), @code{IP}, and @code{HP}.
|
||
|
||
@cindex line breaks, without vertical space [@code{man}]
|
||
@cindex @code{man} macros, line breaks without vertical space
|
||
The macros @code{RS} and @code{RE} also cause a break but do not insert
|
||
vertical space.
|
||
|
||
@cindex default indentation, resetting [@code{man}]
|
||
@cindex indentaion, resetting to default [@code{man}]
|
||
@cindex @code{man} macros, resetting default indentation
|
||
Finally, the macros @code{SH}, @code{SS}, @code{LP} (@code{PP}, @code{P}),
|
||
and @code{RS} reset the indentation to its default value.
|
||
|
||
@c ---------------------------------------------------------------------
|
||
|
||
@node Man font macros, Miscellaneous man macros, Man usage, man
|
||
@subsection Macros to set fonts
|
||
@cindex font selection [@code{man}]
|
||
@cindex @code{man} macros, how to set fonts
|
||
|
||
The standard font is roman; the default text size is 10@w{ }point.
|
||
If command line option @option{-rS=@var{n}} is given, use
|
||
@var{n}@dmn{pt} as the default text size.
|
||
|
||
@Defmac {SM, [@Var{text}], man}
|
||
Set the text on the same line or the text on the next line in a font
|
||
that is one point size smaller than the default font.
|
||
@endDefmac
|
||
|
||
@Defmac {SB, [@Var{text}], man}
|
||
@cindex bold face [@code{man}]
|
||
@cindex @code{man} macros, bold face
|
||
Set the text on the same line or the text on the next line in bold face
|
||
font, one point size smaller than the default font.
|
||
@endDefmac
|
||
|
||
@Defmac {BI, text, man}
|
||
Set its arguments alternately in bold face and italic. Thus,
|
||
|
||
@Example
|
||
.BI this "word and" that
|
||
@endExample
|
||
|
||
@noindent
|
||
would set ``this'' and ``that'' in bold face, and ``word and'' in
|
||
italics.
|
||
@endDefmac
|
||
|
||
@Defmac {IB, text, man}
|
||
Set its arguments alternately in italic and bold face.
|
||
@endDefmac
|
||
|
||
@Defmac {RI, text, man}
|
||
Set its arguments alternately in roman and italic.
|
||
@endDefmac
|
||
|
||
@Defmac {IR, text, man}
|
||
Set its arguments alternately in italic and roman.
|
||
@endDefmac
|
||
|
||
@Defmac {BR, text, man}
|
||
Set its arguments alternately in bold face and roman.
|
||
@endDefmac
|
||
|
||
@Defmac {RB, text, man}
|
||
Set its arguments alternately in roman and bold face.
|
||
@endDefmac
|
||
|
||
@Defmac {B, [@Var{text}], man}
|
||
Set @var{text} 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.
|
||
@endDefmac
|
||
|
||
@Defmac {I, [@Var{text}], man}
|
||
@cindex italic fonts [@code{man}]
|
||
@cindex @code{man} macros, italic fonts
|
||
Set @var{text} 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.
|
||
@endDefmac
|
||
|
||
@c ---------------------------------------------------------------------
|
||
|
||
@node Miscellaneous man macros, Predefined man strings, Man font macros, man
|
||
@subsection Miscellaneous macros
|
||
|
||
@pindex grohtml
|
||
@cindex @code{man} macros, default indentation
|
||
@cindex default indentation [@code{man}]
|
||
The default indentation is 7.2@w{ }en for all output devices except for
|
||
@code{grohtml} which ignores indentation.
|
||
|
||
@Defmac {DT, , man}
|
||
@cindex tab stops [@code{man}]
|
||
@cindex @code{man} macros, tab stops
|
||
Set tabs every 0.5@w{ }inches. Since this macro is always executed
|
||
during a call to the @code{TH} macro, it makes sense to call it only if
|
||
the tab positions have been changed.
|
||
@endDefmac
|
||
|
||
@Defmac {PD, [@Var{nnn}], man}
|
||
@cindex empty space before a paragraph [@code{man}]
|
||
@cindex @code{man} macros, empty space before a paragraph
|
||
Adjust the empty space before a new paragraph (or section). The
|
||
optional argument gives the amount of space (default unit is
|
||
@samp{v}); without parameter, the value is reset to its default value
|
||
(1@w{ }line for TTY devices, 0.4@dmn{v}@w{ }otherwise).
|
||
@endDefmac
|
||
|
||
This affects the macros @code{SH}, @code{SS}, @code{TP}, @code{LP} (as
|
||
well as @code{PP} and @code{P}), @code{IP}, and @code{HP}.
|
||
|
||
@c ---------------------------------------------------------------------
|
||
|
||
@node Predefined man strings, Preprocessors in man pages, Miscellaneous man macros, man
|
||
@subsection Predefined strings
|
||
|
||
The following strings are defined:
|
||
|
||
@Defstr {S, man}
|
||
Switch back to the default font size.
|
||
@endDefstr
|
||
|
||
@Defstr {R, man}
|
||
The `registered' sign.
|
||
@endDefstr
|
||
|
||
@Defstr {Tm, man}
|
||
The `trademark' sign.
|
||
@endDefstr
|
||
|
||
@DefstrList {lq, man}
|
||
@DefstrListEnd {rq, man}
|
||
@cindex @code{lq} glyph, and @code{lq} string [@code{man}]
|
||
@cindex @code{rq} glyph, and @code{rq} string [@code{man}]
|
||
Left and right quote. This is equal to @code{\(lq} and @code{\(rq},
|
||
respectively.
|
||
@endDefstr
|
||
|
||
@c ---------------------------------------------------------------------
|
||
|
||
@node Preprocessors in man pages, , Predefined man strings, man
|
||
@subsection Preprocessors in @file{man} pages
|
||
|
||
@cindex preprocessor, calling convention
|
||
@cindex calling convention of preprocessors
|
||
If a preprocessor like @code{gtbl} or @code{geqn} is needed, it has
|
||
become common usage to make the first line of the man page look like
|
||
this:
|
||
|
||
@Example
|
||
'\" @var{word}
|
||
@endExample
|
||
|
||
@pindex geqn@r{, invocation in manual pages}
|
||
@pindex grefer@r{, invocation in manual pages}
|
||
@pindex gtbl@r{, invocation in manual pages}
|
||
@pindex man@r{, invocation of preprocessors}
|
||
@noindent
|
||
Note the single space character after the double quote. @var{word}
|
||
consists of letters for the needed preprocessors: @samp{e} for
|
||
@code{geqn}, @samp{r} for @code{grefer}, @samp{t} for @code{gtbl}.
|
||
Modern implementations of the @code{man} program read this first line
|
||
and automatically call the right preprocessor(s).
|
||
|
||
|
||
@c =====================================================================
|
||
|
||
@node mdoc, ms, man, Macro Packages
|
||
@section @file{mdoc}
|
||
@cindex @code{mdoc} macros
|
||
|
||
@c XXX documentation
|
||
@c XXX this is a placeholder until we get stuff knocked into shape
|
||
See the @cite{groff_mdoc(7)} man page (type @command{man groff_mdoc}
|
||
at the command line).
|
||
|
||
|
||
@c =====================================================================
|
||
|
||
@node ms, me, mdoc, Macro Packages
|
||
@section @file{ms}
|
||
@cindex @code{ms} macros
|
||
|
||
The @file{-ms}
|
||
macros are suitable for reports, letters, books,
|
||
user manuals, and so forth.
|
||
The package provides macros for cover pages, section headings,
|
||
paragraphs, lists, footnotes, pagination,
|
||
and a table of contents.
|
||
|
||
@menu
|
||
* ms Intro::
|
||
* General ms Structure::
|
||
* ms Document Control Registers::
|
||
* ms Cover Page Macros::
|
||
* ms Body Text::
|
||
* ms Page Layout::
|
||
* Differences from AT&T ms::
|
||
@end menu
|
||
|
||
@c ---------------------------------------------------------------------
|
||
|
||
@node ms Intro, General ms Structure, ms, ms
|
||
@subsection Introduction to @file{ms}
|
||
|
||
The original @file{-ms} macros were included with
|
||
@acronym{AT&T} @code{troff} as well as the
|
||
@file{man} macros.
|
||
While the @file{man} package is intended for brief documents
|
||
that can be read on-line as well as printed, the @file{ms}
|
||
macros are suitable for longer documents that are meant to be
|
||
printed rather than read on-line.
|
||
|
||
The @file{ms} macro package included with @code{groff}
|
||
is a complete, bottom-up re-implementation.
|
||
Several macros (specific to @acronym{AT&T}
|
||
or Berkeley) are not included, while several new commands are.
|
||
@xref{Differences from AT&T ms}, for more information.
|
||
|
||
@c ---------------------------------------------------------------------
|
||
|
||
@node General ms Structure, ms Document Control Registers, ms Intro, ms
|
||
@subsection General structure of an @file{ms} document
|
||
@cindex @code{ms} macros, general structure
|
||
|
||
The @file{ms} macro package expects a certain amount of structure,
|
||
but not as much as packages such as @file{man} or @file{mdoc}.
|
||
|
||
The simplest documents can begin with a paragraph macro
|
||
(such as @code{LP} or @code{PP}),
|
||
and consist of text separated by paragraph macros
|
||
or even blank lines.
|
||
Longer documents have a structure as follows:
|
||
|
||
@table @strong
|
||
@item Document type
|
||
If you invoke the @code{RP}
|
||
(report) macro on the first line of the document,
|
||
@code{groff} prints the cover page information on its own page;
|
||
otherwise it prints the information on the
|
||
first page with your document text immediately following.
|
||
Other document formats found in @acronym{AT&T} @code{troff}
|
||
are specific to @acronym{AT&T} or Berkeley, and are not supported in
|
||
@code{groff}.
|
||
|
||
@item Format and layout
|
||
By setting number registers,
|
||
you can change your document's type (font and size),
|
||
margins, spacing, headers and footers, and footnotes.
|
||
@xref{ms Document Control Registers}, for more details.
|
||
|
||
@item Cover page
|
||
A cover page consists of a title, the author's name and institution,
|
||
an abstract, and the date.
|
||
@footnote{Actually, only the title is required.}
|
||
@xref{ms Cover Page Macros}, for more details.
|
||
|
||
@item Body
|
||
Following the cover page is your document.
|
||
You can use the @file{ms}
|
||
macros to write reports, letters, books, and so forth.
|
||
The package is designed for structured documents,
|
||
consisting of paragraphs interspersed with headings
|
||
and augmented by lists, footnotes, tables, and other
|
||
common constructs.
|
||
@xref{ms Body Text}, for more details.
|
||
|
||
@item Table of contents
|
||
Longer documents usually include a table of contents,
|
||
which you can invoke by placing the
|
||
@code{TC}
|
||
macro at the end of your document.
|
||
The @file{ms}
|
||
macros have minimal indexing facilities, consisting of the
|
||
@code{IX} macro, which prints an entry on standard error.
|
||
Printing the table of contents at the end is necessary since
|
||
@code{groff} is a single-pass text formatter,
|
||
thus it cannot determine the page number of each section
|
||
until that section has actually been set and printed.
|
||
Since @file{ms} output is intended for hardcopy,
|
||
you can manually relocate the pages containing
|
||
the table of contents between the cover page and the
|
||
body text after printing.
|
||
@end table
|
||
|
||
@c ---------------------------------------------------------------------
|
||
|
||
@node ms Document Control Registers, ms Cover Page Macros, General ms Structure, ms
|
||
@subsection Document control registers
|
||
@cindex @code{ms} macros, document control registers
|
||
|
||
The following is a list of document control number registers.
|
||
For the sake of consistency,
|
||
set registers related to margins at the beginning of your document,
|
||
or just after the @code{RP} macro.
|
||
You can set other registers later in your document,
|
||
but you should keep them together at the beginning
|
||
to make them easy to find and edit as necessary.
|
||
|
||
@unnumberedsubsubsec Margin Settings
|
||
|
||
@Defmpreg {PO, ms}
|
||
Defines the page offset (i.e.@: the left margin).
|
||
There is no explicit right margin setting; the combination of
|
||
the @code{PO} and @code{LL} registers implicitly define the
|
||
right margin width.
|
||
|
||
Effective: next page.
|
||
|
||
Default value: 1@dmn{i}.
|
||
@endDefmpreg
|
||
|
||
@Defmpreg {LL, ms}
|
||
Defines the line length (i.e.@: the width of the body text).
|
||
|
||
Effective: next paragraph.
|
||
|
||
Default: 6@dmn{i}.
|
||
@endDefmpreg
|
||
|
||
@Defmpreg {LT, ms}
|
||
Defines the title length (i.e.@: the header and footer width).
|
||
This is usually the same as @code{LL}, but not necessarily.
|
||
|
||
Effective: next paragraph.
|
||
|
||
Default: 6@dmn{i}.
|
||
@endDefmpreg
|
||
|
||
@Defmpreg {HM, ms}
|
||
Defines the header margin height at the top of the page.
|
||
|
||
Effective: next page.
|
||
|
||
Default: 1@dmn{i}.
|
||
@endDefmpreg
|
||
|
||
@Defmpreg {FM, ms}
|
||
Defines the footer margin height at the bottom of the page.
|
||
|
||
Effective: next page.
|
||
|
||
Default: 1@dmn{i}.
|
||
@endDefmpreg
|
||
|
||
@unnumberedsubsubsec Text Settings
|
||
|
||
@Defmpreg {PS, ms}
|
||
Defines the point size of the body text.
|
||
|
||
Effective: next paragraph.
|
||
|
||
Default: 10@dmn{p}.
|
||
@endDefmpreg
|
||
|
||
@Defmpreg {VS, ms}
|
||
Defines the space between lines (line height plus leading).
|
||
|
||
Effective: next paragraph.
|
||
|
||
Default: 12@dmn{p}.
|
||
@endDefmpreg
|
||
|
||
@unnumberedsubsubsec Paragraph Settings
|
||
|
||
@Defmpreg {PI, ms}
|
||
Defines the initial indent of a @code{.PP} paragraph.
|
||
|
||
Effective: next paragraph.
|
||
|
||
Default: 5@dmn{n}.
|
||
@endDefmpreg
|
||
|
||
@Defmpreg {PD, ms}
|
||
Defines the space between paragraphs.
|
||
|
||
Effective: next paragraph.
|
||
|
||
Default: 0.3@dmn{v}.
|
||
@endDefmpreg
|
||
|
||
@Defmpreg {QI, ms}
|
||
Defines the indent on both sides of a quoted (@code{.QP}) paragraph.
|
||
|
||
Effective: next paragraph.
|
||
|
||
Default: 5@dmn{n}.
|
||
@endDefmpreg
|
||
|
||
@unnumberedsubsubsec Footnote Settings
|
||
|
||
@Defmpreg {FL, ms}
|
||
Defines the length of a footnote.
|
||
|
||
Effective: next footnote.
|
||
|
||
Default: @math{@code{@\n[LL]} * 5 / 6}.
|
||
@endDefmpreg
|
||
|
||
@Defmpreg {FI, ms}
|
||
Defines the footnote indent.
|
||
|
||
Effective: next footnote.
|
||
|
||
Default: 2@dmn{n}.
|
||
@endDefmpreg
|
||
|
||
@Defmpreg {FF, ms}
|
||
The footnote format:
|
||
@table @code
|
||
@item 0
|
||
Prints the footnote number as a superscript; indents the footnote (default).
|
||
|
||
@item 1
|
||
Prints the number followed by a period (like 1.)
|
||
and indents the footnote.
|
||
|
||
@item 2
|
||
Like 1, without an indent.
|
||
|
||
@item 3
|
||
Like 1, but prints the footnote number as a hanging paragraph.
|
||
@end table
|
||
|
||
Effective: next footnote.
|
||
|
||
Default: 0.
|
||
@endDefmpreg
|
||
|
||
@unnumberedsubsubsec Miscellaneous Number Registers
|
||
|
||
@Defmpreg {MINGW, ms}
|
||
Defines the minimum width between columns in a multi-column document.
|
||
|
||
Effective: next page.
|
||
|
||
Default: 2@dmn{n}.
|
||
@endDefmpreg
|
||
|
||
@c ---------------------------------------------------------------------
|
||
|
||
@node ms Cover Page Macros, ms Body Text, ms Document Control Registers, ms
|
||
@subsection Cover page macros
|
||
@cindex @code{ms} macros, cover page
|
||
@cindex cover page macros, [@code{ms}]
|
||
|
||
Use the following macros to create a cover page for your document
|
||
in the order shown.
|
||
|
||
@Defmac {RP, [@code{no}], ms}
|
||
Specifies the report format for your document.
|
||
The report format creates a separate cover page.
|
||
The default action (no @code{.RP}
|
||
macro) is to print a subset of the
|
||
cover page on page 1 of your document.
|
||
|
||
If you use the word @code{no} as an optional argument,
|
||
@code{groff} prints a title page but
|
||
does not repeat any of the title page information
|
||
(title, author, abstract, etc.)
|
||
on page 1 of the document.
|
||
@endDefmac
|
||
|
||
@Defmac {DA, [@dots{}], ms}
|
||
(optional) Print the current date, or the arguments to the macro if any,
|
||
on the title page (if specified) and in the footers.
|
||
This is the default for @code{nroff}.
|
||
@endDefmac
|
||
|
||
@Defmac {ND, [@dots{}], ms}
|
||
(optional) Print the current date, or the arguments to the macro if any,
|
||
on the title page (if specified) but not in the footers.
|
||
This is the default for @code{troff}.
|
||
@endDefmac
|
||
|
||
@Defmac {TL, , ms}
|
||
Specifies the document title.
|
||
@code{groff} collects text following the @code{.TL}
|
||
macro into the title, until reaching the author name or abstract.
|
||
@endDefmac
|
||
|
||
@Defmac {AU, , ms}
|
||
Specifies the author's name, which appears on the
|
||
line (or lines) immediately following.
|
||
You can specify multiple authors as follows:
|
||
|
||
@Example
|
||
.AU
|
||
John Doe
|
||
.AI
|
||
University of West Bumblefuzz
|
||
.AU
|
||
Martha Buck
|
||
.AI
|
||
Monolithic Corporation
|
||
|
||
...
|
||
@endExample
|
||
@endDefmac
|
||
|
||
@Defmac {AI, , ms}
|
||
Specifies the author's institution.
|
||
You can specify multiple institutions in the same way
|
||
that you specify multiple authors.
|
||
@endDefmac
|
||
|
||
@Defmac {AB, [@code{no}], ms}
|
||
Begins the abstract.
|
||
The default is to print the word @acronym{ABSTRACT},
|
||
centered and in italics, above the text of the abstract.
|
||
The word @code{no} as an optional argument suppresses this heading.
|
||
@endDefmac
|
||
|
||
@Defmac {AE, , ms}
|
||
End the abstract.
|
||
@endDefmac
|
||
|
||
The following is example mark-up for a title page.
|
||
@cindex title page, example markup
|
||
@cindex example markup, title page
|
||
|
||
@Example
|
||
@cartouche
|
||
.RP
|
||
.TL
|
||
The Inevitability of Code Bloat
|
||
in Commercial and Free Software
|
||
.AU
|
||
J. Random Luser
|
||
.AI
|
||
University of West Bumblefuzz
|
||
.AB
|
||
This report examines the long-term growth
|
||
of the code bases in two large, popular software
|
||
packages; the free Emacs and the commercial
|
||
Microsoft Word.
|
||
While differences appear in the type or order
|
||
of features added, due to the different
|
||
methodologies used, the results are the same
|
||
in the end.
|
||
.PP
|
||
The free software approach is shown to be
|
||
superior in that while free software can
|
||
become as bloated as commercial offerings,
|
||
free software tends to have fewer serious
|
||
bugs and the added features are in line with
|
||
user demand.
|
||
.AE
|
||
|
||
... the rest of the paper follows ...
|
||
@end cartouche
|
||
@endExample
|
||
|
||
@c ---------------------------------------------------------------------
|
||
|
||
@node ms Body Text, ms Page Layout, ms Cover Page Macros, ms
|
||
@subsection Body text
|
||
@cindex @code{ms} macros, body text
|
||
|
||
This section describes macros used to mark up the body of your document.
|
||
Examples include paragraphs, sections, and other groups.
|
||
|
||
@menu
|
||
* Paragraphs in ms::
|
||
* Headings in ms::
|
||
* Highlighting in ms::
|
||
* Lists in ms::
|
||
* Indents in ms::
|
||
* Tabstops in ms::
|
||
* ms Displays and Keeps::
|
||
* ms Insertions::
|
||
* Example multi-page table::
|
||
* ms Footnotes::
|
||
@end menu
|
||
|
||
@c ---------------------------------------------------------------------
|
||
|
||
@node Paragraphs in ms, Headings in ms, ms Body Text, ms Body Text
|
||
@subsubsection Paragraphs
|
||
@cindex @code{ms} macros, paragraph handling
|
||
|
||
The following paragraph types are available.
|
||
|
||
@Defmac {PP, , ms}
|
||
Sets a paragraph with an initial indent.
|
||
@endDefmac
|
||
|
||
@Defmac {LP, , ms}
|
||
Sets a paragraph with no initial indent.
|
||
@endDefmac
|
||
|
||
@Defmac {QP, , ms}
|
||
Sets a paragraph that is indented at both left and right margins.
|
||
The effect is identical to the @acronym{HTML} @code{<BLOCKQUOTE>} element.
|
||
The next paragraph or heading returns margins to normal.
|
||
@endDefmac
|
||
|
||
@Defmac {XP, , ms}
|
||
Sets a paragraph whose lines are indented,
|
||
except for the first line.
|
||
This is a Berkeley extension.
|
||
@endDefmac
|
||
|
||
The following markup uses all four paragraph macros.
|
||
|
||
@Example
|
||
@cartouche
|
||
.NH 2
|
||
Cases used in the study
|
||
.LP
|
||
The following software and versions were
|
||
considered for this report.
|
||
.PP
|
||
For commercial software, we chose
|
||
.B "Microsoft Word for Windows" ,
|
||
starting with version 1.0 through the
|
||
current version (Word 2000).
|
||
.PP
|
||
For free software, we chose
|
||
.B Emacs ,
|
||
from its first appearance as a standalone
|
||
editor through the current version (v20).
|
||
See [Bloggs 2002] for details.
|
||
.QP
|
||
Franklin's Law applied to software:
|
||
software expands to outgrow both
|
||
RAM and disk space over time.
|
||
.LP
|
||
Bibliography:
|
||
.XP
|
||
Bloggs, Joseph R.,
|
||
.I "Everyone's a Critic" ,
|
||
Underground Press, March 2002.
|
||
A definitive work that answers all questions
|
||
and criticisms about the quality and usability of
|
||
free software.
|
||
|
||
@end cartouche
|
||
@endExample
|
||
|
||
@c ---------------------------------------------------------------------
|
||
|
||
@node Headings in ms, Highlighting in ms, Paragraphs in ms, ms Body Text
|
||
@subsubsection Headings
|
||
@cindex @code{ms} macros, headings
|
||
|
||
Use headings to create a hierarchical structure for your document.
|
||
The @file{ms} macros print headings in @strong{bold},
|
||
using the same font family and point size as the body text.
|
||
|
||
The following describes the heading macros:
|
||
|
||
@DefmacList {NH, @Var{curr-level}, ms}
|
||
@DefmacListEnd {NH, @t{S} @Var{level0} @dots{}, ms}
|
||
Numbered heading.
|
||
The argument is either a numeric argument to indicate the
|
||
level of the heading, or the letter@w{ }@code{S} followed by numeric
|
||
arguments to set the heading level explicitly.
|
||
|
||
If you specify heading levels out of sequence, such as invoking
|
||
@samp{.NH 3} after @samp{.NH 1}, @code{groff}
|
||
prints a warning on standard error.
|
||
@endDefmac
|
||
|
||
@Defmac {SH, , ms}
|
||
Unnumbered subheading.
|
||
@endDefmac
|
||
|
||
@c ---------------------------------------------------------------------
|
||
|
||
@node Highlighting in ms, Lists in ms, Headings in ms, ms Body Text
|
||
@subsubsection Highlighting
|
||
@cindex @code{ms} macros, highlighting
|
||
|
||
The @file{ms} macros provide a variety of methods to highlight
|
||
or emphasize text:
|
||
|
||
@Defmac {B, [@Var{txt} [@Var{post} [@Var{pre}]]], ms}
|
||
Sets its first argument in @strong{bold type}.
|
||
If you specify a second argument, @code{groff} prints it in the
|
||
previous font after the bold text, with no intervening space
|
||
(this allows you to set punctuation after the highlighted text
|
||
without highlighting the punctuation).
|
||
Similarly, it prints the third argument (if any) in the previous
|
||
font @strong{before} the first argument.
|
||
For example,
|
||
|
||
@Example
|
||
.B foo ) (
|
||
@endExample
|
||
|
||
prints (@strong{foo}).
|
||
|
||
If you give this macro no arguments, @code{groff}
|
||
prints all text following in bold until
|
||
the next highlighting, paragraph, or heading macro.
|
||
@endDefmac
|
||
|
||
@Defmac {R, [@Var{txt} [@Var{post} [@Var{pre}]]], ms}
|
||
Sets its first argument in roman (or regular) type.
|
||
It operates similarly to the @code{B}@w{ }macro otherwise.
|
||
@endDefmac
|
||
|
||
@Defmac {I, [@Var{txt} [@Var{post} [@Var{pre}]]], ms}
|
||
Sets its first argument in @emph{italic type}.
|
||
It operates similarly to the @code{B}@w{ }macro otherwise.
|
||
@endDefmac
|
||
|
||
@Defmac {CW, [@Var{txt} [@Var{post} [@Var{pre}]]], ms}
|
||
Sets its first argument in a @code{constant width face}.
|
||
It operates similarly to the @code{B}@w{ }macro otherwise.
|
||
@endDefmac
|
||
|
||
@Defmac {BI, [@Var{txt} [@Var{post} [@Var{pre}]]], ms}
|
||
Sets its first argument in bold italic type.
|
||
It operates similarly to the @code{B}@w{ }macro otherwise.
|
||
@endDefmac
|
||
|
||
@Defmac {BX, [@Var{txt}], ms}
|
||
Prints its argument and draws a box around it.
|
||
If you want to box a string that contains spaces,
|
||
use a digit-width space (@code{\0}).
|
||
@endDefmac
|
||
|
||
@Defmac {UL, [@Var{txt} [@Var{post}]], ms}
|
||
Prints its first argument with an underline.
|
||
If you specify a second argument, @code{groff}
|
||
prints it in the previous font after
|
||
the underlined text, with no intervening space.
|
||
@endDefmac
|
||
|
||
@Defmac {LG, , ms}
|
||
Prints all text following in larger type
|
||
(two points larger than the current point size) until
|
||
the next font size, highlighting, paragraph, or heading macro.
|
||
You can specify this macro multiple times
|
||
to enlarge the point size as needed.
|
||
@endDefmac
|
||
|
||
@Defmac {SM, , ms}
|
||
Prints all text following in smaller type
|
||
(two points smaller than the current point size) until
|
||
the next type size, highlighting, paragraph, or heading macro.
|
||
You can specify this macro multiple times
|
||
to reduce the point size as needed.
|
||
@endDefmac
|
||
|
||
@Defmac {NL, , ms}
|
||
Prints all text following in the normal point size
|
||
(that is, the value of the @code{PS} register).
|
||
@endDefmac
|
||
|
||
@c ---------------------------------------------------------------------
|
||
|
||
@node Lists in ms, Indents in ms, Highlighting in ms, ms Body Text
|
||
@subsubsection Lists
|
||
@cindex @code{ms} macros, lists
|
||
|
||
The @code{.IP} macro handles duties for all lists.
|
||
|
||
@Defmac {IP, [@Var{marker} [@Var{width}]], ms}
|
||
The @var{marker} is usually a bullet glyph (@code{\[bu]})
|
||
for unordered lists, a number (or auto-incrementing number
|
||
register) for numbered lists, or a word or phrase for indented
|
||
(glossary-style) lists.
|
||
|
||
The @var{width} specifies the indent for the body of each list item;
|
||
its default unit is @samp{n}.
|
||
Once specified, the indent remains the same for all
|
||
list items in the document until specified again.
|
||
@endDefmac
|
||
|
||
The following is an example of a bulleted list.
|
||
@cindex example markup, bulleted list [@code{ms}]
|
||
@cindex bulleted list, example markup [@code{ms}]
|
||
|
||
@Example
|
||
A bulleted list:
|
||
.IP \[bu] 2
|
||
lawyers
|
||
.IP \[bu]
|
||
guns
|
||
.IP \[bu]
|
||
money
|
||
@endExample
|
||
|
||
Produces:
|
||
|
||
@Example
|
||
A bulleted list:
|
||
|
||
o lawyers
|
||
|
||
o guns
|
||
|
||
o money
|
||
@endExample
|
||
|
||
@sp 1
|
||
|
||
The following is an example of a numbered list.
|
||
@cindex example markup, numbered list [@code{ms}]
|
||
@cindex numbered list, example markup [@code{ms}]
|
||
|
||
@Example
|
||
.nr step 1 1
|
||
A numbered list:
|
||
.IP \n[step] 3
|
||
lawyers
|
||
.IP \n+[step]
|
||
guns
|
||
.IP \n+[step]
|
||
money
|
||
@endExample
|
||
|
||
Produces:
|
||
|
||
@Example
|
||
A numbered list:
|
||
|
||
1. lawyers
|
||
|
||
2. guns
|
||
|
||
3. money
|
||
@endExample
|
||
|
||
Note the use of the auto-incrementing number
|
||
register in this example.
|
||
|
||
@sp 1
|
||
The following is an example of a glossary-style list.
|
||
@cindex example markup, glossary-style list [@code{ms}]
|
||
@cindex glossary-style list, example markup [@code{ms}]
|
||
|
||
@Example
|
||
A glossary-style list:
|
||
.IP lawyers 0.4i
|
||
Two or more attorneys.
|
||
.IP guns
|
||
Firearms, preferably
|
||
large-caliber.
|
||
.IP money
|
||
Gotta pay for those
|
||
lawyers and guns!
|
||
@endExample
|
||
|
||
Produces:
|
||
|
||
@Example
|
||
A glossary-style list:
|
||
|
||
lawyers
|
||
Two or more attorneys.
|
||
|
||
guns Firearms, preferably large-caliber.
|
||
|
||
money
|
||
Gotta pay for those lawyers and guns!
|
||
@endExample
|
||
|
||
In the last example, the @code{IP} macro places the definition
|
||
on the same line as the term if it has enough space; otherwise,
|
||
it breaks to the next line and starts the definition below the
|
||
term.
|
||
This may or may not be the effect you want, especially if some
|
||
of the definitions break and some do not.
|
||
The following examples show two possible ways to force a break.
|
||
|
||
The first workaround uses the @code{br}
|
||
request to force a break after printing the term or label.
|
||
|
||
@Example
|
||
@cartouche
|
||
A glossary-style list:
|
||
.IP lawyers 0.4i
|
||
Two or more attorneys.
|
||
.IP guns
|
||
.br
|
||
Firearms, preferably large-caliber.
|
||
.IP money
|
||
Gotta pay for those lawyers and guns!
|
||
@end cartouche
|
||
@endExample
|
||
|
||
@sp 1
|
||
The second workaround uses the @code{\p} escape to force the break.
|
||
Note the space following the escape; this is important.
|
||
If you omit the space, @code{groff} prints the first word on
|
||
the same line as the term or label (if it fits) @strong{then}
|
||
breaks the line.
|
||
|
||
@Example
|
||
@cartouche
|
||
A glossary-style list:
|
||
.IP lawyers 0.4i
|
||
Two or more attorneys.
|
||
.IP guns
|
||
\p Firearms, preferably large-caliber.
|
||
.IP money
|
||
Gotta pay for those lawyers and guns!
|
||
@end cartouche
|
||
@endExample
|
||
|
||
@sp 1
|
||
To set nested lists, use the @code{RS} and @code{RE} macros.
|
||
@xref{Indents in ms}, for more information.
|
||
@cindex @code{ms} macros, nested lists
|
||
@cindex nested lists [@code{ms}]
|
||
|
||
For example:
|
||
|
||
@Example
|
||
@cartouche
|
||
.IP \[bu] 2
|
||
Lawyers:
|
||
.RS
|
||
.IP \[bu]
|
||
Dewey,
|
||
.IP \[bu]
|
||
Cheatham,
|
||
.IP \[bu]
|
||
and Howe.
|
||
.RE
|
||
.IP \[bu]
|
||
Guns
|
||
@end cartouche
|
||
@endExample
|
||
|
||
Produces:
|
||
|
||
@Example
|
||
o Lawyers:
|
||
|
||
o Dewey,
|
||
|
||
o Cheatham,
|
||
|
||
o and Howe.
|
||
|
||
o Guns
|
||
@endExample
|
||
|
||
@c ---------------------------------------------------------------------
|
||
|
||
@node Indents in ms, Tabstops in ms, Lists in ms, ms Body Text
|
||
@subsubsection Indents
|
||
|
||
In many situations,
|
||
you may need to indent a section of text
|
||
while still wrapping and filling.
|
||
@xref{Lists in ms},
|
||
for an example of nested lists.
|
||
|
||
@DefmacList {RS, , ms}
|
||
@DefmacListEnd {RE, , ms}
|
||
These macros begin and end an indented section.
|
||
The @code{PI} register controls the amount of indent,
|
||
allowing the indented text to line up under hanging
|
||
and indented paragraphs.
|
||
@endDefmac
|
||
|
||
@xref{ms Displays and Keeps},
|
||
for macros to indent and turn off filling.
|
||
|
||
@c ---------------------------------------------------------------------
|
||
|
||
@node Tabstops in ms, ms Displays and Keeps, Indents in ms, ms Body Text
|
||
@subsubsection Tab Stops
|
||
|
||
Use the @code{ta} request to define tab stops as needed.
|
||
@xref{Tabs and Fields}.
|
||
|
||
@Defmac{TA, , ms}
|
||
Use this macro to reset the tab stops to the default for @file{ms}
|
||
(every 5n).
|
||
You can redefine the @code{TA} macro to create a different set
|
||
of default tab stops.
|
||
@endDefmac
|
||
|
||
@c ---------------------------------------------------------------------
|
||
|
||
@node ms Displays and Keeps, ms Insertions, Tabstops in ms, ms Body Text
|
||
@subsubsection Displays and keeps
|
||
@cindex @code{ms} macros, displays
|
||
@cindex @code{ms} macros, keeps
|
||
@cindex keeps [@code{ms}]
|
||
@cindex displays [@code{ms}]
|
||
|
||
Use displays to show text-based examples or figures
|
||
(such as code listings).
|
||
|
||
Displays turn off filling, so lines of code are displayed
|
||
as-is without inserting @code{br} requests in between each line.
|
||
Displays can be @dfn{kept} on a single page, or allowed
|
||
to break across pages.
|
||
|
||
@DefmacList {DS, @t{L}, ms}
|
||
@DefmacItem {LD, , ms}
|
||
@DefmacListEnd {DE, , ms}
|
||
Left-justified display.
|
||
The @samp{.DS L} call generates a page break, if necessary,
|
||
to keep the entire display on one page.
|
||
The @code{LD} macro allows the display to break across pages.
|
||
The @code{DE} macro ends the display.
|
||
@endDefmac
|
||
|
||
@DefmacList {DS, @t{I}, ms}
|
||
@DefmacItem {ID, , ms}
|
||
@DefmacListEnd {DE, , ms}
|
||
Indents the display as defined by the @code{DI} register.
|
||
The @samp{.DS I} call generates a page break, if necessary,
|
||
to keep the entire display on one page.
|
||
The @code{ID} macro allows the display to break across pages.
|
||
The @code{DE} macro ends the display.
|
||
@endDefmac
|
||
|
||
@DefmacList {DS, @t{B}, ms}
|
||
@DefmacItem {BD, , ms}
|
||
@DefmacListEnd {DE, , ms}
|
||
Sets a block-centered display: the entire display is left-justified,
|
||
but indented so that the longest line in the display is centered
|
||
on the page.
|
||
The @samp{.DS B} call generates a page break, if necessary,
|
||
to keep the entire display on one page.
|
||
The @code{BD} macro allows the display to break across pages.
|
||
The @code{DE} macro ends the display.
|
||
@endDefmac
|
||
|
||
@DefmacList {DS, @t{C}, ms}
|
||
@DefmacItem {CD, , ms}
|
||
@DefmacListEnd {DE, , ms}
|
||
Sets a centered display: each line in the display is centered.
|
||
The @samp{.DS C} call generates a page break, if necessary,
|
||
to keep the entire display on one page.
|
||
The @code{CD} macro allows the display to break across pages.
|
||
The @code{DE} macro ends the display.
|
||
@endDefmac
|
||
|
||
@DefmacList {DS, @t{R}, ms}
|
||
@DefmacItem {RD, , ms}
|
||
@DefmacListEnd {DE, , ms}
|
||
Right-justifies each line in the display.
|
||
The @samp{.DS R} call generates a page break, if necessary,
|
||
to keep the entire display on one page.
|
||
The @code{RD} macro allows the display to break across pages.
|
||
The @code{DE} macro ends the display.
|
||
@endDefmac
|
||
|
||
@sp 1
|
||
On occasion, you may want to @dfn{keep} other text together on a page.
|
||
For example, you may want to keep two paragraphs together, or
|
||
a paragraph that refers to a table (or list, or other item)
|
||
immediately following.
|
||
The @file{ms} macros provide the @code{KS} and @code{KE}
|
||
macros for this purpose.
|
||
|
||
@DefmacList {KS, , ms}
|
||
@DefmacListEnd {KE, , ms}
|
||
The @code{KS} macro begins a block of text to be kept on a
|
||
single page, and the @code{KE} macro ends the block.
|
||
@endDefmac
|
||
|
||
@DefmacList {KF, , ms}
|
||
@DefmacListEnd {KE, , ms}
|
||
Specifies a @dfn{floating keep};
|
||
if the keep cannot fit on the current page, @code{groff}
|
||
holds the contents of the keep and allows text following
|
||
the keep (in the source file) to fill in the remainder of
|
||
the current page.
|
||
When the page breaks, whether by an explicit @code{bp}
|
||
request or by reaching the end of the page, @code{groff}
|
||
prints the floating keep at the top of the new page.
|
||
This is useful for printing large graphics or tables
|
||
that do not need to appear exactly where specified.
|
||
@endDefmac
|
||
|
||
You can also use the @code{ne} request to force a page break if
|
||
there is not enough vertical space remaining on the page.
|
||
|
||
@sp 1
|
||
Use the following macros to draw a box around a section of
|
||
text (such as a display).
|
||
|
||
@DefmacList {B1, , ms}
|
||
@DefmacListEnd {B2, , ms}
|
||
Marks the beginning and ending of text that is to have a
|
||
box drawn around it.
|
||
The @code{B1} macro begins the box; the @code{B2} macro ends it.
|
||
Text in the box is automatically placed in a diversion (keep).
|
||
@endDefmac
|
||
|
||
@c ---------------------------------------------------------------------
|
||
|
||
@node ms Insertions, Example multi-page table, ms Displays and Keeps, ms Body Text
|
||
@subsubsection Tables, figures, equations, and references
|
||
@cindex @code{ms} macros, tables
|
||
@cindex @code{ms} macros, figures
|
||
@cindex @code{ms} macros, equations
|
||
@cindex @code{ms} macros, references
|
||
@cindex tables [@code{ms}]
|
||
@cindex figures [@code{ms}]
|
||
@cindex equations [@code{ms}]
|
||
@cindex references [@code{ms}]
|
||
|
||
The @file{ms} macros support the standard
|
||
@code{groff} preprocessors:
|
||
@code{tbl}, @code{pic}, @code{eqn}, and @code{refer}.
|
||
@pindex tbl
|
||
@pindex pic
|
||
@pindex eqn
|
||
@pindex refer
|
||
You mark text meant for preprocessors by enclosing it
|
||
in pairs of tags as follows.
|
||
|
||
@DefmacList {TS, [@code{H}], ms}
|
||
@DefmacListEnd {TE, , ms}
|
||
Denotes a table, to be processed by the @code{tbl} preprocessor.
|
||
The optional argument@w{ }@code{H} to @code{TS} instructs @code{groff}
|
||
to create a running header with the information
|
||
up to the @code{TH} macro.
|
||
@code{groff} prints the header at the beginning of the
|
||
table; if the table runs onto another page, @code{groff}
|
||
prints the header on the next page as well.
|
||
@endDefmac
|
||
|
||
@DefmacList {PS, , ms}
|
||
@DefmacListEnd {PE, , ms}
|
||
Denotes a graphic, to be processed by the @code{pic} preprocessor.
|
||
You can create a @code{pic} file by hand, using the @acronym{AT&T}
|
||
@code{pic} manual available on the Web as a reference, or by using
|
||
a graphics program such as @code{xfig}.
|
||
@endDefmac
|
||
|
||
@DefmacList {EQ, [@Var{align}], ms}
|
||
@DefmacListEnd {EN, , ms}
|
||
Denotes an equation, to be processed by the @code{eqn} preprocessor.
|
||
The optional @var{align} argument can be @code{C}, @code{L}, or@w{
|
||
}@code{I} to center (the default), left-justify, or indent the equation.
|
||
@endDefmac
|
||
|
||
@DefmacList {[, , ms}
|
||
@DefmacListEnd {], , ms}
|
||
Denotes a reference, to be processed by the @code{refer} preprocessor.
|
||
The @acronym{GNU} @cite{refer(1)} man page provides a comprehensive
|
||
reference to the preprocessor and the format of the bibliographic
|
||
database.
|
||
@endDefmac
|
||
|
||
@menu
|
||
* Example multi-page table::
|
||
@end menu
|
||
|
||
@c ---------------------------------------------------------------------
|
||
|
||
@node Example multi-page table, ms Footnotes, ms Insertions, ms Body Text
|
||
@subsubsection An example multi-page table
|
||
@cindex example markup, multi-page table [@code{ms}]
|
||
@cindex multi-page table, example markup [@code{ms}]
|
||
|
||
The following is an example of how to set up a
|
||
table that may print across two or more pages.
|
||
|
||
@Example
|
||
@cartouche
|
||
.TS H
|
||
allbox expand;
|
||
cb | cb .
|
||
Text ...of heading...
|
||
_
|
||
.TH
|
||
.T&
|
||
l | l .
|
||
... the rest of the table follows...
|
||
.CW
|
||
.TE
|
||
@end cartouche
|
||
@endExample
|
||
|
||
@c ---------------------------------------------------------------------
|
||
|
||
@node ms Footnotes, , Example multi-page table, ms Body Text
|
||
@subsubsection Footnotes
|
||
@cindex @code{ms} macros, footnotes
|
||
@cindex footnotes [@code{ms}]
|
||
|
||
The @file{ms} macro package has a flexible footnote system.
|
||
You can specify either numbered footnotes or symbolic footnotes
|
||
(that is, using a marker such as a dagger symbol).
|
||
|
||
@Defstr {*, ms}
|
||
Specifies the location of a numbered footnote marker in the text.
|
||
@endDefesc
|
||
|
||
@DefmacList {FS, , ms}
|
||
@DefmacListEnd {FE, , ms}
|
||
Specifies the text of the footnote.
|
||
The default action is to create a numbered footnote;
|
||
you can create a symbolic footnote by specifying
|
||
a @dfn{mark} glyph
|
||
(such as @code{\[dg]} for the dagger glyph)
|
||
in the body text and as an argument to the @code{FS} macro,
|
||
followed by the text of the footnote
|
||
and the @code{FE} macro.
|
||
@endDefmac
|
||
|
||
You can control how @code{groff}
|
||
prints footnote numbers by changing the value of the
|
||
@code{FF} register. @xref{ms Document Control Registers}.
|
||
|
||
@c ---------------------------------------------------------------------
|
||
|
||
@node ms Page Layout, Differences from AT&T ms, ms Body Text, ms
|
||
@subsection Page layout
|
||
@cindex @code{ms} macros, page layout
|
||
@cindex page layout [@code{ms}]
|
||
|
||
The default output from the @file{ms}
|
||
macros provides a minimalist page layout:
|
||
it prints a single column, with the page number centered at the top
|
||
of each page.
|
||
It prints no footers.
|
||
|
||
You can change the layout by setting
|
||
the proper number registers and strings.
|
||
|
||
@menu
|
||
* ms Headers and Footers::
|
||
* ms Margins::
|
||
* ms Multiple Columns::
|
||
* ms TOC::
|
||
* ms Strings and Special Characters::
|
||
@end menu
|
||
|
||
@c ---------------------------------------------------------------------
|
||
|
||
@node ms Headers and Footers, ms Margins, ms Page Layout, ms Page Layout
|
||
@subsubsection Headers and footers
|
||
@cindex @code{ms} macros, headers
|
||
@cindex @code{ms} macros, footers
|
||
@cindex headers [@code{ms}]
|
||
@cindex footers [@code{ms}]
|
||
|
||
For documents that do not distinguish between odd and even pages,
|
||
set the following strings:
|
||
|
||
@DefstrList {LH, ms}
|
||
@DefstrItem {CH, ms}
|
||
@DefstrListEnd {RH, ms}
|
||
Sets the left, center, and right headers.
|
||
@endDefstr
|
||
|
||
@DefstrList {LF, ms}
|
||
@DefstrItem {CF, ms}
|
||
@DefstrListEnd {RF, ms}
|
||
Sets the left, center, and right footers.
|
||
@endDefstr
|
||
|
||
@sp 1
|
||
For documents that need different information printed in the
|
||
even and odd pages, use the following macros:
|
||
|
||
@DefmacList {OH, @t{'}@Var{left}@t{'}@Var{center}@t{'}@Var{right}@t{'}, ms}
|
||
@DefmacItem {EH, @t{'}@Var{left}@t{'}@Var{center}@t{'}@Var{right}@t{'}, ms}
|
||
@DefmacItem {OF, @t{'}@Var{left}@t{'}@Var{center}@t{'}@Var{right}@t{'}, ms}
|
||
@DefmacListEnd {EF, @t{'}@Var{left}@t{'}@Var{center}@t{'}@Var{right}@t{'}, ms}
|
||
The @code{OH} and @code{EH} macros define headers for the odd and even pages;
|
||
the @code{OF} and @code{EF} macros define footers for the odd and even pages.
|
||
This is more flexible than defining the individual strings.
|
||
|
||
You can replace the quote (@code{'}) marks with any character not
|
||
appearing in the header or footer text.
|
||
@endDefmac
|
||
|
||
@c ---------------------------------------------------------------------
|
||
|
||
@node ms Margins, ms Multiple Columns, ms Headers and Footers, ms Page Layout
|
||
@subsubsection Margins
|
||
@cindex @code{ms} macros, margins
|
||
|
||
You control margins using a set of number registers.
|
||
@xref{ms Document Control Registers}, for details.
|
||
|
||
@c ---------------------------------------------------------------------
|
||
|
||
@node ms Multiple Columns, ms TOC, ms Margins, ms Page Layout
|
||
@subsubsection Multiple columns
|
||
@cindex @code{ms} macros, multiple columns
|
||
@cindex multiple columns [@code{ms}]
|
||
|
||
The @file{ms} macros can set text in as many columns as will
|
||
reasonably fit on the page.
|
||
The following macros are available;
|
||
all of them force a page break if a multi-column mode is already set.
|
||
However, if the current mode is single-column, starting a multi-column
|
||
mode does @strong{not} force a page break.
|
||
|
||
@Defmac {1C, , ms}
|
||
Single-column mode.
|
||
@endDefmac
|
||
|
||
@Defmac {2C, , ms}
|
||
Two-column mode.
|
||
@endDefmac
|
||
|
||
@Defmac {MC, [@Var{width} [@Var{gutter}]], ms}
|
||
Multi-column mode.
|
||
If you specify no arguments, it is equivalent to the
|
||
@code{2C} macro.
|
||
Otherwise, @var{width} is the width of each column and
|
||
@var{gutter} is the space between columns.
|
||
The @code{MINGW} number register controls the default gutter width.
|
||
@endDefmac
|
||
|
||
@c ---------------------------------------------------------------------
|
||
|
||
@node ms TOC, ms Strings and Special Characters, ms Multiple Columns, ms Page Layout
|
||
@subsubsection Creating a table of contents
|
||
@cindex @code{ms} macros, creating table of contents
|
||
@cindex table of contents, creating [@code{ms}]
|
||
|
||
The facilities in the @file{ms} macro package for creating
|
||
a table of contents are semi-automated at best.
|
||
Assuming that you want the table of contents to consist of
|
||
the document's headings, you need to repeat those headings
|
||
wrapped in @code{XS} and @code{XE} macros.
|
||
|
||
@DefmacList {XS, [@Var{page}], ms}
|
||
@DefmacItem {XA, [@Var{page}], ms}
|
||
@DefmacListEnd {XE, , ms}
|
||
These macros define a table of contents
|
||
or an individual entry in the table of contents,
|
||
depending on their use.
|
||
The macros are very simple; they cannot indent a heading based on its level.
|
||
The easiest way to work around this is to add tabs
|
||
to the table of contents string.
|
||
The following is an example:
|
||
|
||
@Example
|
||
@cartouche
|
||
.NH 1
|
||
Introduction
|
||
.XS
|
||
Introduction
|
||
.XE
|
||
.LP
|
||
...
|
||
.CW
|
||
.NH 2
|
||
Methodology
|
||
.XS
|
||
Methodology
|
||
.XE
|
||
.LP
|
||
...
|
||
@end cartouche
|
||
@endExample
|
||
|
||
You can manually create a table of contents
|
||
by beginning with the @code{XS} macro for the first entry,
|
||
specifying the page number for that entry as the argument to @code{XS}.
|
||
Add subsequent entries using the @code{XA} macro,
|
||
specifying the page number for that entry as the argument to @code{XA}.
|
||
The following is an example:
|
||
|
||
@Example
|
||
@cartouche
|
||
.XS 1
|
||
Introduction
|
||
.XA 2
|
||
A Brief History of the Universe
|
||
.XA 729
|
||
Details of Galactic Formation
|
||
...
|
||
.XE
|
||
@end cartouche
|
||
@endExample
|
||
@endDefmac
|
||
|
||
@Defmac {TC, [@code{no}], ms}
|
||
Prints the table of contents on a new page,
|
||
setting the page number to@w{ }@strong{i} (Roman numeral one).
|
||
You should usually place this macro at the end of the
|
||
file, since @code{groff} is a single-pass formatter and
|
||
can only print what has been collected up to the point
|
||
that the @code{TC} macro appears.
|
||
|
||
The optional argument @code{no} suppresses printing
|
||
the title specified by the string register @code{TOC}.
|
||
@endDefmac
|
||
|
||
@Defmac{PX, [@code{no}], ms}
|
||
Prints the table of contents on a new page,
|
||
using the current page numbering sequence.
|
||
Use this macro to print a manually-generated table of contents
|
||
at the beginning of your document.
|
||
|
||
The optional argument @code{no} suppresses printing
|
||
the title specified by the string register @code{TOC}.
|
||
@endDefmac
|
||
|
||
The @cite{Groff and Friends HOWTO}
|
||
includes a @code{sed} script that automatically inserts
|
||
@code{XS} and @code{XE} macro entries after each heading in a document.
|
||
|
||
Altering the @code{NH} macro to automatically build the table
|
||
of contents is perhaps initially more difficult, but would save
|
||
a great deal of time in the long run if you use @file{ms} regularly.
|
||
|
||
@c ---------------------------------------------------------------------
|
||
|
||
@node ms Strings and Special Characters, , ms TOC, ms Page Layout
|
||
@subsubsection Strings and Special Characters
|
||
@cindex @code{ms} macros, strings
|
||
@cindex @code{ms} macros, special characters
|
||
@cindex @code{ms} macros, accent marks
|
||
@cindex accent marks [@code{ms}]
|
||
@cindex special characters [@code{ms}]
|
||
@cindex strings [@code{ms}]
|
||
|
||
The @file{ms} macros provide the following predefined strings.
|
||
You can change the string definitions to help in creating
|
||
documents in languages other than English.
|
||
|
||
@Defstr {REFERENCES, ms}
|
||
Contains the string printed at the beginning of the
|
||
references (bibliography) page.
|
||
The default is @samp{References}.
|
||
@endDefstr
|
||
|
||
@Defstr {ABSTRACT, ms}
|
||
Contains the string printed at the beginning of the abstract.
|
||
The default is @samp{ABSTRACT}.
|
||
@endDefstr
|
||
|
||
@Defstr {TOC, ms}
|
||
Contains the string printed at the beginning of the table of contents.
|
||
@endDefstr
|
||
|
||
@DefstrList {MONTH1, ms}
|
||
@DefstrItem {MONTH2, ms}
|
||
@DefstrItem {MONTH3, ms}
|
||
@DefstrItem {MONTH4, ms}
|
||
@DefstrItem {MONTH5, ms}
|
||
@DefstrItem {MONTH6, ms}
|
||
@DefstrItem {MONTH7, ms}
|
||
@DefstrItem {MONTH8, ms}
|
||
@DefstrItem {MONTH9, ms}
|
||
@DefstrItem {MONTH10, ms}
|
||
@DefstrItem {MONTH11, ms}
|
||
@DefstrListEnd {MONTH12, ms}
|
||
Prints the full name of the month in dates.
|
||
The default is @samp{January}, @samp{February}, etc.
|
||
@endDefstr
|
||
|
||
The following special characters are available@footnote{For an
|
||
explanation what special characters are see @ref{Special Characters}.}:
|
||
|
||
@Defstr {-, ms}
|
||
Prints an em dash.
|
||
@endDefstr
|
||
|
||
@DefstrList {*Q, ms}
|
||
@DefstrListEnd {*U, ms}
|
||
Prints typographer's quotes in troff,
|
||
plain quotes in nroff.
|
||
@code{*Q} is the left quote and @code{*U} is the right quote.
|
||
@endDefstr
|
||
|
||
Improved accent marks are available in the @file{ms} macros.
|
||
|
||
@Defmac {AM, , ms}
|
||
Specify this macro at the beginning of your document
|
||
to enable extended accent marks and special characters.
|
||
This is a Berkeley extension.
|
||
|
||
To use the accent marks, place them @strong{after}
|
||
the character being accented.
|
||
@endDefmac
|
||
|
||
The following accent marks are available
|
||
after invoking the @code{AM} macro:
|
||
|
||
@Defstr {\', ms}
|
||
Acute accent.
|
||
@endDefstr
|
||
|
||
@Defstr {\`, ms}
|
||
Grave accent.
|
||
@endDefstr
|
||
|
||
@Defstr {^, ms}
|
||
Circumflex.
|
||
@endDefstr
|
||
|
||
@Defstr {\,, ms}
|
||
Cedilla.
|
||
@endDefstr
|
||
|
||
@Defstr {~, ms}
|
||
Tilde.
|
||
@endDefstr
|
||
|
||
@deffn String @t{\*[:]}
|
||
@ifnotinfo
|
||
@stindex : @r{[}ms@r{]}
|
||
@end ifnotinfo
|
||
@ifinfo
|
||
@stindex @r{<colon>} @r{[}ms@r{]}
|
||
@end ifinfo
|
||
Umlaut.
|
||
@end deffn
|
||
|
||
@Defstr {v, ms}
|
||
Hacek.
|
||
@endDefstr
|
||
|
||
@Defstr {_, ms}
|
||
Macron (overbar).
|
||
@endDefstr
|
||
|
||
@Defstr {., ms}
|
||
Underdot.
|
||
@endDefstr
|
||
|
||
@Defstr {o, ms}
|
||
Ring above.
|
||
@endDefstr
|
||
|
||
The following are standalone characters
|
||
available after invoking the @code{AM} macro:
|
||
|
||
@Defstr {?, ms}
|
||
Upside-down question mark.
|
||
@endDefstr
|
||
|
||
@Defstr {!, ms}
|
||
Upside-down exclamation point.
|
||
@endDefstr
|
||
|
||
@Defstr {8, ms}
|
||
German @ss{} ligature.
|
||
@endDefstr
|
||
|
||
@Defstr {3, ms}
|
||
Yogh.
|
||
@endDefstr
|
||
|
||
@Defstr {Th, ms}
|
||
Uppercase thorn.
|
||
@endDefstr
|
||
|
||
@Defstr {th, ms}
|
||
Lowercase thorn.
|
||
@endDefstr
|
||
|
||
@Defstr {D-, ms}
|
||
Uppercase eth.
|
||
@endDefstr
|
||
|
||
@Defstr {d-, ms}
|
||
Lowercase eth.
|
||
@endDefstr
|
||
|
||
@Defstr {q, ms}
|
||
Hooked o.
|
||
@endDefstr
|
||
|
||
@Defstr {ae, ms}
|
||
Lowercase @ae{} ligature.
|
||
@endDefstr
|
||
|
||
@Defstr {Ae, ms}
|
||
Uppercase @AE{} ligature.
|
||
@endDefstr
|
||
|
||
@c ---------------------------------------------------------------------
|
||
|
||
@node Differences from AT&T ms, , ms Page Layout, ms
|
||
@subsection Differences from @acronym{AT&T} @file{ms}
|
||
@cindex @code{ms} macros, differences from @acronym{AT&T}
|
||
@cindex @acronym{AT&T} @code{troff}, @code{ms} macro package differences
|
||
|
||
This section lists the (minor) differences between the
|
||
@code{groff -ms} macros and @acronym{AT&T}
|
||
@code{troff -ms} macros.
|
||
|
||
@menu
|
||
* Missing ms Macros::
|
||
* Additional ms Macros::
|
||
@end menu
|
||
|
||
@c ---------------------------------------------------------------------
|
||
|
||
@node Missing ms Macros, Additional ms Macros, Differences from AT&T ms, Differences from AT&T ms
|
||
@subsubsection @code{troff} macros not appearing in @code{groff}
|
||
|
||
Macros missing from @code{groff -ms}
|
||
are cover page macros specific to Bell Labs.
|
||
The macros known to be missing are:
|
||
|
||
@table @code
|
||
@item .TM
|
||
Technical memorandum; a cover sheet style
|
||
|
||
@item .IM
|
||
Internal memorandum; a cover sheet style
|
||
|
||
@item .MR
|
||
Memo for record; a cover sheet style
|
||
|
||
@item .MF
|
||
Memo for file; a cover sheet style
|
||
|
||
@item .EG
|
||
Engineer's notes; a cover sheet style
|
||
|
||
@item .TR
|
||
Computing Science Tech Report; a cover sheet style
|
||
|
||
@item .OK
|
||
Other keywords
|
||
|
||
@item .CS
|
||
Cover sheet information
|
||
|
||
@item .MH
|
||
A cover sheet macro
|
||
@end table
|
||
|
||
@c ---------------------------------------------------------------------
|
||
|
||
@node Additional ms Macros, , Missing ms Macros, Differences from AT&T ms
|
||
@subsubsection @code{groff} macros not appearing in @acronym{AT&T} @code{troff}
|
||
|
||
The @code{groff -ms} macros have a few minor extensions
|
||
compared to the @acronym{AT&T} @code{troff -ms} macros.
|
||
|
||
@Defmac {AM, , ms}
|
||
Improved accent marks.
|
||
@xref{ms Strings and Special Characters}, for details.
|
||
@endDefmac
|
||
|
||
@Defmac {DS, @t{I}, ms}
|
||
Indented display.
|
||
The default behavior of @acronym{AT&T} @code{troff -ms}
|
||
was to indent; the @code{groff} default prints displays
|
||
flush left with the body text.
|
||
@endDefmac
|
||
|
||
@Defmac {CW, , ms}
|
||
Print text in @code{constant width} (Courier) font.
|
||
@endDefmac
|
||
|
||
@Defmac {IX, , ms}
|
||
Indexing term (printed on standard error).
|
||
You can write a script to capture and process an index
|
||
generated in this manner.
|
||
@endDefmac
|
||
|
||
@sp 1
|
||
The following additional number registers
|
||
appear in @code{groff -ms}:
|
||
|
||
@Defmpreg {MINGW, ms}
|
||
Specifies a minimum space
|
||
between columns (for multi-column output); this takes the
|
||
place of the @code{GW} register that was documented but apparently
|
||
not implemented in @acronym{AT&T} @code{troff}.
|
||
@endDefmpreg
|
||
|
||
@sp 1
|
||
Several new string registers are available as well.
|
||
You can change these to handle (for example) the local language.
|
||
@xref{ms Strings and Special Characters}, for details.
|
||
|
||
|
||
@c =====================================================================
|
||
|
||
@node me, mm, ms, Macro Packages
|
||
@section @file{me}
|
||
@cindex @code{me} macro package
|
||
|
||
@c XXX documentation
|
||
@c XXX this is a placeholder until we get stuff knocked into shape
|
||
See the @file{meintro.me} and @file{meref.me} documents in
|
||
groff's @file{doc} directory.
|
||
|
||
|
||
@c =====================================================================
|
||
|
||
@node mm, , me, Macro Packages
|
||
@section @file{mm}
|
||
@cindex @code{mm} macro package
|
||
|
||
@c XXX documentation
|
||
@c XXX this is a placeholder until we get stuff knocked into shape
|
||
See the @cite{groff_mm(7)} man page (type @command{man groff_mm} at
|
||
the command line).
|
||
|
||
|
||
@c =====================================================================
|
||
@c =====================================================================
|
||
|
||
@node gtroff Reference, Preprocessors, Macro Packages, Top
|
||
@chapter @code{gtroff} Reference
|
||
@cindex reference, @code{gtroff}
|
||
@cindex @code{gtroff}, reference
|
||
|
||
This chapter covers @strong{all} of the facilities of @code{gtroff}.
|
||
Users of macro packages may skip it if not interested in details.
|
||
|
||
|
||
@menu
|
||
* Text::
|
||
* Input Conventions::
|
||
* Measurements::
|
||
* Expressions::
|
||
* Identifiers::
|
||
* Embedded Commands::
|
||
* Registers::
|
||
* Manipulating Filling and Adjusting::
|
||
* Manipulating Hyphenation::
|
||
* Manipulating Spacing::
|
||
* Tabs and Fields::
|
||
* Character Translations::
|
||
* Troff and Nroff Mode::
|
||
* Line Layout::
|
||
* Line Control::
|
||
* Page Layout::
|
||
* Page Control::
|
||
* Fonts::
|
||
* Sizes::
|
||
* Strings::
|
||
* Conditionals and Loops::
|
||
* Writing Macros::
|
||
* Page Motions::
|
||
* Drawing Requests::
|
||
* Traps::
|
||
* Diversions::
|
||
* Environments::
|
||
* Suppressing output::
|
||
* Colors::
|
||
* I/O::
|
||
* Postprocessor Access::
|
||
* Miscellaneous::
|
||
* Gtroff Internals::
|
||
* Debugging::
|
||
* Implementation Differences::
|
||
@end menu
|
||
|
||
|
||
@c =====================================================================
|
||
|
||
@node Text, Input Conventions, gtroff Reference, gtroff Reference
|
||
@section Text
|
||
@cindex text, @code{gtroff} processing
|
||
|
||
@code{gtroff} input files contain text with control commands
|
||
interspersed throughout. But, even without control codes, @code{gtroff}
|
||
still does several things with the input text:
|
||
|
||
@itemize @bullet
|
||
@item
|
||
filling and adjusting
|
||
|
||
@item
|
||
adding additional space after sentences
|
||
|
||
@item
|
||
hyphenating
|
||
|
||
@item
|
||
inserting implicit line breaks
|
||
@end itemize
|
||
|
||
@menu
|
||
* Filling and Adjusting::
|
||
* Hyphenation::
|
||
* Sentences::
|
||
* Tab Stops::
|
||
* Implicit Line Breaks::
|
||
@end menu
|
||
|
||
@c ---------------------------------------------------------------------
|
||
|
||
@node Filling and Adjusting, Hyphenation, Text, Text
|
||
@subsection Filling and Adjusting
|
||
@cindex filling
|
||
@cindex adjusting
|
||
|
||
When @code{gtroff} reads text, it collects words from the input and fits
|
||
as many of them together on one output line as it can. This is known as
|
||
@dfn{filling}.
|
||
|
||
@cindex leading spaces
|
||
@cindex spaces, leading and trailing
|
||
@cindex extra spaces
|
||
@cindex trailing spaces
|
||
Once @code{gtroff} has a @dfn{filled} line, it tries to @dfn{adjust}
|
||
it. This means it widens 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 cause a @dfn{break} (breaks are
|
||
explained in @ref{Implicit Line Breaks}).
|
||
|
||
@xref{Manipulating Filling and Adjusting}.
|
||
|
||
@c ---------------------------------------------------------------------
|
||
|
||
@node Hyphenation, Sentences, Filling and Adjusting, Text
|
||
@subsection Hyphenation
|
||
@cindex hyphenation
|
||
|
||
Since the odds are not great for finding a set of words, for every
|
||
output line, which fit nicely on a line without inserting excessive
|
||
amounts of space between words, @code{gtroff} hyphenates words so
|
||
that it can justify lines without inserting 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 is added to the current filled line being output (with
|
||
an attached hyphen), and the other portion is added to the next
|
||
line to be filled.
|
||
|
||
@xref{Manipulating Hyphenation}.
|
||
|
||
@c ---------------------------------------------------------------------
|
||
|
||
@node Sentences, Tab Stops, Hyphenation, Text
|
||
@subsection Sentences
|
||
@cindex sentences
|
||
|
||
Although it is often debated, some typesetting rules say there should be
|
||
different amounts of space after various punctuation marks. For
|
||
example, the @cite{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.
|
||
|
||
@c XXX exact citation of Chicago manual
|
||
|
||
@cindex sentence space
|
||
@cindex space between sentences
|
||
@cindex french-spacing
|
||
@code{gtroff} does this by flagging certain characters (normally
|
||
@samp{!}, @samp{?}, and @samp{.}) as @dfn{end-of-sentence} characters.
|
||
When @code{gtroff} encounters one of these characters at the end of a
|
||
line, it appends a normal space followed by a @dfn{sentence space} in
|
||
the formatted output. (This justifies one of the conventions mentioned
|
||
in @ref{Input Conventions}.)
|
||
|
||
@cindex transparent characters
|
||
@cindex character, transparent
|
||
@cindex @code{dg} glyph, at end of sentence
|
||
@cindex @code{rq} glyph, at end of sentence
|
||
@cindex @code{"}, at end of sentence
|
||
@cindex @code{'}, at end of sentence
|
||
@cindex @code{)}, at end of sentence
|
||
@cindex @code{]}, at end of sentence
|
||
@cindex @code{*}, at end of sentence
|
||
In addition, the following characters and symbols are treated
|
||
transparently while handling end-of-sentence characters: @samp{"},
|
||
@samp{'}, @samp{)}, @samp{]}, @samp{*}, @code{\[dg]}, and @code{\[rq]}.
|
||
|
||
See the @code{cflags} request in @ref{Using Symbols}, for more details.
|
||
|
||
@cindex @code{\&}, at end of sentence
|
||
To prevent the insertion of extra space after an end-of-sentence
|
||
character (at the end of a line), append @code{\&}.
|
||
|
||
@c ---------------------------------------------------------------------
|
||
|
||
@node Tab Stops, Implicit Line Breaks, Sentences, Text
|
||
@subsection Tab Stops
|
||
@cindex tab stops
|
||
@cindex stops, tabulator
|
||
@cindex tab character
|
||
@cindex character, tabulator
|
||
|
||
@cindex @acronym{EBCDIC} encoding
|
||
@cindex encoding, @acronym{EBCDIC}
|
||
@code{gtroff} translates @dfn{tabulator characters}, also called
|
||
@dfn{tabs} (normally code point @acronym{ASCII} @code{0x09} or
|
||
@acronym{EBCDIC} @code{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 be made easily.
|
||
However, it can often be deceptive as the appearance (and width) of the
|
||
text on a terminal and the results from @code{gtroff} can vary greatly.
|
||
|
||
Also, a possible sticking point is that lines beginning with tab
|
||
characters are still filled, again producing unexpected results.
|
||
For example, the following input
|
||
|
||
@multitable {12345678} {12345678} {12345678} {12345678}
|
||
@item
|
||
@tab 1 @tab 2 @tab 3
|
||
@item
|
||
@tab @tab 4 @tab 5
|
||
@end multitable
|
||
|
||
@noindent
|
||
produces
|
||
|
||
@multitable {12345678} {12345678} {12345678} {12345678} {12345678} {12345678} {12345678}
|
||
@item
|
||
@tab 1 @tab 2 @tab 3 @tab @tab 4 @tab 5
|
||
@end multitable
|
||
|
||
@xref{Tabs and Fields}.
|
||
|
||
@c ---------------------------------------------------------------------
|
||
|
||
@node Implicit Line Breaks, , Tab Stops, Text
|
||
@subsection Implicit Line Breaks
|
||
@cindex implicit line breaks
|
||
@cindex implicit breaks of lines
|
||
@cindex line, implicit breaks
|
||
@cindex break, implicit
|
||
@cindex line break
|
||
|
||
An important concept in @code{gtroff} is the @dfn{break}. When a break
|
||
occurs, @code{gtroff} outputs the partially filled line
|
||
(unjustified), and resumes collecting and filling text on the next output
|
||
line.
|
||
|
||
@cindex blank line
|
||
@cindex empty line
|
||
@cindex line, blank
|
||
@cindex blank line macro (@code{blm})
|
||
There are several ways to cause a break in @code{gtroff}. A blank
|
||
line not only causes a break, but it also outputs a one-line vertical
|
||
space (effectively a blank line). Note that this behaviour can be
|
||
modified with the blank line macro request @code{blm}.
|
||
@xref{Blank Line Traps}.
|
||
|
||
@cindex fill mode
|
||
@cindex mode, fill
|
||
A line that begins with a space causes a break and the space is
|
||
output at the beginning of the next line. Note that this space isn't
|
||
adjusted, even in fill mode.
|
||
|
||
The end of file also causes a break -- otherwise the last line of
|
||
the document may vanish!
|
||
|
||
Certain requests also cause breaks, implicitly or explicitly. This is
|
||
discussed in @ref{Manipulating Filling and Adjusting}.
|
||
|
||
|
||
@c =====================================================================
|
||
|
||
@node Input Conventions, Measurements, Text, gtroff Reference
|
||
@section Input Conventions
|
||
@cindex input conventions
|
||
@cindex conventions for input
|
||
|
||
Since @code{gtroff} does filling automatically, it is traditional in
|
||
@code{groff} not to try and type things in as nicely formatted
|
||
paragraphs. These are some conventions commonly used when typing
|
||
@code{gtroff} text:
|
||
|
||
@itemize @bullet
|
||
@item
|
||
Break lines after punctuation, particularly at the end of a sentence
|
||
and in other logical places. Keep separate phrases on lines by
|
||
themselves, as entire phrases are often added or deleted when editing.
|
||
|
||
@item
|
||
Try to keep lines less than 40-60@w{ }characters, to allow space for
|
||
inserting more text.
|
||
|
||
@item
|
||
Do not try to do any formatting in a @acronym{WYSIWYG} manner (i.e.,
|
||
don't try using spaces to get proper indentation).
|
||
@end itemize
|
||
|
||
|
||
@c =====================================================================
|
||
|
||
@node Measurements, Expressions, Input Conventions, gtroff Reference
|
||
@section Measurements
|
||
@cindex measurements
|
||
|
||
@cindex units of measurement
|
||
@cindex basic unit (@code{u})
|
||
@cindex machine unit (@code{u})
|
||
@cindex measurement unit
|
||
@cindex @code{u} unit
|
||
@cindex unit, @code{u}
|
||
@code{gtroff} (like many other programs) requires numeric parameters to
|
||
specify various measurements. Most numeric parameters@footnote{those
|
||
that specify vertical or horizontal motion or a type size} may have a
|
||
@dfn{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 @code{gtroff}, to be a multiple of its
|
||
@dfn{basic unit}. So, whenever a different measurement unit is
|
||
specified @code{gtroff} converts this into its @dfn{basic units}. This
|
||
basic unit, represented by a @samp{u}, is a device dependent measurement
|
||
which is quite small, ranging from 1/75@dmn{th} to 1/72000@dmn{th} 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 @code{gtroff}.
|
||
|
||
@table @code
|
||
@item i
|
||
@cindex inch unit (@code{i})
|
||
@cindex @code{i} unit
|
||
@cindex unit, @code{i}
|
||
Inches. An antiquated measurement unit still in use in certain
|
||
backwards countries with incredibly low-cost computer equipment. One
|
||
inch is equal to@w{ }2.54@dmn{cm}.
|
||
|
||
@item c
|
||
@cindex centimeter unit (@code{c})
|
||
@cindex @code{c} unit
|
||
@cindex unit, @code{c}
|
||
Centimeters. One centimeter is equal to@w{ }0.3937@dmn{in}.
|
||
|
||
@item p
|
||
@cindex point unit (@code{p})
|
||
@cindex @code{p} unit
|
||
@cindex unit, @code{p}
|
||
Points. This is a typesetter's measurement used for measure type size.
|
||
It is 72@w{ }points to an inch.
|
||
|
||
@item P
|
||
@cindex pica unit (@code{P})
|
||
@cindex @code{P} unit
|
||
@cindex unit, @code{P}
|
||
Pica. Another typesetting measurement. 6@w{ }Picas to an inch (and
|
||
12@w{ }points to a pica).
|
||
|
||
@item s
|
||
@itemx z
|
||
@cindex @code{s} unit
|
||
@cindex unit, @code{s}
|
||
@cindex @code{z} unit
|
||
@cindex unit, @code{z}
|
||
@xref{Fractional Type Sizes}, for a discussion of these units.
|
||
|
||
@item f
|
||
@cindex @code{f} unit
|
||
@cindex unit, @code{f}
|
||
Fractions. Value is 65536.
|
||
@xref{Colors}, for usage.
|
||
@end table
|
||
|
||
The other measurements understood by @code{gtroff} depend on
|
||
settings currently in effect in @code{gtroff}. These are very useful
|
||
for specifying measurements which should look proper with any size of
|
||
text.
|
||
|
||
@table @code
|
||
@item m
|
||
@cindex em unit (@code{m})
|
||
@cindex @code{m} unit
|
||
@cindex unit, @code{m}
|
||
Ems. This unit is equal to the current font size in points. So called
|
||
because it is @emph{approximately} the width of the letter@w{ }@samp{m}
|
||
in the current font.
|
||
|
||
@item n
|
||
@cindex en unit (@code{n})
|
||
@cindex @code{n} unit
|
||
@cindex unit, @code{n}
|
||
Ens. In @code{groff}, this is half of an em.
|
||
|
||
@item v
|
||
@cindex vertical space unit (@code{v})
|
||
@cindex space, vertical, unit (@code{v})
|
||
@cindex @code{v} unit
|
||
@cindex unit, @code{v}
|
||
Vertical space. This is equivalent to the current line spacing.
|
||
@xref{Sizes}, for more information about this.
|
||
|
||
@item M
|
||
@cindex @code{M} unit
|
||
@cindex unit, @code{M}
|
||
100ths of an em.
|
||
@end table
|
||
|
||
@menu
|
||
* Default Units::
|
||
@end menu
|
||
|
||
@c ---------------------------------------------------------------------
|
||
|
||
@node Default Units, , Measurements, Measurements
|
||
@subsection Default Units
|
||
@cindex default units
|
||
@cindex units, default
|
||
|
||
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@w{ }inches and their results:
|
||
|
||
@Example
|
||
3.5i @result{} 3.5i
|
||
7/2 @result{} 0i
|
||
7/2i @result{} 0i
|
||
(7 / 2)u @result{} 0i
|
||
7i/2 @result{} 0.1i
|
||
7i/2u @result{} 3.5i
|
||
@endExample
|
||
|
||
@noindent
|
||
Everything is converted to basic units first. In the above example it
|
||
is assumed that 1@dmn{i} equals@w{ }240@dmn{u}, and 1@dmn{m} equals@w{
|
||
}10@dmn{p} (thus 1@dmn{m} equals@w{ }33@dmn{u}). The value 7@dmn{i}/2
|
||
is first handled as 7@dmn{i}/2@dmn{m}, then converted to
|
||
1680@dmn{u}/66@dmn{u} which is 25@dmn{u}, and this is approximately
|
||
0.1@dmn{i}. As can be seen, a scaling indicator after a closing
|
||
parenthesis is simply ignored.
|
||
|
||
@cindex measurements, specifying safely
|
||
Thus, 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 @samp{u} as the unit for that value.
|
||
|
||
|
||
@c =====================================================================
|
||
|
||
@node Expressions, Identifiers, Measurements, gtroff Reference
|
||
@section Expressions
|
||
@cindex expressions
|
||
|
||
@code{gtroff} has most arithmetic operators common to other languages:
|
||
|
||
@itemize @bullet
|
||
@item
|
||
@cindex arithmetic operators
|
||
@cindex operators, arithmetic
|
||
@opindex +
|
||
@opindex -
|
||
@opindex /
|
||
@opindex *
|
||
@opindex %
|
||
Arithmetic: @samp{+} (addition), @samp{-} (subtraction), @samp{/}
|
||
(division), @samp{*} (multiplication), @samp{%} (modulo).
|
||
|
||
@code{gtroff} only provides integer arithmetic. The internal type used
|
||
for computing results is @samp{int}, which is usually a 32@dmn{bit}
|
||
signed integer.
|
||
|
||
@item
|
||
@cindex comparison operators
|
||
@cindex operators, comparison
|
||
@opindex <
|
||
@opindex >
|
||
@opindex >=
|
||
@opindex <=
|
||
@opindex =
|
||
@opindex ==
|
||
Comparison: @samp{<} (less than), @samp{>} (greater than), @samp{<=}
|
||
(less than or equal), @samp{>=} (greater than or equal), @samp{=}
|
||
(equal), @samp{==} (the same as @samp{=}).
|
||
|
||
@item
|
||
@cindex logical operators
|
||
@cindex operators, logical
|
||
@opindex &
|
||
@ifnotinfo
|
||
@opindex :
|
||
@end ifnotinfo
|
||
@ifinfo
|
||
@opindex @r{<colon>}
|
||
@end ifinfo
|
||
Logical: @samp{&} (logical and), @samp{:} (logical or).
|
||
|
||
@item
|
||
@cindex unary operators
|
||
@cindex operators, unary
|
||
@opindex -
|
||
@opindex +
|
||
@opindex !
|
||
@cindex @code{if} request, and the @samp{!} operator
|
||
@cindex @code{while} request, and the @samp{!} operator
|
||
Unary operators: @samp{-} (negating, i.e.@: changing the sign), @samp{+}
|
||
(just for completeness; does nothing in expressions), @samp{!} (logical
|
||
not; this works only within @code{if} and @code{while} requests). See
|
||
below for the use of unary operators in motion requests.
|
||
|
||
@item
|
||
@cindex extremum operators (@code{>?}, @code{<?})
|
||
@cindex operators, extremum (@code{>?}, @code{<?})
|
||
@opindex >?
|
||
@opindex <?
|
||
Extrema: @samp{>?} (maximum), @samp{<?} (minimum).
|
||
|
||
Example:
|
||
|
||
@Example
|
||
.nr x 5
|
||
.nr y 3
|
||
.nr z (\n[x] >? \n[y])
|
||
@endExample
|
||
|
||
@noindent
|
||
The register@w{ }@code{z} now contains@w{ }5.
|
||
|
||
@item
|
||
@cindex scaling operator
|
||
@cindex operator, scaling
|
||
Scaling: @code{(@var{c};@var{e})}. Evaluate@w{ }@var{e} using@w{ }@var{c}
|
||
as the default scaling indicator. If @var{c} is missing, ignore scaling
|
||
indicators in the evaluation of@w{ }@var{e}.
|
||
@end itemize
|
||
|
||
@cindex parentheses
|
||
@cindex order of evaluation in expressions
|
||
@cindex expression, order of evaluation
|
||
@opindex (
|
||
@opindex )
|
||
Parentheses may be used as in any other language. However, in
|
||
@code{gtroff} they are necessary to ensure order of evaluation.
|
||
@code{gtroff} has no operator precedence; expressions are evaluated left
|
||
to right. This means that @code{gtroff} evaluates @samp{3+5*4} as if it were
|
||
parenthesized like @samp{(3+5)*4}, not as @samp{3+(5*4)}, as might be
|
||
expected.
|
||
|
||
@cindex @code{+}, and page motion
|
||
@cindex @code{-}, and page motion
|
||
@cindex motion operators
|
||
@cindex operators, motion
|
||
For many requests which cause a motion on the page, the unary operators
|
||
@samp{+} and @samp{-} work differently if leading an expression. They
|
||
then indicate a motion relative to the current position (down or up,
|
||
respectively).
|
||
|
||
@cindex @code{|}, and page motion
|
||
@cindex absolute position operator (@code{|})
|
||
@cindex position, absolute, operator (@code{|})
|
||
Similarly, a leading @samp{|} operator indicates an absolute position.
|
||
For vertical movements, it specifies the distance from the top of the
|
||
page; for horizontal movements, it gives the distance from the beginning
|
||
of the @emph{input} line.
|
||
|
||
@cindex @code{bp} request, using @code{+} and@w{ }@code{-}
|
||
@cindex @code{in} request, using @code{+} and@w{ }@code{-}
|
||
@cindex @code{ll} request, using @code{+} and@w{ }@code{-}
|
||
@cindex @code{lt} request, using @code{+} and@w{ }@code{-}
|
||
@cindex @code{nm} request, using @code{+} and@w{ }@code{-}
|
||
@cindex @code{nr} request, using @code{+} and@w{ }@code{-}
|
||
@cindex @code{pl} request, using @code{+} and@w{ }@code{-}
|
||
@cindex @code{pn} request, using @code{+} and@w{ }@code{-}
|
||
@cindex @code{po} request, using @code{+} and@w{ }@code{-}
|
||
@cindex @code{ps} request, using @code{+} and@w{ }@code{-}
|
||
@cindex @code{pvs} request, using @code{+} and@w{ }@code{-}
|
||
@cindex @code{rt} request, using @code{+} and@w{ }@code{-}
|
||
@cindex @code{ti} request, using @code{+} and@w{ }@code{-}
|
||
@cindex @code{\H}, using @code{+} and@w{ }@code{-}
|
||
@cindex @code{\R}, using @code{+} and@w{ }@code{-}
|
||
@cindex @code{\s}, using @code{+} and@w{ }@code{-}
|
||
@samp{+} and @samp{-} are also treated differently by the following
|
||
requests and escapes: @code{bp}, @code{in}, @code{ll}, @code{lt},
|
||
@code{nm}, @code{nr}, @code{pl}, @code{pn}, @code{po}, @code{ps},
|
||
@code{pvs}, @code{rt}, @code{ti}, @code{\H}, @code{\R}, and @code{\s}.
|
||
Here, leading plus and minus signs indicate increments and decrements.
|
||
|
||
@xref{Setting Registers}, for some examples.
|
||
|
||
@Defesc {\\B, ', anything, '}
|
||
@cindex numeric expression, valid
|
||
@cindex valid numeric expression
|
||
Return@w{ }1 if @var{anything} is a valid numeric expression;
|
||
or@w{ }0 if @var{anything} is empty or not a valid numeric expression.
|
||
@endDefesc
|
||
|
||
@cindex space characters, in expressions
|
||
@cindex expressions, and space characters
|
||
Due to the way arguments are parsed, spaces are not allowed in
|
||
expressions, unless the entire expression is surrounded by parentheses.
|
||
|
||
@xref{Request Arguments}, and @ref{Conditionals and Loops}.
|
||
|
||
|
||
@c =====================================================================
|
||
|
||
@node Identifiers, Embedded Commands, Expressions, gtroff Reference
|
||
@section Identifiers
|
||
@cindex identifiers
|
||
|
||
Like any other language, @code{gtroff} has rules for properly formed
|
||
@dfn{identifiers}. In @code{gtroff}, an identifier can be made up of
|
||
almost any printable character, with the exception of the following
|
||
characters:
|
||
|
||
@itemize @bullet
|
||
@item
|
||
@cindex whitespace characters
|
||
@cindex newline character
|
||
@cindex character, whitespace
|
||
Whitespace characters (spaces, tabs, and newlines).
|
||
|
||
@item
|
||
@cindex character, backspace
|
||
@cindex backspace character
|
||
@cindex @acronym{EBCDIC} encoding of backspace
|
||
Backspace (@acronym{ASCII}@w{ }@code{0x08} or @acronym{EBCDIC}@w{
|
||
}@code{0x16}) and character code @code{0x01}.
|
||
|
||
@item
|
||
@cindex invalid input characters
|
||
@cindex input characters, invalid
|
||
@cindex characters, invalid input
|
||
@cindex Unicode
|
||
The following input characters are invalid and are ignored if
|
||
@code{groff} runs on a machine based on @acronym{ASCII}, causing a
|
||
warning message of type @samp{input} (see @ref{Debugging}, for more
|
||
details): @code{0x00}, @code{0x0B}, @code{0x0D}-@code{0x1F},
|
||
@code{0x80}-@code{0x9F}.
|
||
|
||
And here are the invalid input characters if @code{groff} runs on an
|
||
@acronym{EBCDIC} host: @code{0x00}, @code{0x08}, @code{0x09},
|
||
@code{0x0B}, @code{0x0D}-@code{0x14}, @code{0x17}-@code{0x1F},
|
||
@code{0x30}-@code{0x3F}.
|
||
|
||
Currently, some of these reserved codepoints are used internally, thus
|
||
making it non-trivial to extend @code{gtroff} to cover Unicode or other
|
||
character sets and encodings which use characters of these ranges.
|
||
|
||
Note that invalid characters are removed before parsing; an
|
||
identifier @code{foo}, followed by an invalid character, followed by
|
||
@code{bar} is treated as @code{foobar}.
|
||
@end itemize
|
||
|
||
For example, any of the following is valid.
|
||
|
||
@Example
|
||
br
|
||
PP
|
||
(l
|
||
end-list
|
||
@@_
|
||
@endExample
|
||
|
||
@cindex @code{]}, as part of an identifier
|
||
@noindent
|
||
Note that identifiers longer than two characters with a closing bracket
|
||
(@samp{]}) in its name can't be accessed with escape sequences which
|
||
expect an identifier as a parameter. For example, @samp{\[foo]]}
|
||
accesses the glyph @samp{foo}, followed by @samp{]}, whereas
|
||
@samp{\C'foo]'} really asks for glyph @samp{foo]}.
|
||
|
||
@cindex @code{refer}, and macro names starting with @code{[} or @code{]}
|
||
@cindex @code{[}, macro names starting with, and @code{refer}
|
||
@cindex @code{]}, macro names starting with, and @code{refer}
|
||
@cindex macro names, starting with @code{[} or @code{]}, and @code{refer}
|
||
To avoid problems with the @code{refer} preprocessor, macro names
|
||
should not start with @samp{[} or @samp{]}. Due to backwards
|
||
compatibility, everything after @samp{.[} and @samp{.]} is handled as
|
||
a special argument to @code{refer}. For example, @samp{.[foo} makes
|
||
@code{refer} to start a reference, using @samp{foo} as a parameter.
|
||
|
||
@Defesc {\\A, ', ident, '}
|
||
Test whether an identifier @var{ident} is valid in @code{gtroff}. It
|
||
expands to the character@w{ }1 or@w{ }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 returns@w{ }0 if no argument is given. This is useful for
|
||
looking up user input in some sort of associative table.
|
||
|
||
@Example
|
||
\A'end-list'
|
||
@result{} 1
|
||
@endExample
|
||
@endDefesc
|
||
|
||
@xref{Escapes}, for details on parameter delimiting characters.
|
||
|
||
Identifiers in @code{gtroff} can be any length, but, in some contexts,
|
||
@code{gtroff} needs to be told where identifiers end and text begins
|
||
(and in different ways depending on their length):
|
||
|
||
@itemize @bullet
|
||
@item
|
||
Single character.
|
||
|
||
@cindex @code{(}, starting a two-character identifier
|
||
@item
|
||
Two characters. Must be prefixed with @samp{(} in some situations.
|
||
|
||
@cindex @code{[}, starting an identifier
|
||
@cindex @code{]}, ending an identifier
|
||
@item
|
||
Arbitrary length (@code{gtroff} only). Must be bracketed with @samp{[}
|
||
and@w{ }@samp{]} in some situations. Any length identifier can be put
|
||
in brackets.
|
||
@end itemize
|
||
|
||
@cindex undefined identifiers
|
||
@cindex identifiers, undefined
|
||
Unlike many other programming languages, undefined identifiers are
|
||
silently ignored or expanded to nothing.
|
||
When @code{gtroff} finds an undefined identifier, it emits a
|
||
warning, doing the following:
|
||
|
||
@itemize @bullet
|
||
@item
|
||
If the identifier is a string, macro, or diversion,
|
||
@code{gtroff} defines it as empty.
|
||
|
||
@item
|
||
If the identifier is a number register, @code{gtroff}
|
||
defines it with a value of@w{ }0.
|
||
@end itemize
|
||
|
||
@xref{Warnings}., @ref{Interpolating Registers}, and @ref{Strings}.
|
||
|
||
Note that macros, strings, and diversions share the same name space.
|
||
|
||
@Example
|
||
.de xxx
|
||
. nop foo
|
||
..
|
||
.
|
||
.di xxx
|
||
bar
|
||
.br
|
||
.di
|
||
.
|
||
.xxx
|
||
@result{} bar
|
||
@endExample
|
||
|
||
@noindent
|
||
As can be seen in the previous example, @code{gtroff} reuses the
|
||
identifier @samp{xxx}, changing it from a macro to a diversion.
|
||
No warning is emitted! The contents of the first macro definition is
|
||
lost.
|
||
|
||
@xref{Interpolating Registers}, and @ref{Strings}.
|
||
|
||
|
||
@c =====================================================================
|
||
|
||
@node Embedded Commands, Registers, Identifiers, gtroff Reference
|
||
@section Embedded Commands
|
||
@cindex embedded commands
|
||
@cindex commands, embedded
|
||
|
||
Most documents need more functionality beyond filling, adjusting and
|
||
implicit line breaking. In order to gain further functionality,
|
||
@code{gtroff} allows commands to be embedded into the text, in two ways.
|
||
|
||
The first is a @dfn{request} which takes up an entire line, and does
|
||
some large-scale operation (e.g.@: break lines, start new pages).
|
||
|
||
The other is an @dfn{escape} which can be usually embedded anywhere
|
||
in the text; most requests can accept it even as an argument.
|
||
Escapes generally do more minor operations like sub- and superscripts,
|
||
print a symbol, etc.
|
||
|
||
@menu
|
||
* Requests::
|
||
* Macros::
|
||
* Escapes::
|
||
@end menu
|
||
|
||
@c ---------------------------------------------------------------------
|
||
|
||
@node Requests, Macros, Embedded Commands, Embedded Commands
|
||
@subsection Requests
|
||
@cindex requests
|
||
|
||
@cindex control character (@code{.})
|
||
@cindex character, control (@code{.})
|
||
@cindex no-break control character (@code{'})
|
||
@cindex character, no-break control (@code{'})
|
||
@cindex control character, no-break (@code{'})
|
||
A request line begins with a control character, which is either a single
|
||
quote (@samp{'}, the @dfn{no-break control character}) or a period
|
||
(@samp{.}, the normal @dfn{control character}). These can be changed;
|
||
see @ref{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 (@emph{no} tabs here).
|
||
|
||
@cindex structuring source code of documents or macro packages
|
||
@cindex documents, structuring the source code
|
||
@cindex macro packages, structuring the source code
|
||
Since a control character followed by whitespace only is ignored, it
|
||
is common practice to use this feature for structuring the source code
|
||
of documents or macro packages.
|
||
|
||
@Example
|
||
.de foo
|
||
. tm This is foo.
|
||
..
|
||
.
|
||
.
|
||
.de bar
|
||
. tm This is bar.
|
||
..
|
||
@endExample
|
||
|
||
@cindex blank line
|
||
@cindex blank line macro (@code{blm})
|
||
Another possibility is to use the blank line macro request @code{blm}
|
||
by assigning an empty macro to it.
|
||
|
||
@Example
|
||
.de do-nothing
|
||
..
|
||
.blm do-nothing \" activate blank line macro
|
||
|
||
.de foo
|
||
. tm This is foo.
|
||
..
|
||
|
||
|
||
.de bar
|
||
. tm This is bar.
|
||
..
|
||
|
||
.blm \" deactivate blank line macro
|
||
@endExample
|
||
|
||
@xref{Blank Line Traps}.
|
||
|
||
@cindex zero width space character (@code{\&})
|
||
@cindex character, zero width space (@code{\&})
|
||
@cindex space character, zero width (@code{\&})
|
||
@cindex @code{\&}, escaping control characters
|
||
To begin a line with a control character without it being interpreted,
|
||
precede it with @code{\&}. This represents a zero width space, which
|
||
means it does not affect the output.
|
||
|
||
In most cases the period is used as a control character. Several
|
||
requests cause a break implicitly; using the single quote control
|
||
character prevents this.
|
||
|
||
@menu
|
||
* Request Arguments::
|
||
@end menu
|
||
|
||
@node Request Arguments, , Requests, Requests
|
||
@subsubsection Request Arguments
|
||
@cindex request arguments
|
||
@cindex arguments to requests
|
||
|
||
Arguments to requests (and macros) are processed much like the shell:
|
||
The line is split into arguments according to
|
||
spaces.@footnote{Plan@w{ }9's @code{troff} implementation also allows
|
||
tabs for argument separation -- @code{gtroff} intentionally doesn't
|
||
support this.} An argument which is intended to contain spaces can
|
||
either be enclosed in double quotes, or have the spaces @dfn{escaped}
|
||
with backslashes.
|
||
|
||
Here are a few examples:
|
||
|
||
@Example
|
||
.uh The Mouse Problem
|
||
.uh "The Mouse Problem"
|
||
.uh The\ Mouse\ Problem
|
||
@endExample
|
||
|
||
@cindex @code{\~}, difference to @code{\@key{SP}}
|
||
@cindex @code{\@key{SP}}, difference to @code{\~}
|
||
@noindent
|
||
The first line is the @code{uh} macro being called with 3 arguments,
|
||
@samp{The}, @samp{Mouse}, and @samp{Problem}. The latter two have the
|
||
same effect of calling the @code{uh} macro with one argument, @samp{The
|
||
Mouse Problem}.@footnote{The last solution, i.e., using escaped spaces,
|
||
is ``classical'' in the sense that it can be found in most @code{troff}
|
||
documents. Nevertheless, it is not optimal in all situations, since
|
||
@w{@samp{\ }} inserts a fixed-width, non-breaking space character which
|
||
can't stretch. @code{gtroff} provides a different command @code{\~} to
|
||
insert a stretchable, non-breaking space.}
|
||
|
||
@cindex @code{"}, in a macro argument
|
||
@cindex double quote, in a macro argument
|
||
A double quote which isn't preceded by a space doesn't start a macro
|
||
argument. If not closing a string, it is printed literally.
|
||
|
||
For example,
|
||
|
||
@Example
|
||
.xxx a" "b c" "de"fg"
|
||
@endExample
|
||
|
||
@noindent
|
||
has the arguments @samp{a"}, @w{@samp{b c}}, @samp{de}, and @samp{fg"}.
|
||
Don't rely on this obscure behaviour!
|
||
|
||
There are two possibilities to get a double quote reliably.
|
||
|
||
@itemize @bullet
|
||
@item
|
||
Enclose the whole argument with double quotes and use two consecutive double
|
||
quotes to represent a single one. This traditional solution has the
|
||
disadvantage that double quotes don't survive argument expansion again if
|
||
called in compatibility mode (using the @option{-C} option of @code{groff}):
|
||
|
||
@Example
|
||
.de xx
|
||
. tm xx: `\\$1' `\\$2' `\\$3'
|
||
.
|
||
. yy "\\$1" "\\$2" "\\$3"
|
||
..
|
||
.de yy
|
||
. tm yy: `\\$1' `\\$2' `\\$3'
|
||
..
|
||
.xx A "test with ""quotes""" .
|
||
@result{} xx: `A' `test with "quotes"' `.'
|
||
@result{} yy: `A' `test with ' `quotes""'
|
||
@endExample
|
||
|
||
@noindent
|
||
If not in compatibility mode, you get the expected result
|
||
|
||
@Example
|
||
xx: `A' `test with "quotes"' `.'
|
||
yy: `A' `test with "quotes"' `.'
|
||
@endExample
|
||
|
||
@noindent
|
||
since @code{gtroff} preserves the input level.
|
||
|
||
@item
|
||
Use the double quote glyph @code{\(dq}. This works with and without
|
||
compatibility mode enabled since @code{gtroff} doesn't convert @code{\(dq}
|
||
back to a double quote input character.
|
||
|
||
Not that this method won't work with @acronym{UNIX} @code{troff} in general
|
||
since the glyph `dq' isn't defined normally.
|
||
@end itemize
|
||
|
||
@cindex @code{ds} request, and double quotes
|
||
Double quotes in the @code{ds} request are handled differently.
|
||
@xref{Strings}, for more details.
|
||
|
||
@c ---------------------------------------------------------------------
|
||
|
||
@node Macros, Escapes, Requests, Embedded Commands
|
||
@subsection Macros
|
||
@cindex macros
|
||
|
||
@code{gtroff} has a @dfn{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.
|
||
|
||
@xref{Writing Macros}, and @ref{Request Arguments}.
|
||
|
||
@c ---------------------------------------------------------------------
|
||
|
||
@node Escapes, , Macros, Embedded Commands
|
||
@subsection Escapes
|
||
@cindex escapes
|
||
|
||
Escapes may occur anywhere in the input to @code{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 @ref{Character Translations}.
|
||
|
||
Escape sequences which require an identifier as a parameter accept three
|
||
possible syntax forms.
|
||
|
||
@itemize @bullet
|
||
@item
|
||
The next single character is the identifier.
|
||
|
||
@cindex @code{(}, starting a two-character identifier
|
||
@item
|
||
If this single character is an opening parenthesis, take the following
|
||
two characters as the identifier. Note that there is no closing
|
||
parenthesis after the identifier.
|
||
|
||
@cindex @code{[}, starting an identifier
|
||
@cindex @code{]}, ending an identifier
|
||
@item
|
||
If this single character is an opening bracket, take all characters
|
||
until a closing bracket as the identifier.
|
||
@end itemize
|
||
|
||
@noindent
|
||
Examples:
|
||
|
||
@Example
|
||
\fB
|
||
\n(XX
|
||
\*[TeX]
|
||
@endExample
|
||
|
||
@cindex @code{'}, delimiting arguments
|
||
@cindex argument delimiting characters
|
||
@cindex characters, argument delimiting
|
||
@cindex delimiting characters for arguments
|
||
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:
|
||
|
||
@Example
|
||
\l'1.5i\(bu'
|
||
@endExample
|
||
|
||
@cindex @code{\o}, possible quote characters
|
||
@cindex @code{\b}, possible quote characters
|
||
@cindex @code{\X}, possible quote characters
|
||
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: @code{\o}, @code{\b}, and
|
||
@code{\X}. This makes e.g.
|
||
|
||
@Example
|
||
A caf
|
||
\o
|
||
e\'
|
||
|
||
|
||
in Paris
|
||
@result{} A caf@'e in Paris
|
||
@endExample
|
||
|
||
@noindent
|
||
possible, but it is better not to use this feature to avoid confusion.
|
||
|
||
@cindex @code{\%}, used as delimiter
|
||
@cindex @code{\@key{SP}}, used as delimiter
|
||
@cindex @code{\|}, used as delimiter
|
||
@cindex @code{\^}, used as delimiter
|
||
@cindex @code{\@{}, used as delimiter
|
||
@cindex @code{\@}}, used as delimiter
|
||
@cindex @code{\'}, used as delimiter
|
||
@cindex @code{\`}, used as delimiter
|
||
@cindex @code{\-}, used as delimiter
|
||
@cindex @code{\_}, used as delimiter
|
||
@cindex @code{\!}, used as delimiter
|
||
@cindex @code{\?}, used as delimiter
|
||
@cindex @code{\@@}, used as delimiter
|
||
@cindex @code{\)}, used as delimiter
|
||
@cindex @code{\/}, used as delimiter
|
||
@cindex @code{\,}, used as delimiter
|
||
@cindex @code{\&}, used as delimiter
|
||
@ifnotinfo
|
||
@cindex @code{\:}, used as delimiter
|
||
@end ifnotinfo
|
||
@ifinfo
|
||
@cindex @code{\@r{<colon>}}, used as delimiter
|
||
@end ifinfo
|
||
@cindex @code{\~}, used as delimiter
|
||
@cindex @code{\0}, used as delimiter
|
||
@cindex @code{\a}, used as delimiter
|
||
@cindex @code{\c}, used as delimiter
|
||
@cindex @code{\d}, used as delimiter
|
||
@cindex @code{\e}, used as delimiter
|
||
@cindex @code{\E}, used as delimiter
|
||
@cindex @code{\p}, used as delimiter
|
||
@cindex @code{\r}, used as delimiter
|
||
@cindex @code{\t}, used as delimiter
|
||
@cindex @code{\u}, used as delimiter
|
||
The following escapes sequences (which are handled similarly to
|
||
characters since they don't take a parameter) are also allowed as
|
||
delimiters: @code{\%}, @w{@samp{\ }}, @code{\|}, @code{\^}, @code{\@{},
|
||
@code{\@}}, @code{\'}, @code{\`}, @code{\-}, @code{\_}, @code{\!},
|
||
@code{\?}, @code{\@@}, @code{\)}, @code{\/}, @code{\,}, @code{\&},
|
||
@code{\:}, @code{\~}, @code{\0}, @code{\a}, @code{\c}, @code{\d},
|
||
@code{\e}, @code{\E}, @code{\p}, @code{\r}, @code{\t}, and @code{\u}.
|
||
Again, don't use these if possible.
|
||
|
||
@cindex @code{\A}, allowed delimiters
|
||
@cindex @code{\B}, allowed delimiters
|
||
@cindex @code{\Z}, allowed delimiters
|
||
@cindex @code{\C}, allowed delimiters
|
||
@cindex @code{\w}, allowed delimiters
|
||
No newline characters as delimiters are allowed in the following
|
||
escapes: @code{\A}, @code{\B}, @code{\Z}, @code{\C}, and @code{\w}.
|
||
|
||
@cindex @code{\D}, allowed delimiters
|
||
@cindex @code{\h}, allowed delimiters
|
||
@cindex @code{\H}, allowed delimiters
|
||
@cindex @code{\l}, allowed delimiters
|
||
@cindex @code{\L}, allowed delimiters
|
||
@cindex @code{\N}, allowed delimiters
|
||
@cindex @code{\R}, allowed delimiters
|
||
@cindex @code{\s}, allowed delimiters
|
||
@cindex @code{\S}, allowed delimiters
|
||
@cindex @code{\v}, allowed delimiters
|
||
@cindex @code{\x}, allowed delimiters
|
||
Finally, the escapes @code{\D}, @code{\h}, @code{\H}, @code{\l},
|
||
@code{\L}, @code{\N}, @code{\R}, @code{\s}, @code{\S}, @code{\v},
|
||
and @code{\x} can't use the following characters as delimiters:
|
||
|
||
@itemize @bullet
|
||
@item
|
||
@cindex numbers, and delimiters
|
||
@cindex digits, and delimiters
|
||
The digits @code{0}-@code{9}.
|
||
|
||
@item
|
||
@cindex operators, as delimiters
|
||
@cindex @code{+}, as delimiter
|
||
@cindex @code{-}, as delimiter
|
||
@cindex @code{/}, as delimiter
|
||
@cindex @code{*}, as delimiter
|
||
@cindex @code{%}, as delimiter
|
||
@cindex @code{<}, as delimiter
|
||
@cindex @code{>}, as delimiter
|
||
@cindex @code{=}, as delimiter
|
||
@cindex @code{&}, as delimiter
|
||
@ifnotinfo
|
||
@cindex @code{:}, as delimiter
|
||
@end ifnotinfo
|
||
@ifinfo
|
||
@cindex <colon>, as delimiter
|
||
@end ifinfo
|
||
@cindex @code{(}, as delimiter
|
||
@cindex @code{)}, as delimiter
|
||
@cindex @code{.}, as delimiter
|
||
The (single-character) operators @samp{+-/*%<>=&:().}.
|
||
|
||
@item
|
||
@cindex space character
|
||
@cindex character, space
|
||
@cindex tab character
|
||
@cindex character, tab
|
||
@cindex newline character
|
||
@cindex character, newline
|
||
The space, tab, and newline characters.
|
||
|
||
@item
|
||
@cindex @code{\%}, used as delimiter
|
||
@ifnotinfo
|
||
@cindex @code{\:}, used as delimiter
|
||
@end ifnotinfo
|
||
@ifinfo
|
||
@cindex @code{\@r{<colon>}}, used as delimiter
|
||
@end ifinfo
|
||
@cindex @code{\@{}, used as delimiter
|
||
@cindex @code{\@}}, used as delimiter
|
||
@cindex @code{\'}, used as delimiter
|
||
@cindex @code{\`}, used as delimiter
|
||
@cindex @code{\-}, used as delimiter
|
||
@cindex @code{\_}, used as delimiter
|
||
@cindex @code{\!}, used as delimiter
|
||
@cindex @code{\@@}, used as delimiter
|
||
@cindex @code{\/}, used as delimiter
|
||
@cindex @code{\c}, used as delimiter
|
||
@cindex @code{\e}, used as delimiter
|
||
@cindex @code{\p}, used as delimiter
|
||
All escape sequences except @code{\%}, @code{\:}, @code{\@{}, @code{\@}},
|
||
@code{\'}, @code{\`}, @code{\-}, @code{\_}, @code{\!}, @code{\@@},
|
||
@code{\/}, @code{\c}, @code{\e}, and @code{\p}.
|
||
@end itemize
|
||
|
||
@cindex printing backslash (@code{\\}, @code{\e}, @code{\E}, @code{\[rs]})
|
||
@cindex backslash, printing (@code{\\}, @code{\e}, @code{\E}, @code{\[rs]})
|
||
To have a backslash (actually, the current escape character) appear in the
|
||
output several escapes are defined: @code{\\}, @code{\e} or @code{\E}.
|
||
These are very similar, and only differ with respect to being used in
|
||
macros or diversions. @xref{Character Translations}, for an exact
|
||
description of those escapes.
|
||
|
||
@xref{Implementation Differences}, @ref{Copy-in Mode}, and @ref{Diversions},
|
||
@ref{Identifiers}, for more information.
|
||
|
||
@menu
|
||
* Comments::
|
||
@end menu
|
||
|
||
@node Comments, , Escapes, Escapes
|
||
@subsubsection Comments
|
||
@cindex comments
|
||
|
||
Probably one of the most@footnote{Unfortunately, this is a lie. But
|
||
hopefully future @code{gtroff} hackers will believe it @code{:-)}}
|
||
common forms of escapes is the comment.
|
||
|
||
@Defesc {\\", , , }
|
||
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.
|
||
|
||
@cindex @code{ds}, @code{ds1} requests, and comments
|
||
@cindex @code{as}, @code{as1} requests, and comments
|
||
If the escape is to the right of some text or a request, that portion
|
||
of the line is ignored, but the space leading up to it is noticed by
|
||
@code{gtroff}. This only affects the @code{ds} and @code{as}
|
||
request and its variants.
|
||
|
||
@cindex tabs, before comments
|
||
@cindex comments, lining up with tabs
|
||
One possibly irritating idiosyncracy is that tabs must not be used to
|
||
line up comments. Tabs are not treated as whitespace between the
|
||
request and macro arguments.
|
||
|
||
@cindex undefined request
|
||
@cindex request, undefined
|
||
A comment on a line by itself is treated as a blank line, because
|
||
after eliminating the comment, that is all that remains:
|
||
|
||
@Example
|
||
Test
|
||
\" comment
|
||
Test
|
||
@endExample
|
||
|
||
@noindent
|
||
produces
|
||
|
||
@Example
|
||
Test
|
||
|
||
Test
|
||
@endExample
|
||
|
||
To avoid this, it is common to start the line with @code{.\"} which
|
||
causes the line to be treated as an undefined request and thus ignored
|
||
completely.
|
||
|
||
@cindex @code{'}, as a comment
|
||
Another commenting scheme seen sometimes is three consecutive single
|
||
quotes (@code{'''}) at the beginning of a line. This works, but
|
||
@code{gtroff} gives a warning about an undefined macro (namely
|
||
@code{''}), which is harmless, but irritating.
|
||
@endDefesc
|
||
|
||
@Defesc {\\#, , , }
|
||
To avoid all this, @code{gtroff} has a new comment mechanism using the
|
||
@code{\#} escape. This escape works the same as @code{\"} except that
|
||
the newline is also ignored:
|
||
|
||
@Example
|
||
Test
|
||
\# comment
|
||
Test
|
||
@endExample
|
||
|
||
@noindent
|
||
produces
|
||
|
||
@Example
|
||
Test Test
|
||
@endExample
|
||
|
||
@noindent
|
||
as expected.
|
||
@endDefesc
|
||
|
||
@Defreq {ig, yy}
|
||
Ignore all input until @code{gtroff} encounters the macro named
|
||
@code{.}@var{yy} on a line by itself (or @code{..} if @var{yy} is not
|
||
specified). This is useful for commenting out large blocks of text:
|
||
|
||
@Example
|
||
text text text...
|
||
.ig
|
||
This is part of a large block
|
||
of text that has been
|
||
temporarily(?) commented out.
|
||
|
||
We can restore it simply by removing
|
||
the .ig request and the ".." at the
|
||
end of the block.
|
||
..
|
||
More text text text...
|
||
@endExample
|
||
|
||
@noindent
|
||
produces
|
||
|
||
@Example
|
||
text text text@dots{} More text text text@dots{}
|
||
@endExample
|
||
|
||
@noindent
|
||
Note that the commented-out block of text does not
|
||
cause a break.
|
||
|
||
The input is read in copy-mode; auto-incremented registers @emph{are}
|
||
affected (@pxref{Auto-increment}).
|
||
@endDefreq
|
||
|
||
|
||
@c =====================================================================
|
||
|
||
@node Registers, Manipulating Filling and Adjusting, Embedded Commands, gtroff Reference
|
||
@section Registers
|
||
@cindex registers
|
||
|
||
Numeric variables in @code{gtroff} are called @dfn{registers}. There
|
||
are a number of built-in registers, supplying anything from the date to
|
||
details of formatting parameters.
|
||
|
||
@xref{Identifiers}, for details on register identifiers.
|
||
|
||
@menu
|
||
* Setting Registers::
|
||
* Interpolating Registers::
|
||
* Auto-increment::
|
||
* Assigning Formats::
|
||
* Built-in Registers::
|
||
@end menu
|
||
|
||
@c ---------------------------------------------------------------------
|
||
|
||
@node Setting Registers, Interpolating Registers, Registers, Registers
|
||
@subsection Setting Registers
|
||
@cindex setting registers (@code{nr}, @code{\R})
|
||
@cindex registers, setting (@code{nr}, @code{\R})
|
||
|
||
Define or set registers using the @code{nr} request or the
|
||
@code{\R} escape.
|
||
|
||
@DefreqList {nr, ident value}
|
||
@DefescListEnd {\\R, ', ident value, '}
|
||
Set number register @var{ident} to @var{value}. If @var{ident}
|
||
doesn't exist, @code{gtroff} creates it.
|
||
|
||
The argument to @code{\R} usually has to be enclosed in quotes.
|
||
@xref{Escapes}, for details on parameter delimiting characters.
|
||
|
||
The @code{\R} escape doesn't produce an input token in @code{gtroff};
|
||
with other words, it vanishes completely after @code{gtroff} has
|
||
processed it.
|
||
@endDefreq
|
||
|
||
For example, the following two lines are equivalent:
|
||
|
||
@Example
|
||
.nr a (((17 + (3 * 4))) % 4)
|
||
\R'a (((17 + (3 * 4))) % 4)'
|
||
@result{} 1
|
||
@endExample
|
||
|
||
Both @code{nr} and @code{\R} have two additional special forms to
|
||
increment or decrement a register.
|
||
|
||
@DefreqList {nr, ident @t{+}@Var{value}}
|
||
@DefreqItem {nr, ident @t{-}@Var{value}}
|
||
@DefescItem {\\R, ', ident @t{+}@Var{value}, '}
|
||
@DefescListEnd {\\R, ', ident @t{-}@Var{value}, '}
|
||
Increment (decrement) register @var{ident} by @var{value}.
|
||
|
||
@Example
|
||
.nr a 1
|
||
.nr a +1
|
||
\na
|
||
@result{} 2
|
||
@endExample
|
||
|
||
@cindex negating register values
|
||
To assign the negated value of a register to another register, some care
|
||
must be taken to get the desired result:
|
||
|
||
@Example
|
||
.nr a 7
|
||
.nr b 3
|
||
.nr a -\nb
|
||
\na
|
||
@result{} 4
|
||
.nr a (-\nb)
|
||
\na
|
||
@result{} -3
|
||
@endExample
|
||
|
||
@noindent
|
||
The surrounding parentheses prevent the interpretation of the minus sign
|
||
as a decrementing operator. An alternative is to start the assignment
|
||
with a @samp{0}:
|
||
|
||
@Example
|
||
.nr a 7
|
||
.nr b -3
|
||
.nr a \nb
|
||
\na
|
||
@result{} 4
|
||
.nr a 0\nb
|
||
\na
|
||
@result{} -3
|
||
@endExample
|
||
@endDefreq
|
||
|
||
@Defreq {rr, ident}
|
||
@cindex removing number register (@code{rr})
|
||
@cindex number register, removing (@code{rr})
|
||
@cindex register, removing (@code{rr})
|
||
Remove number register @var{ident}. If @var{ident} doesn't exist, the
|
||
request is ignored.
|
||
@endDefreq
|
||
|
||
@Defreq {rnn, ident1 ident2}
|
||
@cindex renaming number register (@code{rnn})
|
||
@cindex number register, renaming (@code{rnn})
|
||
@cindex register, renaming (@code{rnn})
|
||
Rename number register @var{ident1} to @var{ident2}. If either
|
||
@var{ident1} or @var{ident2} doesn't exist, the request is ignored.
|
||
@endDefreq
|
||
|
||
@Defreq {aln, ident1 ident2}
|
||
@cindex alias, number register, creating (@code{aln})
|
||
@cindex creating alias, for number register (@code{aln})
|
||
@cindex number register, creating alias (@code{aln})
|
||
@cindex register, creating alias (@code{aln})
|
||
Create an alias @var{ident1} for a number register @var{ident2}. The
|
||
new name and the old name are exactly equivalent. If @var{ident1} is
|
||
undefined, a warning of type @samp{reg} is generated, and the request
|
||
is ignored. @xref{Debugging}, for information about warnings.
|
||
@endDefreq
|
||
|
||
@c ---------------------------------------------------------------------
|
||
|
||
@node Interpolating Registers, Auto-increment, Setting Registers, Registers
|
||
@subsection Interpolating Registers
|
||
@cindex interpolating registers (@code{\n})
|
||
@cindex registers, interpolating (@code{\n})
|
||
|
||
Numeric registers can be accessed via the @code{\n} escape.
|
||
|
||
@DefescList {\\n, , i, }
|
||
@DefescItem {\\n, @lparen{}, id, }
|
||
@DefescListEnd {\\n, @lbrack{}, ident, @rbrack}
|
||
@cindex nested assignments
|
||
@cindex assignments, nested
|
||
@cindex indirect assignments
|
||
@cindex assignments, indirect
|
||
Interpolate number register with name @var{ident} (one-character name@w{
|
||
}@var{i}, two-character name @var{id}). This means that the value of the
|
||
register is expanded in-place while @code{gtroff} is parsing the input line.
|
||
Nested assignments (also called indirect assignments) are possible.
|
||
|
||
@Example
|
||
.nr a 5
|
||
.nr as \na+\na
|
||
\n(as
|
||
@result{} 10
|
||
@endExample
|
||
|
||
@Example
|
||
.nr a1 5
|
||
.nr ab 6
|
||
.ds str b
|
||
.ds num 1
|
||
\n[a\n[num]]
|
||
@result{} 5
|
||
\n[a\*[str]]
|
||
@result{} 6
|
||
@endExample
|
||
@endDefesc
|
||
|
||
@c ---------------------------------------------------------------------
|
||
|
||
@node Auto-increment, Assigning Formats, Interpolating Registers, Registers
|
||
@subsection Auto-increment
|
||
@cindex auto-increment
|
||
@cindex increment, automatic
|
||
|
||
Number registers can also be auto-incremented and auto-decremented.
|
||
The increment or decrement value can be specified with a third
|
||
argument to the @code{nr} request or @code{\R} escape.
|
||
|
||
@Defreq {nr, ident value incr}
|
||
@cindex @code{\R}, difference to @code{nr}
|
||
Set number register @var{ident} to @var{value}; the increment for
|
||
auto-incrementing is set to @var{incr}. Note that the @code{\R}
|
||
escape doesn't support this notation.
|
||
@endDefreq
|
||
|
||
To activate auto-incrementing, the escape @code{\n} has a special
|
||
syntax form.
|
||
|
||
@DefescList {\\n, +, i, }
|
||
@DefescItem {\\n, -, i, }
|
||
@DefescItem {\\n, @lparen{}+, id, }
|
||
@DefescItem {\\n, @lparen{}-, id, }
|
||
@DefescItem {\\n, +@lparen{}, id, }
|
||
@DefescItem {\\n, -@lparen{}, id, }
|
||
@DefescItem {\\n, @lbrack{}+, ident, @rbrack{}}
|
||
@DefescItem {\\n, @lbrack{}-, ident, @rbrack{}}
|
||
@DefescItem {\\n, +@lbrack{}, ident, @rbrack{}}
|
||
@DefescListEnd {\\n, -@lbrack{}, ident, @rbrack{}}
|
||
Before interpolating, increment or decrement @var{ident}
|
||
(one-character name@w{ }@var{i}, two-character name @var{id}) by the
|
||
auto-increment value as specified with the @code{nr} request (or the
|
||
@code{\R} escape). If no auto-increment value has been specified,
|
||
these syntax forms are identical to @code{\n}.
|
||
@endDefesc
|
||
|
||
For example,
|
||
|
||
@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]
|
||
@endExample
|
||
|
||
@noindent
|
||
produces
|
||
|
||
@Example
|
||
1, 2, 3, 4, 5
|
||
-5, -10, -15, -20, -25
|
||
-2, -4, -6, -8, -10
|
||
@endExample
|
||
|
||
@cindex increment value without changing the register
|
||
@cindex value, incrementing without changing the register
|
||
To change the increment value without changing the value of a register
|
||
(@var{a} in the example), the following can be used:
|
||
|
||
@Example
|
||
.nr a \na 10
|
||
@endExample
|
||
|
||
@c ---------------------------------------------------------------------
|
||
|
||
@node Assigning Formats, Built-in Registers, Auto-increment, Registers
|
||
@subsection Assigning Formats
|
||
@cindex assigning formats (@code{af})
|
||
@cindex formats, assigning (@code{af})
|
||
|
||
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 @code{af} request.
|
||
|
||
@Defreq {af, ident format}
|
||
Change the output format of a number register. The first argument
|
||
@var{ident} is the name of the number register to be changed, and the
|
||
second argument @var{format} is the output format. The following
|
||
output formats are available:
|
||
|
||
@table @code
|
||
@item 1
|
||
Decimal arabic numbers. This is the default format: 0, 1, 2, 3,@w{
|
||
}@enddots{}
|
||
|
||
@item 0@dots{}0
|
||
Decimal numbers with as many digits as specified. So, @samp{00} would
|
||
result in printing numbers as 01, 02, 03,@w{ }@enddots{}
|
||
|
||
In fact, any digit instead of zero will do; @code{gtroff} only counts
|
||
how many digits are specified. As a consequence, @code{af}'s default
|
||
format @samp{1} could be specified as @samp{0} also (and exactly this is
|
||
returned by the @code{\g} escape, see below).
|
||
|
||
@item I
|
||
@cindex Roman numerals
|
||
@cindex numerals, Roman
|
||
Upper-case Roman numerals: 0, I, II, III, IV,@w{ }@enddots{}
|
||
|
||
@item i
|
||
Lower-case Roman numerals: 0, i, ii, iii, iv,@w{ }@enddots{}
|
||
|
||
@item A
|
||
Upper-case letters: 0, A, B, C, @dots{},@w{ }Z, AA, AB,@w{ }@enddots{}
|
||
|
||
@item a
|
||
Lower-case letters: 0, a, b, c, @dots{},@w{ }z, aa, ab,@w{ }@enddots{}
|
||
@end table
|
||
|
||
Omitting the number register format causes a warning of type
|
||
@samp{missing}. @xref{Debugging}, for more details. Specifying a
|
||
nonexistent format causes an error.
|
||
|
||
The following example produces @samp{10, X, j, 010}:
|
||
|
||
@Example
|
||
.nr a 10
|
||
.af a 1 \" the default format
|
||
\na,
|
||
.af a I
|
||
\na,
|
||
.af a a
|
||
\na,
|
||
.af a 001
|
||
\na
|
||
@endExample
|
||
|
||
@cindex Roman numerals, maximum and minimum
|
||
@cindex maximum values of Roman numerals
|
||
@cindex minimum values of Roman numerals
|
||
The largest number representable for the @samp{i} and @samp{I} formats
|
||
is 39999 (or @minus{}39999); @acronym{UNIX} @code{troff} uses @samp{z}
|
||
and @samp{w} to represent 10000 and 5000 in Roman numerals, and so does
|
||
@code{gtroff}. Currently, the correct glyphs of Roman numeral five
|
||
thousand and Roman numeral ten thousand (Unicode code points
|
||
@code{U+2182} and @code{U+2181}, respectively) are not available.
|
||
|
||
If @var{ident} doesn't exist, it is created.
|
||
|
||
@cindex read-only register, changing format
|
||
@cindex changing format, and read-only registers
|
||
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 @code{af} request to this other register.
|
||
@endDefreq
|
||
|
||
@DefescList {\\g, , i, }
|
||
@DefescItem {\\g, @lparen{}, id, }
|
||
@DefescListEnd {\\g, @lbrack{}, ident, @rbrack{}}
|
||
@cindex format of register (@code{\g})
|
||
@cindex register, format (@code{\g})
|
||
Return the current format of the specified register @var{ident}
|
||
(one-character name@w{ }@var{i}, two-character name @var{id}). For
|
||
example, @samp{\ga} after the previous example would produce the
|
||
string @samp{000}. If the register hasn't been defined yet, nothing
|
||
is returned.
|
||
@endDefesc
|
||
|
||
@c ---------------------------------------------------------------------
|
||
|
||
@node Built-in Registers, , Assigning Formats, Registers
|
||
@subsection Built-in Registers
|
||
@cindex built-in registers
|
||
@cindex registers, built-in
|
||
|
||
The following lists some built-in registers which are not described
|
||
elsewhere in this manual. Any register which begins with a @samp{.} is
|
||
read-only. A complete listing of all built-in registers can be found in
|
||
appendix@w{ }@ref{Register Index}.
|
||
|
||
@table @code
|
||
@item .F
|
||
@cindex current input file name register (@code{.F})
|
||
@cindex input file name, current, register (@code{.F})
|
||
@vindex .F
|
||
This string-valued register returns the current input file name.
|
||
|
||
@item .H
|
||
@cindex horizontal resolution register (@code{.H})
|
||
@cindex resolution, horizontal, register (@code{.H})
|
||
@vindex .H
|
||
Horizontal resolution in basic units.
|
||
|
||
@item .V
|
||
@cindex vertical resolution register (@code{.V})
|
||
@cindex resolution, vertical, register (@code{.V})
|
||
@vindex .V
|
||
Vertical resolution in basic units.
|
||
|
||
@item seconds
|
||
@cindex seconds, current time (@code{seconds})
|
||
@cindex time, current, seconds (@code{seconds})
|
||
@cindex current time, seconds (@code{seconds})
|
||
@vindex seconds
|
||
The number of seconds after the minute, normally in the range@w{ }0
|
||
to@w{ }59, but can be up to@w{ }61 to allow for leap seconds. Initialized
|
||
at start-up of @code{gtroff}.
|
||
|
||
@item minutes
|
||
@cindex minutes, current time (@code{minutes})
|
||
@cindex time, current, minutes (@code{minutes})
|
||
@cindex current time, minutes (@code{minutes})
|
||
@vindex minutes
|
||
The number of minutes after the hour, in the range@w{ }0 to@w{ }59.
|
||
Initialized at start-up of @code{gtroff}.
|
||
|
||
@item hours
|
||
@cindex hours, current time (@code{hours})
|
||
@cindex time, current, hours (@code{hours})
|
||
@cindex current time, hours (@code{hours})
|
||
@vindex hours
|
||
The number of hours past midnight, in the range@w{ }0 to@w{ }23.
|
||
Initialized at start-up of @code{gtroff}.
|
||
|
||
@item dw
|
||
@cindex day of the week register (@code{dw})
|
||
@cindex date, day of the week register (@code{dw})
|
||
@vindex dw
|
||
Day of the week (1-7).
|
||
|
||
@item dy
|
||
@cindex day of the month register (@code{dy})
|
||
@cindex date, day of the month register (@code{dy})
|
||
@vindex dy
|
||
Day of the month (1-31).
|
||
|
||
@item mo
|
||
@cindex month of the year register (@code{mo})
|
||
@cindex date, month of the year register (@code{mo})
|
||
@vindex mo
|
||
Current month (1-12).
|
||
|
||
@item year
|
||
@cindex date, year register (@code{year}, @code{yr})
|
||
@cindex year, current, register (@code{year}, @code{yr})
|
||
@vindex year
|
||
The current year.
|
||
|
||
@item yr
|
||
@vindex yr
|
||
The current year minus@w{ }1900. Unfortunately, the documentation of
|
||
@acronym{UNIX} Version@w{ }7's @code{troff} had a year@w{ }2000 bug: It
|
||
incorrectly claimed that @code{yr} contains the last two digits of the
|
||
year. That claim has never been true of either @acronym{AT&T}
|
||
@code{troff} or GNU @code{troff}. Old @code{troff} input that looks
|
||
like this:
|
||
|
||
@Example
|
||
'\" The following line stopped working after 1999
|
||
This document was formatted in 19\n(yr.
|
||
@endExample
|
||
|
||
@noindent
|
||
can be corrected as follows:
|
||
|
||
@Example
|
||
This document was formatted in \n[year].
|
||
@endExample
|
||
|
||
@noindent
|
||
or, to be portable to older @code{troff} versions, as follows:
|
||
|
||
@Example
|
||
.nr y4 1900+\n(yr
|
||
This document was formatted in \n(y4.
|
||
@endExample
|
||
|
||
@item .c
|
||
@vindex .c
|
||
@itemx c.
|
||
@vindex c.
|
||
@cindex input line number register (@code{.c}, @code{c.})
|
||
@cindex line number, input, register (@code{.c}, @code{c.})
|
||
The current @emph{input} line number. Register @samp{.c} is read-only,
|
||
whereas @samp{c.} (a @code{gtroff} extension) is writable also,
|
||
affecting both @samp{.c} and @samp{c.}.
|
||
|
||
@item ln
|
||
@vindex ln
|
||
@cindex output line number register (@code{ln})
|
||
@cindex line number, output, register (@code{ln})
|
||
The current @emph{output} line number after a call to the @code{nm}
|
||
request to activate line numbering.
|
||
|
||
@xref{Miscellaneous}, for more information about line numbering.
|
||
|
||
@item .x
|
||
@vindex .x
|
||
@cindex major version number register (@code{.x})
|
||
@cindex version number, major, register (@code{.x})
|
||
The major version number. For example, if the version number is@w{
|
||
}1.03 then @code{.x} contains@w{ }@samp{1}.
|
||
|
||
@item .y
|
||
@vindex .y
|
||
@cindex minor version number register (@code{.y})
|
||
@cindex version number, minor, register (@code{.y})
|
||
The minor version number. For example, if the version number is@w{
|
||
}1.03 then @code{.y} contains@w{ }@samp{03}.
|
||
|
||
@item .Y
|
||
@vindex .Y
|
||
@cindex revision number register (@code{.Y})
|
||
The revision number of @code{groff}.
|
||
|
||
@item $$
|
||
@vindex $$
|
||
@cindex process ID of @code{gtroff} register (@code{$$})
|
||
@cindex @code{gtroff}, process ID register (@code{$$})
|
||
The process ID of @code{gtroff}.
|
||
|
||
@item .g
|
||
@vindex .g
|
||
@cindex @code{gtroff}, identification register (@code{.g})
|
||
@cindex GNU-specific register (@code{.g})
|
||
Always@w{ }1. Macros should use this to determine whether they are
|
||
running under GNU @code{troff}.
|
||
|
||
@item .A
|
||
@vindex .A
|
||
@cindex @acronym{ASCII} approximation output register (@code{.A})
|
||
If the command line option @option{-a} is used to produce an
|
||
@acronym{ASCII} approximation of the output, this is set to@w{ }1, zero
|
||
otherwise. @xref{Groff Options}.
|
||
|
||
@item .P
|
||
@vindex .P
|
||
This register is set to@w{ }1 (and to@w{ }0 otherwise) if the current
|
||
page is actually being printed, i.e., if the @option{-o} option is being
|
||
used to only print selected pages. @xref{Groff Options}, for more
|
||
information.
|
||
|
||
@item .T
|
||
@vindex .T
|
||
If @code{gtroff} is called with the @option{-T} command line option, the
|
||
number register @code{.T} is set to@w{ }1, and zero otherwise.
|
||
@xref{Groff Options}.
|
||
|
||
@stindex .T
|
||
@cindex output device name string register (@code{.T})
|
||
Additionally, @code{gtroff} predefines a single read-write string
|
||
register @code{.T} which contains the current output device (for
|
||
example, @samp{latin1} or @samp{ps}).
|
||
@end table
|
||
|
||
|
||
@c =====================================================================
|
||
|
||
@node Manipulating Filling and Adjusting, Manipulating Hyphenation, Registers, gtroff Reference
|
||
@section Manipulating Filling and Adjusting
|
||
@cindex manipulating filling and adjusting
|
||
@cindex filling and adjusting, manipulating
|
||
@cindex adjusting and filling, manipulating
|
||
@cindex justifying text
|
||
@cindex text, justifying
|
||
|
||
@cindex break
|
||
@cindex line break
|
||
@cindex @code{bp} request, causing implicit linebreak
|
||
@cindex @code{ce} request, causing implicit linebreak
|
||
@cindex @code{cf} request, causing implicit linebreak
|
||
@cindex @code{fi} request, causing implicit linebreak
|
||
@cindex @code{fl} request, causing implicit linebreak
|
||
@cindex @code{in} request, causing implicit linebreak
|
||
@cindex @code{nf} request, causing implicit linebreak
|
||
@cindex @code{rj} request, causing implicit linebreak
|
||
@cindex @code{sp} request, causing implicit linebreak
|
||
@cindex @code{ti} request, causing implicit linebreak
|
||
@cindex @code{trf} request, causing implicit linebreak
|
||
Various ways of causing @dfn{breaks} were given in @ref{Implicit Line
|
||
Breaks}. The @code{br} request likewise causes a break. Several
|
||
other requests also cause breaks, but implicitly. These are
|
||
@code{bp}, @code{ce}, @code{cf}, @code{fi}, @code{fl}, @code{in},
|
||
@code{nf}, @code{rj}, @code{sp}, @code{ti}, and @code{trf}.
|
||
|
||
@Defreq {br, }
|
||
Break the current line, i.e., the input collected so far is emitted
|
||
without adjustment.
|
||
|
||
If the no-break control character is used, @code{gtroff} suppresses
|
||
the break:
|
||
|
||
@Example
|
||
a
|
||
'br
|
||
b
|
||
@result{} a b
|
||
@endExample
|
||
@endDefreq
|
||
|
||
Initially, @code{gtroff} fills and adjusts text to both margins.
|
||
Filling can be disabled via the @code{nf} request and re-enabled with
|
||
the @code{fi} request.
|
||
|
||
@DefreqList {fi, }
|
||
@DefregListEnd {.u}
|
||
@cindex fill mode (@code{fi})
|
||
@cindex mode, fill (@code{fi})
|
||
Activate fill mode (which is the default). This request implicitly
|
||
enables adjusting; it also inserts a break in the text currently being
|
||
filled. The read-only number register @code{.u} is set to@w{ }1.
|
||
|
||
The fill mode status is associated with the current environment
|
||
(@pxref{Environments}).
|
||
|
||
See @ref{Line Control}, for interaction with the @code{\c} escape.
|
||
@endDefreq
|
||
|
||
@Defreq {nf, }
|
||
@cindex no-fill mode (@code{nf})
|
||
@cindex mode, no-fill (@code{nf})
|
||
Activate no-fill mode. Input lines are output as-is, retaining line
|
||
breaks and ignoring the current line length. This command implicitly
|
||
disables adjusting; it also causes a break. The number register
|
||
@code{.u} is set to@w{ }0.
|
||
|
||
The fill mode status is associated with the current environment
|
||
(@pxref{Environments}).
|
||
|
||
See @ref{Line Control}, for interaction with the @code{\c} escape.
|
||
@endDefreq
|
||
|
||
@DefreqList {ad, [@Var{mode}]}
|
||
@DefregListEnd {.j}
|
||
Set adjusting mode.
|
||
|
||
Activation and deactivation of adjusting is done implicitly with
|
||
calls to the @code{fi} or @code{nf} requests.
|
||
|
||
@var{mode} can have one of the following values:
|
||
|
||
@table @code
|
||
@item l
|
||
@cindex ragged-right
|
||
Adjust text to the left margin. This produces what is traditionally
|
||
called ragged-right text.
|
||
|
||
@item r
|
||
@cindex ragged-left
|
||
Adjust text to the right margin, producing ragged-left text.
|
||
|
||
@item c
|
||
@cindex centered text
|
||
@cindex @code{ce} request, difference to @samp{.ad@w{ }c}
|
||
Center filled text. This is different to the @code{ce} request which
|
||
only centers text without filling.
|
||
|
||
@item b
|
||
@itemx n
|
||
Justify to both margins. This is the default used by @code{gtroff}.
|
||
@end table
|
||
|
||
With no argument, @code{gtroff} adjusts lines in the same way it did
|
||
before adjusting was deactivated (with a call to @code{na}, for
|
||
example).
|
||
|
||
@Example
|
||
text
|
||
.ad r
|
||
text
|
||
.ad c
|
||
text
|
||
.na
|
||
text
|
||
.ad \" back to centering
|
||
text
|
||
@endExample
|
||
|
||
@cindex adjustment mode register (@code{.j})
|
||
The current adjustment mode is available in the read-only number
|
||
register @code{.j}; it can be stored and subsequently used to set
|
||
adjustment.
|
||
|
||
The adjustment mode status is associated with the current environment
|
||
(@pxref{Environments}).
|
||
@endDefreq
|
||
|
||
@Defreq {na, }
|
||
Disable adjusting. This request won't change the current adjustment
|
||
mode: A subsequent call to @code{ad} uses the previous adjustment
|
||
setting.
|
||
|
||
The adjustment mode status is associated with the current environment
|
||
(@pxref{Environments}).
|
||
@endDefreq
|
||
|
||
@DefreqList {brp, }
|
||
@DefescListEnd {\\p, , , }
|
||
Adjust the current line and cause a break.
|
||
|
||
In most cases this produces very ugly results since @code{gtroff}
|
||
doesn't have a sophisticated paragraph building algorithm (as @TeX{}
|
||
have, for example); instead, @code{gtroff} fills and adjusts a paragraph
|
||
line by line:
|
||
|
||
@Example
|
||
This is an uninteresting sentence.
|
||
This is an uninteresting sentence.\p
|
||
This is an uninteresting sentence.
|
||
@endExample
|
||
|
||
@noindent
|
||
is formatted as
|
||
|
||
@Example
|
||
This is an uninteresting sentence. This is an
|
||
uninteresting sentence.
|
||
This is an uninteresting sentence.
|
||
@endExample
|
||
@endDefreq
|
||
|
||
@DefreqList {ss, word_space_size [@Var{sentence_space_size}]}
|
||
@DefregItem {.ss}
|
||
@DefregListEnd {.sss}
|
||
@cindex word space size register (@code{.ss})
|
||
@cindex size of word space register (@code{.ss})
|
||
@cindex space between words register (@code{.ss})
|
||
@cindex sentence space size register (@code{.sss})
|
||
@cindex size of sentence space register (@code{.sss})
|
||
@cindex space between sentences register (@code{.sss})
|
||
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 @var{word_space_size} and
|
||
@var{sentence_space_size} are@w{ }12.
|
||
|
||
@cindex fill mode
|
||
@cindex mode, fill
|
||
If two arguments are given to the @code{ss} request, the second
|
||
argument sets the sentence space size. If the second argument is not
|
||
given, sentence space size is set to @var{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 are added; if two spaces follow
|
||
the end of a sentence in the middle of a line, then the second space
|
||
is a sentence space. If a second argument is never given to the
|
||
@code{ss} request, the behaviour of @acronym{UNIX} @code{troff} is the
|
||
same as that exhibited by GNU @code{troff}. In GNU @code{troff}, as
|
||
in @acronym{UNIX} @code{troff}, a sentence should always be followed
|
||
by either a newline or two spaces.
|
||
|
||
The read-only number registers @code{.ss} and @code{.sss} hold the
|
||
values of the parameters set by the first and second arguments of the
|
||
@code{ss} request.
|
||
|
||
The word space and sentence space values are associated with the current
|
||
environment (@pxref{Environments}).
|
||
|
||
Contrary to @acronym{AT&T} @code{troff}, this request is @emph{not}
|
||
ignored if a TTY output device is used; the given values are then
|
||
rounded down to a multiple of@w{ }12 (@pxref{Implementation Differences}).
|
||
|
||
The request is ignored if there is no parameter.
|
||
@endDefreq
|
||
|
||
@DefreqList {ce, [@Var{nnn}]}
|
||
@DefregListEnd {.ce}
|
||
@cindex centering lines (@code{ce})
|
||
@cindex lines, centering (@code{ce})
|
||
Center text. While the @w{@samp{.ad c}} request also centers text,
|
||
it fills the text as well. @code{ce} does not fill the
|
||
text it affects. This request causes a break. The number of lines
|
||
still to be centered is associated with the current environment
|
||
(@pxref{Environments}).
|
||
|
||
The following example demonstrates the differences.
|
||
Here the input:
|
||
|
||
@Example
|
||
.ll 4i
|
||
.ce 1000
|
||
This is a small text fragment which shows the differences
|
||
between the `.ce' and the `.ad c' request.
|
||
.ce 0
|
||
|
||
.ad c
|
||
This is a small text fragment which shows the differences
|
||
between the `.ce' and the `.ad c' request.
|
||
@endExample
|
||
|
||
@noindent
|
||
And here the result:
|
||
|
||
@Example
|
||
This is a small text fragment which
|
||
shows the differences
|
||
between the `.ce' and the `.ad c' request.
|
||
|
||
This is a small text fragment which
|
||
shows the differences between the `.ce'
|
||
and the `.ad c' request.
|
||
@endExample
|
||
|
||
With no arguments, @code{ce} centers the next line of text. @var{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
|
||
@code{ll} request) minus the indentation (as set with the @code{in}
|
||
request). Temporary indentation is ignored.
|
||
|
||
As can be seen in the previous example, it is a common idiom 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.
|
||
|
||
The @code{.ce} read-only number register contains the number of lines
|
||
remaining to be centered, as set by the @code{ce} request.
|
||
@endDefreq
|
||
|
||
@DefreqList {rj, [@Var{nnn}]}
|
||
@DefregListEnd {.rj}
|
||
@cindex justifying text (@code{rj})
|
||
@cindex text, justifying (@code{rj})
|
||
@cindex right-justifying (@code{rj})
|
||
Justify unfilled text to the right margin. Arguments are identical to
|
||
the @code{ce} request. The @code{.rj} read-only number register is
|
||
the number of lines to be right-justified as set by the @code{rj}
|
||
request. This request causes a break. The number of lines still to be
|
||
right-justified is associated with the current environment
|
||
(@pxref{Environments}).
|
||
@endDefreq
|
||
|
||
|
||
@c =====================================================================
|
||
|
||
@node Manipulating Hyphenation, Manipulating Spacing, Manipulating Filling and Adjusting, gtroff Reference
|
||
@section Manipulating Hyphenation
|
||
@cindex manipulating hyphenation
|
||
@cindex hyphenation, manipulating
|
||
|
||
As discussed in @ref{Hyphenation}, @code{gtroff} hyphenates words.
|
||
There are a number of ways to influence hyphenation.
|
||
|
||
@DefreqList {hy, [@Var{mode}]}
|
||
@DefregListEnd {.hy}
|
||
Enable hyphenation. The request has an optional numeric argument,
|
||
@var{mode}, to restrict hyphenation if necessary:
|
||
|
||
@table @code
|
||
@item 1
|
||
The default argument if @var{mode} is omitted. Hyphenate without
|
||
restrictions. This is also the start-up value of @code{gtroff}.
|
||
|
||
@item 2
|
||
Do not hyphenate the last word on a page or column.
|
||
|
||
@item 4
|
||
Do not hyphenate the last two characters of a word.
|
||
|
||
@item 8
|
||
Do not hyphenate the first two characters of a word.
|
||
@end table
|
||
|
||
Values in the previous table are additive. For example, the value@w{
|
||
}12 causes @code{gtroff} to neither hyphenate the last two nor the first
|
||
two characters of a word.
|
||
|
||
@cindex hyphenation restrictions register (@code{.hy})
|
||
The current hyphenation restrictions can be found in the read-only
|
||
number register @samp{.hy}.
|
||
|
||
The hyphenation mode is associated with the current environment
|
||
(@pxref{Environments}).
|
||
@endDefreq
|
||
|
||
@Defreq {nh, }
|
||
Disable hyphenation (i.e., set the hyphenation mode to zero). Note
|
||
that the hyphenation mode of the last call to @code{hy} is not
|
||
remembered.
|
||
|
||
The hyphenation mode is associated with the current environment
|
||
(@pxref{Environments}).
|
||
@endDefreq
|
||
|
||
@DefreqList {hlm, [@Var{nnn}]}
|
||
@DefregItem {.hlm}
|
||
@DefregListEnd {.hlc}
|
||
@cindex explicit hyphen (@code{\%})
|
||
@cindex hyphen, explicit (@code{\%})
|
||
@cindex consecutive hyphenated lines (@code{hlm})
|
||
@cindex lines, consecutive hyphenated (@code{hlm})
|
||
@cindex hyphenated lines, consecutive (@code{hlm})
|
||
Set the maximum number of consecutive hyphenated lines to @var{nnn}.
|
||
If this number is negative, there is no maximum. The default value
|
||
is@w{ }@minus{}1 if @var{nnn} is omitted. This value is associated
|
||
with the current environment (@pxref{Environments}). Only lines
|
||
output from a given environment count towards the maximum associated
|
||
with that environment. Hyphens resulting from @code{\%} are counted;
|
||
explicit hyphens are not.
|
||
|
||
The current setting of @code{hlm} is available in the @code{.hlm}
|
||
read-only number register. Also the number of immediately preceding
|
||
consecutive hyphenated lines are available in the read-only number
|
||
register @samp{.hlc}.
|
||
@endDefreq
|
||
|
||
@Defreq {hw, word1 word2 @dots{}}
|
||
Define how @var{word1}, @var{word2}, etc.@: are to be hyphenated. The
|
||
words must be given with hyphens at the hyphenation points. For
|
||
example:
|
||
|
||
@Example
|
||
.hw in-sa-lub-rious
|
||
@endExample
|
||
|
||
@noindent
|
||
Besides the space character, any character whose hyphenation code value
|
||
is zero can be used to separate the arguments of @code{hw} (see the
|
||
documentation for the @code{hcode} request below for more information).
|
||
In addition, this request can be used more than once.
|
||
|
||
Hyphenation exceptions specified with the @code{hw} request are
|
||
associated with the current hyphenation language; it causes an error
|
||
if there is no current hyphenation language.
|
||
|
||
This request is ignored if there is no parameter.
|
||
|
||
In old versions of @code{troff} there was a limited amount of space to
|
||
store such information; fortunately, with @code{gtroff}, this is no
|
||
longer a restriction.
|
||
@endDefreq
|
||
|
||
@DefescList {\\%, , , }
|
||
@deffnx Escape @t{\:}
|
||
@ifnotinfo
|
||
@esindex \:
|
||
@end ifnotinfo
|
||
@ifinfo
|
||
@esindex @r{<colon>}
|
||
@end ifinfo
|
||
@cindex hyphenation character (@code{\%})
|
||
@cindex character, hyphenation (@code{\%})
|
||
@cindex disabling hyphenation (@code{\%})
|
||
@cindex hyphenation, disabling (@code{\%})
|
||
To tell @code{gtroff} how to hyphenate words on the fly, use the
|
||
@code{\%} escape, also known as the @dfn{hyphenation character}.
|
||
Preceding a word with this character prevents it from being
|
||
hyphenated; putting it inside a word indicates to @code{gtroff} that
|
||
the word may be hyphenated at that point. Note that this mechanism
|
||
only affects that one occurrence of the word; to change the
|
||
hyphenation of a word for the entire document, use the @code{hw}
|
||
request.
|
||
|
||
The @code{\:} escape inserts a zero-width break point
|
||
(that is, the word breaks but without adding a hyphen).
|
||
|
||
@Example
|
||
... check the /var/log/\:httpd/\:access_log file ...
|
||
@endExample
|
||
|
||
@cindex @code{\X}, followed by @code{\%}
|
||
@cindex @code{\Y}, followed by @code{\%}
|
||
@cindex @code{\%}, following @code{\X} or @code{\Y}
|
||
Note that @code{\X} and @code{\Y} start a word, that is, the @code{\%}
|
||
escape in (say) @w{@samp{ \X'...'\%foobar}} and
|
||
@w{@samp{ \Y'...'\%foobar}} no longer prevents hyphenation but inserts
|
||
a hyphenation point at the beginning of @samp{foobar}; most likely
|
||
this isn't what you want to do.
|
||
@endDefesc
|
||
|
||
@Defreq {hc, [@Var{char}]}
|
||
Change the hyphenation character to @var{char}. This character then
|
||
works the same as the @code{\%} escape, and thus, no longer appears in
|
||
the output. Without an argument, @code{hc} resets the hyphenation
|
||
character to be @code{\%} (the default) only.
|
||
|
||
The hyphenation character is associated with the current environment
|
||
(@pxref{Environments}).
|
||
@endDefreq
|
||
|
||
@DefreqList {hpf, pattern_file}
|
||
@DefreqItem {hpfa, pattern_file}
|
||
@DefreqListEnd {hpfcode, a b [c d @dots{}]}
|
||
@cindex hyphenation patterns (@code{hpf})
|
||
@cindex patterns for hyphenation (@code{hpf})
|
||
Read in a file of hyphenation patterns. This file is searched for in
|
||
the same way as @file{@var{name}.tmac} (or @file{tmac.@var{name}}) is
|
||
searched for if the @option{-m@var{name}} option is specified.
|
||
|
||
It should have the same format as (simple) @TeX{} patterns files.
|
||
More specifically, the following scanning rules are implemented.
|
||
|
||
@itemize @bullet
|
||
@item
|
||
A percent sign starts a comment (up to the end of the line)
|
||
even if preceded by a backslash.
|
||
|
||
@item
|
||
No support for `digraphs' like @code{\$}.
|
||
|
||
@item
|
||
@code{^^@var{xx}} (@var{x} is 0-9 or a-f) and @code{^^@var{x}} (character
|
||
code of @var{x} in the range 0-127) are recognized; other use of @code{^}
|
||
causes an error.
|
||
|
||
@item
|
||
No macro expansion.
|
||
|
||
@item
|
||
@code{hpf} checks for the expression @code{\patterns@{@dots{}@}}
|
||
(possibly with whitespace before and after the braces).
|
||
Everything between the braces is taken as hyphenation patterns.
|
||
Consequently, @code{@{} and @code{@}} are not allowed in patterns.
|
||
|
||
@item
|
||
Similarly, @code{\hyphenation@{@dots{}@}} gives a list of hyphenation
|
||
exceptions.
|
||
|
||
@item
|
||
@code{\endinput} is recognized also.
|
||
|
||
@item
|
||
For backwards compatibility, if @code{\patterns} is missing,
|
||
the whole file is treated as a list of hyphenation patterns
|
||
(only recognizing the @code{%} character as the start of a comment).
|
||
@end itemize
|
||
|
||
If no @code{hpf} request is specified (either in the document or in a
|
||
macro package), @code{gtroff} won't hyphenate at all.
|
||
|
||
The @code{hpfa} request appends a file of patterns to the current list.
|
||
|
||
The @code{hpfcode} request defines mapping values for character codes in
|
||
hyphenation patterns. @code{hpf} or @code{hpfa} then apply the mapping
|
||
(after reading the patterns) before replacing or appending them to
|
||
the current list of patterns. Its arguments are pairs of character codes
|
||
-- integers from 0 to@w{ }255. The request maps character code@w{ }@var{a}
|
||
to code@w{ }@var{b}, code@w{ }@var{c} to code@w{ }@var{d}, and so on. You
|
||
can use character codes which would be invalid otherwise.
|
||
|
||
@pindex troffrc
|
||
@pindex troffrc-end
|
||
@pindex hyphen.us
|
||
The set of hyphenation patterns is associated with the current language
|
||
set by the @code{hla} request. The @code{hpf} request is usually
|
||
invoked by the @file{troffrc} or @file{troffrc-end} file; by default,
|
||
@file{troffrc} loads hyphenation patterns for American English (in file
|
||
@file{hyphen.us}).
|
||
|
||
A second call to @code{hpf} (for the same language) will replace the
|
||
hyphenation patterns with the new ones.
|
||
|
||
Invoking @code{hpf} causes an error if there is no current hyphenation
|
||
language.
|
||
@endDefreq
|
||
|
||
@Defreq {hcode, c1 code1 c2 code2 @dots{}}
|
||
@cindex hyphenation code (@code{hcode})
|
||
@cindex code, hyphenation (@code{hcode})
|
||
Set the hyphenation code of character @var{c1} to @var{code1}, that of
|
||
@var{c2} to @var{code2}, etc. A hyphenation code must be a single
|
||
input character (not a special character) other than a digit or a
|
||
space. Initially each lower-case letter (@samp{a}-@samp{z}) has its
|
||
hyphenation code set to itself, and each upper-case letter
|
||
(@samp{A}-@samp{Z}) has a hyphenation code which is the lower-case
|
||
version of itself.
|
||
|
||
This request is ignored if it has no parameter.
|
||
@endDefreq
|
||
|
||
@DefreqList {hym, [@Var{length}]}
|
||
@DefregListEnd {.hym}
|
||
@cindex hyphenation margin (@code{hym})
|
||
@cindex margin for hyphenation (@code{hym})
|
||
@cindex @code{ad} request, and hyphenation margin
|
||
Set the (right) hyphenation margin to @var{length}. If the current
|
||
adjustment mode is not @samp{b} or @samp{n}, the line is not
|
||
hyphenated if it is shorter than @var{length}. Without an argument,
|
||
the hyphenation margin is reset to its default value, which is@w{ }0.
|
||
The default scaling indicator for this request is @samp{m}. The
|
||
hyphenation margin is associated with the current environment
|
||
(@pxref{Environments}).
|
||
|
||
A negative argument resets the hyphenation margin to zero, emitting
|
||
a warning of type @samp{range}.
|
||
|
||
@cindex hyphenation margin register (@code{.hym})
|
||
The current hyphenation margin is available in the @code{.hym} read-only
|
||
number register.
|
||
@endDefreq
|
||
|
||
@DefreqList {hys, [@Var{hyphenation_space}]}
|
||
@DefregListEnd {.hys}
|
||
@cindex hyphenation space (@code{hys})
|
||
@cindex @code{ad} request, and hyphenation space
|
||
Set the hyphenation space to @var{hyphenation_space}. If the current
|
||
adjustment mode is @samp{b} or @samp{n}, don't hyphenate the line
|
||
if it can be justified by adding no more than @var{hyphenation_space}
|
||
extra space to each word space. Without argument, the hyphenation
|
||
space is set to its default value, which is@w{ }0. The default
|
||
scaling indicator for this request is @samp{m}. The hyphenation
|
||
space is associated with the current environment
|
||
(@pxref{Environments}).
|
||
|
||
A negative argument resets the hyphenation space to zero, emitting a
|
||
warning of type @samp{range}.
|
||
|
||
@cindex hyphenation space register (@code{.hys})
|
||
The current hyphenation space is available in the @code{.hys} read-only
|
||
number register.
|
||
@endDefreq
|
||
|
||
@Defreq {shc, [@Var{glyph}]}
|
||
@cindex soft hyphen character, setting (@code{shc})
|
||
@cindex character, soft hyphen, setting (@code{shc})
|
||
@cindex glyph, soft hyphen (@code{hy})
|
||
@cindex soft hyphen glyph (@code{hy})
|
||
@cindex @code{char} request, and soft hyphen character
|
||
@cindex @code{tr} request, and soft hyphen character
|
||
Set the @dfn{soft hyphen character} to @var{glyph}.@footnote{@dfn{Soft
|
||
hyphen character} is a misnomer since it is an output glyph.} If the
|
||
argument is omitted, the soft hyphen character is set to the default
|
||
glyph @code{\(hy} (this is the start-up value of @code{gtroff} also).
|
||
The soft hyphen character is the glyph that is inserted when a word is
|
||
hyphenated at a line break. If the soft hyphen character does not
|
||
exist in the font of the character immediately preceding a potential
|
||
break point, then the line is not broken at that point. Neither
|
||
definitions (specified with the @code{char} request) nor translations
|
||
(specified with the @code{tr} request) are considered when finding the
|
||
soft hyphen character.
|
||
@endDefreq
|
||
|
||
@DefreqList {hla, language}
|
||
@DefregListEnd {.hla}
|
||
@cindex @code{hpf} request, and hyphenation language
|
||
@cindex @code{hw} request, and hyphenation language
|
||
@pindex troffrc
|
||
@pindex troffrc-end
|
||
Set the current hyphenation language to the string @var{language}.
|
||
Hyphenation exceptions specified with the @code{hw} request and
|
||
hyphenation patterns specified with the @code{hpf} and @code{hpfa}
|
||
requests are both associated with the current hyphenation language.
|
||
The @code{hla} request is usually invoked by the @file{troffrc} or the
|
||
@file{troffrc-end} files; @file{troffrc} sets the default language to
|
||
@samp{us}.
|
||
|
||
@cindex hyphenation language register (@code{.hla})
|
||
The current hyphenation language is available as a string in the
|
||
read-only number register @samp{.hla}.
|
||
|
||
@Example
|
||
.ds curr_language \n[.hla]
|
||
\*[curr_language]
|
||
@result{} us
|
||
@endExample
|
||
@endDefreq
|
||
|
||
|
||
@c =====================================================================
|
||
|
||
@node Manipulating Spacing, Tabs and Fields, Manipulating Hyphenation, gtroff Reference
|
||
@section Manipulating Spacing
|
||
@cindex manipulating spacing
|
||
@cindex spacing, manipulating
|
||
|
||
@Defreq {sp, [@Var{distance}]}
|
||
Space downwards @var{distance}. With no argument it advances 1@w{
|
||
}line. A negative argument causes @code{gtroff} to move up the page
|
||
the specified distance. If the argument is preceded by a @samp{|}
|
||
then @code{gtroff} moves that distance from the top of the page. This
|
||
request causes a line break. The default scaling indicator is @samp{v}.
|
||
@endDefreq
|
||
|
||
@DefreqList {ls, [@Var{nnn}]}
|
||
@DefregListEnd {.L}
|
||
@cindex double-spacing (@code{ls})
|
||
Output @w{@var{nnn}@minus{}1} blank lines after each line of text.
|
||
With no argument, @code{gtroff} uses the previous value before the
|
||
last @code{ls} call.
|
||
|
||
@Example
|
||
.ls 2 \" This causes double-spaced output
|
||
.ls 3 \" This causes triple-spaced output
|
||
.ls \" Again double-spaced
|
||
@endExample
|
||
|
||
The line spacing is associated with the current environment
|
||
(@pxref{Environments}).
|
||
|
||
@cindex line spacing register (@code{.L})
|
||
The read-only number register @code{.L} contains the current line
|
||
spacing setting.
|
||
@endDefreq
|
||
|
||
@xref{Changing Type Sizes}, for the requests @code{vs} and @code{pvs}
|
||
as alternatives to @code{ls}.
|
||
|
||
@DefescList {\\x, ', spacing, '}
|
||
@DefregListEnd {.a}
|
||
Sometimes, extra vertical spacing is only needed occasionally, e.g.@:
|
||
to allow space for a tall construct (like an equation). The @code{\x}
|
||
escape does this. The escape is given a numerical argument, usually
|
||
enclosed in quotes (like @samp{\x'3p'}); the default scaling indicator
|
||
is @samp{v}. If this number is positive extra vertical space is
|
||
inserted below the current line. A negative number adds space above.
|
||
If this escape is used multiple times on the same line, the maximum of
|
||
the values is used.
|
||
|
||
@xref{Escapes}, for details on parameter delimiting characters.
|
||
|
||
@cindex extra post-vertical line space register (@code{.a})
|
||
The @code{.a} read-only number register contains the most recent
|
||
(nonnegative) extra vertical line space.
|
||
|
||
Using @code{\x} can be necessary in combination with the @code{\b}
|
||
escape, as the following example shows.
|
||
|
||
@Example
|
||
This is a test with the \[rs]b escape.
|
||
.br
|
||
This is a test with the \[rs]b escape.
|
||
.br
|
||
This is a test with \b'xyz'\x'-1m'\x'1m'.
|
||
.br
|
||
This is a test with the \[rs]b escape.
|
||
.br
|
||
This is a test with the \[rs]b escape.
|
||
@endExample
|
||
|
||
@noindent
|
||
produces
|
||
|
||
@Example
|
||
This is a test with the \b escape.
|
||
This is a test with the \b escape.
|
||
x
|
||
This is a test with y.
|
||
z
|
||
This is a test with the \b escape.
|
||
This is a test with the \b escape.
|
||
@endExample
|
||
@endDefesc
|
||
|
||
@DefreqList {ns, }
|
||
@DefreqItem {rs, }
|
||
@DefregListEnd {.ns}
|
||
@cindex @code{sp} request, and no-space mode
|
||
@cindex no-space mode (@code{ns})
|
||
@cindex mode, no-space (@code{ns})
|
||
@cindex blank lines, disabling
|
||
@cindex lines, blank, disabling
|
||
Enable @dfn{no-space mode}. In this mode, spacing (either via
|
||
@code{sp} or via blank lines) is disabled. The @code{bp} request to
|
||
advance to the next page is also disabled, except if it is accompanied
|
||
by a page number (see @ref{Page Control}, for more information). This
|
||
mode ends when actual text is output or the @code{rs} request is
|
||
encountered which ends no-space mode. The read-only number register
|
||
@code{.ns} is set to@w{ }1 as long as no-space mode is active.
|
||
|
||
This request is useful for macros that conditionally
|
||
insert vertical space before the text starts
|
||
(for example, a paragraph macro could insert some space
|
||
except when it is the first paragraph after a section header).
|
||
@endDefreq
|
||
|
||
|
||
@c =====================================================================
|
||
|
||
@node Tabs and Fields, Character Translations, Manipulating Spacing, gtroff Reference
|
||
@section Tabs and Fields
|
||
@cindex tabs, and fields
|
||
@cindex fields, and tabs
|
||
|
||
@cindex @acronym{EBCDIC} encoding of a tab
|
||
A tab character (@acronym{ASCII} char@w{ }9, @acronym{EBCDIC} char@w{
|
||
}5) causes a horizontal movement to the next tab stop (much
|
||
like it did on a typewriter).
|
||
|
||
@Defesc {\\t, , , }
|
||
@cindex tab character, non-interpreted (@code{\t})
|
||
@cindex character, tab, non-interpreted (@code{\t})
|
||
This escape is a non-interpreted tab character. In copy mode
|
||
(@pxref{Copy-in Mode}), @code{\t} is the same as a real tab character.
|
||
@endDefesc
|
||
|
||
@DefreqList {ta, [@Var{n1} @Var{n2} @dots{} @Var{nn} @t{T} @Var{r1} @Var{r2} @dots{} @Var{rn}]}
|
||
@DefregListEnd {.tabs}
|
||
Change tab stop positions. This request takes a series of tab
|
||
specifiers as arguments (optionally divided into two groups with the
|
||
letter @samp{T}) which indicate where each tab stop is to be
|
||
(overriding any previous settings).
|
||
|
||
Tab stops can be specified absolutely, i.e., as the distance from the
|
||
left margin. For example, the following sets 6@w{ }tab stops every
|
||
one inch.
|
||
|
||
@Example
|
||
.ta 1i 2i 3i 4i 5i 6i
|
||
@endExample
|
||
|
||
Tab stops can also be specified using a leading @samp{+}
|
||
which means that the specified tab stop is set relative to
|
||
the previous tab stop. For example, the following is equivalent to the
|
||
previous example.
|
||
|
||
@Example
|
||
.ta 1i +1i +1i +1i +1i +1i
|
||
@endExample
|
||
|
||
@code{gtroff} supports an extended syntax to specify repeat values after
|
||
the @samp{T} mark (these values are always taken as relative) -- this is
|
||
the usual way to specify tabs set at equal intervals. The following is,
|
||
yet again, the same as the previous examples. It does even more since
|
||
it defines an infinite number of tab stops separated by one inch.
|
||
|
||
@Example
|
||
.ta T 1i
|
||
@endExample
|
||
|
||
Now we are ready to interpret the full syntax given at the beginning:
|
||
Set tabs at positions @var{n1}, @var{n2}, @dots{}, @var{nn} and then set
|
||
tabs at @var{nn}+@var{r1}, @var{nn}+@var{r2}, @dots{}, @var{nn}+@var{rn}
|
||
and then at @var{nn}+@var{rn}+@var{r1}, @var{nn}+@var{rn}+@var{r2},
|
||
@dots{}, @var{nn}+@var{rn}+@var{rn}, and so on.
|
||
|
||
Example: @samp{4c +6c T 3c 5c 2c} is equivalent to @samp{4c 10c 13c 18c
|
||
20c 23c 28c 30c @dots{}}.
|
||
|
||
The material in each tab column (i.e., the column between two tab stops)
|
||
may be justified to the right or left or centered in the column. This
|
||
is specified by appending @samp{R}, @samp{L}, or @samp{C} to the tab
|
||
specifier. The default justification is @samp{L}. Example:
|
||
|
||
@Example
|
||
.ta 1i 2iC 3iR
|
||
@endExample
|
||
|
||
Some notes:
|
||
|
||
@itemize @bullet
|
||
@item
|
||
The default unit of the @code{ta} request is @samp{m}.
|
||
|
||
@item
|
||
A tab stop is converted into a non-breakable horizontal movement which
|
||
can be neither stretched nor squeezed. For example,
|
||
|
||
@Example
|
||
.ds foo a\tb\tc
|
||
.ta T 5i
|
||
\*[foo]
|
||
@endExample
|
||
|
||
@noindent
|
||
creates a single line which is a bit longer than 10@w{ }inches (a string
|
||
is used to show exactly where the tab characters are). Now consider the
|
||
following:
|
||
|
||
@Example
|
||
.ds bar a\tb b\tc
|
||
.ta T 5i
|
||
\*[bar]
|
||
@endExample
|
||
|
||
@noindent
|
||
@code{gtroff} first converts the tab stops of the line into unbreakable
|
||
horizontal movements, then splits the line after the second @samp{b}
|
||
(assuming a sufficiently short line length). Usually, this isn't what
|
||
the user wants.
|
||
|
||
@item
|
||
Superfluous tabs (i.e., tab characters which do not correspond to a tab
|
||
stop) are ignored except the first one which delimits the characters
|
||
belonging to the last tab stop for right-justifying or centering.
|
||
Consider the following example
|
||
|
||
@Example
|
||
.ds Z foo\tbar\tfoo
|
||
.ds ZZ foo\tbar\tfoobar
|
||
.ds ZZZ foo\tbar\tfoo\tbar
|
||
.ta 2i 4iR
|
||
\*[Z]
|
||
.br
|
||
\*[ZZ]
|
||
.br
|
||
\*[ZZZ]
|
||
.br
|
||
@endExample
|
||
|
||
@noindent
|
||
which produces the following output:
|
||
|
||
@Example
|
||
foo bar foo
|
||
foo bar foobar
|
||
foo bar foobar
|
||
@endExample
|
||
|
||
@noindent
|
||
The first line right-justifies the second `foo' relative to the tab
|
||
stop. The second line right-justifies `foobar'. The third line finally
|
||
right-justifies only `foo' because of the additional tab character which
|
||
marks the end of the string belonging to the last defined tab stop.
|
||
|
||
@item
|
||
Tab stops are associated with the current environment
|
||
(@pxref{Environments}).
|
||
|
||
@item
|
||
Calling @code{ta} without an argument removes all tab stops.
|
||
|
||
@item
|
||
@cindex tab stops, for TTY output devices
|
||
The start-up value of @code{gtroff} is @w{@samp{T 0.5i}} in troff mode
|
||
and @w{@samp{T 0.8i}} in nroff mode (the latter is done with an
|
||
explicit call to the @code{ta} request in the file @file{tty.tmac}.
|
||
@end itemize
|
||
|
||
@cindex tab settings register (@code{.tabs})
|
||
The read-only number register @code{.tabs} contains a string
|
||
representation of the current tab settings suitable for use as an
|
||
argument to the @code{ta} request.
|
||
|
||
@Example
|
||
.ds tab-string \n[.tabs]
|
||
\*[tab-string]
|
||
@result{} T120u
|
||
@endExample
|
||
|
||
@cindex @code{.S} register, Plan@w{ }9 alias for @code{.tabs}
|
||
@cindex @code{.tabs} register, Plan@w{ }9 alias (@code{.S})
|
||
The @code{troff} version of the Plan@w{ }9 operating system uses
|
||
register @code{.S} for the same purpose.
|
||
@endDefreq
|
||
|
||
@Defreq {tc, [@Var{fill-glyph}]}
|
||
@cindex tab repetition character (@code{tc})
|
||
@cindex character, tab repetition (@code{tc})
|
||
@cindex glyph, tab repetition (@code{tc})
|
||
Normally @code{gtroff} fills the space to the next tab stop with
|
||
whitespace. This can be changed with the @code{tc} request. With no
|
||
argument @code{gtroff} reverts to using whitespace, which is the
|
||
default. The value of this @dfn{tab repetition character} is
|
||
associated with the current environment
|
||
(@pxref{Environments}).@footnote{@dfn{Tab repetition character} is a
|
||
misnomer since it is an output glyph.}
|
||
@endDefreq
|
||
|
||
@DefreqList {linetabs, n}
|
||
@DefregListEnd {.linetabs}
|
||
@cindex tab, line-tabs mode
|
||
@cindex line-tabs mode
|
||
@cindex mode, line-tabs
|
||
If @var{n} is missing or not zero, enable @dfn{line-tabs} mode,
|
||
or disable it otherwise (the default).
|
||
In line-tabs mode, @code{gtroff} computes tab distances
|
||
relative to the (current) output line instead of the input line.
|
||
|
||
For example, the following code:
|
||
|
||
@Example
|
||
.ds x a\t\c
|
||
.ds y b\t\c
|
||
.ds z c
|
||
.ta 1i 3i
|
||
\*x
|
||
\*y
|
||
\*z
|
||
@endExample
|
||
|
||
@noindent
|
||
in normal mode, results in the output
|
||
|
||
@Example
|
||
a b c
|
||
@endExample
|
||
|
||
@noindent
|
||
in line-tabs mode, the same code outputs
|
||
|
||
@Example
|
||
a b c
|
||
@endExample
|
||
|
||
Line-tabs mode is associated with the current environment.
|
||
The read-only register @code{.linetabs} is set to@w{ }1 if in line-tabs
|
||
mode, and 0 in normal mode.
|
||
@endDefreq
|
||
|
||
@menu
|
||
* Leaders::
|
||
* Fields::
|
||
@end menu
|
||
|
||
@c ---------------------------------------------------------------------
|
||
|
||
@node Leaders, Fields, Tabs and Fields, Tabs and Fields
|
||
@subsection Leaders
|
||
@cindex leaders
|
||
|
||
Sometimes it may may be desirable to use the @code{tc} request to fill a
|
||
particular tab stop with a given glyph (for example dots in a table
|
||
of contents), but also normal tab stops on the rest of the line. For
|
||
this @code{gtroff} provides an alternate tab mechanism, called
|
||
@dfn{leaders} which does just that.
|
||
|
||
@cindex leader character
|
||
A leader character (character code@w{ }1) behaves similarly to a tab
|
||
character: It moves to the next tab stop. The only difference is that
|
||
for this movement, the fill glyph defaults to a period character and
|
||
not to space.
|
||
|
||
@Defesc {\\a, , , }
|
||
@cindex leader character, non-interpreted (@code{\a})
|
||
@cindex character, leader, non-interpreted (@code{\a})
|
||
This escape is a non-interpreted leader character. In copy mode
|
||
(@pxref{Copy-in Mode}), @code{\a} is the same as a real leader
|
||
character.
|
||
@endDefesc
|
||
|
||
@Defreq {lc, [@Var{fill-glyph}]}
|
||
@cindex leader repetition character (@code{lc})
|
||
@cindex character, leader repetition (@code{lc})
|
||
@cindex glyph, leader repetition (@code{lc})
|
||
Declare the @dfn{leader repetition character}.@footnote{@dfn{Leader
|
||
repetition character} is a misnomer since it is an output glyph.}
|
||
Without an argument, leaders act the same as tabs (i.e., using
|
||
whitespace for filling). @code{gtroff}'s start-up value is a dot
|
||
(@samp{.}). The value of the leader repetition character is
|
||
associated with the current environment (@pxref{Environments}).
|
||
@endDefreq
|
||
|
||
@cindex table of contents
|
||
@cindex contents, table of
|
||
For a table of contents, to name an example, tab stops may be defined so
|
||
that the section number is one tab stop, the title is the second with
|
||
the remaining space being filled with a line of dots, and then the page
|
||
number slightly separated from the dots.
|
||
|
||
@Example
|
||
.ds entry 1.1\tFoo\a\t12
|
||
.lc .
|
||
.ta 1i 5i +.25i
|
||
\*[entry]
|
||
@endExample
|
||
|
||
@noindent
|
||
This produces
|
||
|
||
@Example
|
||
1.1 Foo.......................................... 12
|
||
@endExample
|
||
|
||
@c ---------------------------------------------------------------------
|
||
|
||
@node Fields, , Leaders, Tabs and Fields
|
||
@subsection Fields
|
||
@cindex fields
|
||
|
||
@cindex field delimiting character (@code{fc})
|
||
@cindex delimiting character, for fields (@code{fc})
|
||
@cindex character, field delimiting (@code{fc})
|
||
@cindex field padding character (@code{fc})
|
||
@cindex padding character, for fields (@code{fc})
|
||
@cindex character, field padding (@code{fc})
|
||
@dfn{Fields} are a more general way of laying out tabular data. A field
|
||
is defined as the data between a pair of @dfn{delimiting characters}.
|
||
It contains substrings which are separated by @dfn{padding characters}.
|
||
The width of a field is the distance on the @emph{input} line from the
|
||
position where the field starts to the next tab stop. A padding
|
||
character inserts stretchable space similar to @TeX{}'s @code{\hss}
|
||
command (thus it can even be negative) to make the sum of all substring
|
||
lengths plus the stretchable space equal to the field width. If more
|
||
than one padding character is inserted, the available space is evenly
|
||
distributed among them.
|
||
|
||
@Defreq {fc, [@Var{delim-char} [@Var{padding-char}]]}
|
||
Define a delimiting and a padding character for fields. If the latter
|
||
is missing, the padding character defaults to a space character. If
|
||
there is no argument at all, the field mechanism is disabled (which is
|
||
the default). Note that contrary to e.g.@: the tab repetition
|
||
character, delimiting and padding characters are @emph{not} associated
|
||
to the current environment (@pxref{Environments}).
|
||
|
||
Example:
|
||
|
||
@Example
|
||
.fc # ^
|
||
.ta T 3i
|
||
#foo^bar^smurf#
|
||
.br
|
||
#foo^^bar^smurf#
|
||
@endExample
|
||
|
||
@noindent
|
||
and here the result:
|
||
|
||
@Example
|
||
foo bar smurf
|
||
foo bar smurf
|
||
@endExample
|
||
@endDefreq
|
||
|
||
|
||
@c =====================================================================
|
||
|
||
@node Character Translations, Troff and Nroff Mode, Tabs and Fields, gtroff Reference
|
||
@section Character Translations
|
||
@cindex character translations
|
||
@cindex translations of characters
|
||
|
||
@cindex control character, changing (@code{cc})
|
||
@cindex character, control, changing (@code{cc})
|
||
@cindex no-break control character, changing (@code{c2})
|
||
@cindex character, no-break control, changing (@code{c2})
|
||
@cindex control character, no-break, changing (@code{c2})
|
||
The control character (@samp{.}) and the no-break control character
|
||
(@samp{'}) can be changed with the @code{cc} and @code{c2} requests,
|
||
respectively.
|
||
|
||
@Defreq {cc, [@Var{c}]}
|
||
Set the control character to@w{ }@var{c}. With no argument the default
|
||
control character @samp{.} is restored. The value of the control
|
||
character is associated with the current environment
|
||
(@pxref{Environments}).
|
||
@endDefreq
|
||
|
||
@Defreq {c2, [@Var{c}]}
|
||
Set the no-break control character to@w{ }@var{c}. With no argument the
|
||
default control character @samp{'} is restored. The value of the
|
||
no-break control character is associated with the current environment
|
||
(@pxref{Environments}).
|
||
@endDefreq
|
||
|
||
@Defreq {eo, }
|
||
@cindex disabling @code{\} (@code{eo})
|
||
@cindex @code{\}, disabling (@code{eo})
|
||
Disable the escape mechanism completely. After executing this
|
||
request, the backslash character @samp{\} no longer starts an escape
|
||
sequence.
|
||
|
||
This request can be very helpful in writing macros since it is not
|
||
necessary then to double the escape character. Here an example:
|
||
|
||
@Example
|
||
.\" This is a simplified version of the
|
||
.\" .BR request from the man macro package
|
||
.eo
|
||
.de BR
|
||
. ds result \&
|
||
. while (\n[.$] >= 2) \@{\
|
||
. as result \fB\$1\fR\$2
|
||
. shift 2
|
||
. \@}
|
||
. if \n[.$] .as result \fB\$1
|
||
\*[result]
|
||
. ft R
|
||
..
|
||
.ec
|
||
@endExample
|
||
@endDefreq
|
||
|
||
@Defreq {ec, [@Var{c}]}
|
||
@cindex escape character, changing (@code{ec})
|
||
@cindex character, escape, changing (@code{ec})
|
||
Set the escape character to@w{ }@var{c}. With no argument the default
|
||
escape character @samp{\} is restored. It can be also used to
|
||
re-enable the escape mechanism after an @code{eo} request.
|
||
|
||
Note that changing the escape character globally will likely break
|
||
macro packages since @code{gtroff} has no mechanism to `intern' macros,
|
||
i.e., to convert a macro definition into an internal form which is
|
||
independent of its representation (@TeX{} has this mechanism).
|
||
If a macro is called, it is executed literally.
|
||
@endDefreq
|
||
|
||
@DefreqList {ecs, }
|
||
@DefreqListEnd {ecr, }
|
||
The @code{ecs} request saves the current escape character
|
||
in an internal register.
|
||
Use this request in combination with the @code{ec} request to
|
||
temporarily change the escape character.
|
||
|
||
The @code{ecr} request restores the escape character
|
||
saved with @code{ecs}.
|
||
Without a previous call to @code{ecs}, this request
|
||
sets the escape character to @code{\}.
|
||
@endDefreq
|
||
|
||
@DefescList {\\\\, , , }
|
||
@DefescItem {\\e, , , }
|
||
@DefescListEnd {\\E, , , }
|
||
Print the current escape character (which is the backslash character
|
||
@samp{\} by default).
|
||
|
||
@code{\\} is a `delayed' backslash; more precisely, it is the default
|
||
escape character followed by a backslash, which no longer has special
|
||
meaning due to the leading escape character. It is @emph{not} an escape
|
||
sequence in the usual sense! In any unknown escape sequence
|
||
@code{\@var{X}} the escape character is ignored and @var{X} is printed.
|
||
But if @var{X} is equal to the current escape character, no warning is
|
||
emitted.
|
||
|
||
As a consequence, only at top-level or in a diversion a backslash glyph is
|
||
printed; in copy-in mode, it expands to a single backslash which then
|
||
combines with the following character to an escape sequence.
|
||
|
||
The @code{\E} escape differs from @code{\e} by printing an escape
|
||
character that is not interpreted in copy mode.
|
||
Use this to define strings with escapes that work
|
||
when used in copy mode (for example, as a macro argument).
|
||
The following example defines strings to begin and end
|
||
a superscript:
|
||
|
||
@Example
|
||
.ds @{ \v'-.3m'\s'\Es[.s]*60/100'
|
||
.ds @} \s0\v'.3m'
|
||
@endExample
|
||
|
||
Another example to demonstrate the differences between the various escape
|
||
sequences, using a strange escape character, @samp{-}.
|
||
|
||
@Example
|
||
.ec -
|
||
.de xxx
|
||
--A'123'
|
||
..
|
||
.xxx
|
||
@result{} -A'foo'
|
||
@endExample
|
||
|
||
@noindent
|
||
The result is surprising for most users, expecting @samp{1} since
|
||
@samp{foo} is a valid identifier. What has happened? As mentioned
|
||
above, the leading escape character makes the following character
|
||
ordinary. Written with the default escape character the sequence
|
||
@samp{--} becomes @samp{\-} -- this is the minus sign.
|
||
|
||
If the escape character followed by itself is a valid escape sequence,
|
||
only @code{\E} yields the expected result:
|
||
|
||
@Example
|
||
.ec -
|
||
.de xxx
|
||
-EA'123'
|
||
..
|
||
.xxx
|
||
@result{} 1
|
||
@endExample
|
||
@endDefesc
|
||
|
||
@Defesc {\\., , , }
|
||
Similar to @code{\\}, the sequence @code{\.} isn't a real escape sequence.
|
||
As before, a warning message is suppressed if the escape character is
|
||
followed by a dot, and the dot itself is printed.
|
||
|
||
@Example
|
||
.de foo
|
||
. nop foo
|
||
.
|
||
. de bar
|
||
. nop bar
|
||
\\..
|
||
.
|
||
..
|
||
.foo
|
||
.bar
|
||
@result{} foo bar
|
||
@endExample
|
||
|
||
@noindent
|
||
The first backslash is consumed while the macro is read, and the second
|
||
is swallowed while exexuting macro @code{foo}.
|
||
@endDefesc
|
||
|
||
A @dfn{translation} is a mapping of an input character to an output
|
||
glyph. The mapping occurs at output time, i.e., the input character
|
||
gets assigned the metric information of the mapped output character
|
||
right before input tokens are converted to nodes (@pxref{Gtroff
|
||
Internals}, for more on this process).
|
||
|
||
@DefreqList {tr, @Var{a}@Var{b}@Var{c}@Var{d}@dots{}}
|
||
@DefreqListEnd {trin, @Var{a}@Var{b}@Var{c}@Var{d}@dots{}}
|
||
Translate character @var{a} to glyph@w{ }@var{b}, character @var{c} to
|
||
glyph@w{ }@var{d}, etc. If there is an odd number of arguments, the
|
||
last one is translated to an unstretchable space (@w{@samp{\ }}).
|
||
|
||
The @code{trin} request is identical to @code{tr},
|
||
but when you unformat a diversion with @code{asciify}
|
||
it ignores the translation.
|
||
@xref{Diversions}, for details about the @code{asciify} request.
|
||
|
||
Some notes:
|
||
|
||
@itemize @bullet
|
||
@item
|
||
@cindex @code{\(}, and translations
|
||
@cindex @code{\[}, and translations
|
||
@cindex @code{\'}, and translations
|
||
@cindex @code{\`}, and translations
|
||
@cindex @code{\-}, and translations
|
||
@cindex @code{\_}, and translations
|
||
@cindex @code{\C}, and translations
|
||
@cindex @code{\N}, and translations
|
||
@cindex @code{char} request, and translations
|
||
@cindex special characters
|
||
@cindex character, special
|
||
@cindex numbered glyph (@code{\N})
|
||
@cindex glyph, numbered (@code{\N})
|
||
Special characters (@code{\(@var{xx}}, @code{\[@var{xxx}]},
|
||
@code{\C'@var{xxx}'}, @code{\'}, @code{\`}, @code{\-}, @code{\_}),
|
||
glyphs defined with the @code{char} request, and numbered glyphs
|
||
(@code{\N'@var{xxx}'}) can be translated also.
|
||
|
||
@item
|
||
@cindex @code{\e}, and translations
|
||
The @code{\e} escape can be translated also.
|
||
|
||
@item
|
||
@cindex @code{\%}, and translations
|
||
@cindex @code{\~}, and translations
|
||
Characters can be mapped onto the @code{\%} and @code{\~} escapes (but
|
||
@code{\%} and @code{\~} can't be mapped onto another glyph).
|
||
|
||
@item
|
||
@cindex backspace character, and translations
|
||
@cindex character, backspace, and translations
|
||
@cindex leader character, and translations
|
||
@cindex character, leader, and translations
|
||
@cindex newline character, and translations
|
||
@cindex character, newline, and translations
|
||
@cindex tab character, and translations
|
||
@cindex character, tab, and translations
|
||
@cindex @code{\a}, and translations
|
||
@cindex @code{\t}, and translations
|
||
The following characters can't be translated: space (with one exception,
|
||
see below), backspace, newline, leader (and @code{\a}), tab (and
|
||
@code{\t}).
|
||
|
||
@item
|
||
@cindex @code{shc} request, and translations
|
||
Translations are not considered for finding the soft hyphen character
|
||
set with the @code{shc} request.
|
||
|
||
@item
|
||
@cindex @code{\&}, and translations
|
||
The pair @samp{@var{c}\&} (this is an arbitrary character@w{
|
||
}@var{c} followed by the zero width space character) maps this
|
||
character to nothing.
|
||
|
||
@Example
|
||
.tr a\&
|
||
foo bar
|
||
@result{} foo br
|
||
@endExample
|
||
|
||
@noindent
|
||
It is even possible to map the space character to nothing:
|
||
|
||
@Example
|
||
.tr aa \&
|
||
foo bar
|
||
@result{} foobar
|
||
@endExample
|
||
|
||
@noindent
|
||
As shown in the example, the space character can't be the first
|
||
character/glyph pair as an argument of @code{tr}. Additionally, it is
|
||
not possible to map the space character to any other glyph; requests
|
||
like @w{@samp{.tr aa x}} undo @w{@samp{.tr aa \&}} instead.
|
||
|
||
If justification is active, lines are justified in spite of the
|
||
`empty' space character (but there is no minimal distance, i.e.@: the
|
||
space character, between words).
|
||
|
||
@item
|
||
After an output glyph has been constructed (this happens at the
|
||
moment immediately before the glyph is appended to an output
|
||
glyph list, either by direct output, in a macro, diversion, or
|
||
string), it is no longer affected by @code{tr}.
|
||
|
||
@item
|
||
Translating character to glyphs where one of them or both are
|
||
undefined is possible also; @code{tr} does not check whether the
|
||
entities in its argument do exist.
|
||
|
||
@xref{Gtroff Internals}.
|
||
|
||
@item
|
||
@code{troff} no longer has a hard-coded dependency on @w{Latin-1};
|
||
all @code{char@var{XXX}} entities have been removed from the font
|
||
description files. This has a notable consequence which shows up in
|
||
warnings like @code{can't find character with input code @var{XXX}}
|
||
if the @code{tr} request isn't handled properly.
|
||
|
||
Consider the following translation:
|
||
|
||
@Example
|
||
.tr @'e@'E
|
||
@endExample
|
||
|
||
@noindent
|
||
This maps input character @code{@'e} onto glyph @code{@'E}, which is
|
||
identical to glyph @code{char201}. But this glyph intentionally
|
||
doesn't exist! Instead, @code{\[char201]} is treated as an input
|
||
character entity and is by default mapped onto @code{\['E]}, and
|
||
@code{gtroff} doesn't handle translations of translations.
|
||
|
||
The right way to write the above translation is
|
||
|
||
@Example
|
||
.tr @'e\['E]
|
||
@endExample
|
||
|
||
@noindent
|
||
With other words, the first argument of @code{tr} should be an input
|
||
character or entity, and the second one a glyph entity.
|
||
|
||
@item
|
||
Without an argument, the @code{tr} request is ignored.
|
||
@end itemize
|
||
@endDefreq
|
||
|
||
@Defreq {trnt, @Var{a}@Var{b}@Var{c}@Var{d}@dots{}}
|
||
@cindex @code{\!}, and @code{trnt}
|
||
@code{trnt} is the same as the @code{tr} request except that the
|
||
translations do not apply to text that is transparently throughput
|
||
into a diversion with @code{\!}. @xref{Diversions}, for more
|
||
information.
|
||
|
||
For example,
|
||
|
||
@Example
|
||
.tr ab
|
||
.di x
|
||
\!.tm a
|
||
.di
|
||
.x
|
||
@endExample
|
||
|
||
@noindent
|
||
prints @samp{b} to the standard error stream; if @code{trnt} is used
|
||
instead of @code{tr} it prints @samp{a}.
|
||
@endDefreq
|
||
|
||
|
||
@c =====================================================================
|
||
|
||
@node Troff and Nroff Mode, Line Layout, Character Translations, gtroff Reference
|
||
@section Troff and Nroff Mode
|
||
@cindex troff mode
|
||
@cindex mode, troff
|
||
@cindex nroff mode
|
||
@cindex mode, nroff
|
||
|
||
Originally, @code{nroff} and @code{troff} were two separate programs,
|
||
the former for TTY output, the latter for everything else. With GNU
|
||
@code{troff}, both programs are merged into one executable, sending
|
||
its output to a device driver (@code{grotty} for TTY devices,
|
||
@code{grops} for @sc{PostScript}, etc.) which interprets the
|
||
intermediate output of @code{gtroff}. For @acronym{UNIX} @code{troff}
|
||
it makes sense to talk about @dfn{Nroff mode} and @dfn{Troff mode}
|
||
since the differences are hardcoded. For GNU @code{troff}, this
|
||
distinction is not appropriate because @code{gtroff} simply takes the
|
||
information given in the font files for a particular device without
|
||
handling requests specially if a TTY output device is used.
|
||
|
||
Usually, a macro package can be used with all output devices.
|
||
Nevertheless, it is sometimes necessary to make a distinction between
|
||
TTY and non-TTY devices: @code{gtroff} provides two built-in
|
||
conditions @samp{n} and @samp{t} for the @code{if}, @code{ie}, and
|
||
@code{while} requests to decide whether @code{gtroff} shall behave
|
||
like @code{nroff} or like @code{troff}.
|
||
|
||
@Defreq {troff, }
|
||
@pindex troffrc
|
||
@pindex troffrc-end
|
||
Make the @samp{t} built-in condition true (and the @samp{n} built-in
|
||
condition false) for @code{if}, @code{ie}, and @code{while}
|
||
conditional requests. This is the default if @code{gtroff}
|
||
(@emph{not} @code{groff}) is started with the @option{-R} switch to
|
||
avoid loading of the start-up files @file{troffrc} and
|
||
@file{troffrc-end}. Without @option{-R}, @code{gtroff} stays in troff
|
||
mode if the output device is not a TTY (e.g.@: `ps').
|
||
@endDefreq
|
||
|
||
@Defreq {nroff, }
|
||
@pindex tty.tmac
|
||
Make the @samp{n} built-in condition true (and the @samp{t} built-in
|
||
condition false) for @code{if}, @code{ie}, and @code{while}
|
||
conditional requests. This is the default if @code{gtroff} uses a TTY
|
||
output device; the code for switching to nroff mode is in the file
|
||
@file{tty.tmac} which is loaded by the start-up file @code{troffrc}.
|
||
@endDefreq
|
||
|
||
@xref{Conditionals and Loops}, for more details on built-in
|
||
conditions.
|
||
|
||
|
||
@c =====================================================================
|
||
|
||
@node Line Layout, Line Control, Troff and Nroff Mode, gtroff Reference
|
||
@section Line Layout
|
||
@cindex line layout
|
||
@cindex layout, line
|
||
|
||
@cindex dimensions, line
|
||
@cindex line dimensions
|
||
The following drawing shows the dimensions which @code{gtroff} uses for
|
||
placing a line of output onto the page. They are labeled with the
|
||
request which manipulates each dimension.
|
||
|
||
@Example
|
||
-->| in |<--
|
||
|<-----------ll------------>|
|
||
+----+----+----------------------+----+
|
||
| : : : |
|
||
+----+----+----------------------+----+
|
||
-->| po |<--
|
||
|<--------paper width---------------->|
|
||
@endExample
|
||
|
||
@noindent
|
||
These dimensions are:
|
||
|
||
@ftable @code
|
||
@item po
|
||
@cindex left margin (@code{po})
|
||
@cindex margin, left (@code{po})
|
||
@cindex page offset (@code{po})
|
||
@cindex offset, page (@code{po})
|
||
@dfn{Page offset} -- this is the leftmost position of text on the final
|
||
output, defining the @dfn{left margin}.
|
||
|
||
@item in
|
||
@cindex indentation (@code{in})
|
||
@cindex line indentation (@code{in})
|
||
@dfn{Indentation} -- this is the distance from the left margin where
|
||
text is printed.
|
||
|
||
@item ll
|
||
@cindex line length (@code{ll})
|
||
@cindex length of line (@code{ll})
|
||
@dfn{Line length} -- this is the distance from the left margin to right
|
||
margin.
|
||
@end ftable
|
||
|
||
A simple demonstration:
|
||
|
||
@Example
|
||
.ll 3i
|
||
This is text without indentation.
|
||
The line length has been set to 3\~inch.
|
||
.in +.5i
|
||
.ll -.5i
|
||
Now the left and right margins are both increased.
|
||
.in
|
||
.ll
|
||
Calling .in and .ll without parameters restore
|
||
the previous values.
|
||
@endExample
|
||
|
||
Result:
|
||
|
||
@Example
|
||
This is text without indenta-
|
||
tion. The line length has
|
||
been set to 3 inch.
|
||
Now the left and
|
||
right margins are
|
||
both increased.
|
||
Calling .in and .ll without
|
||
parameters restore the previ-
|
||
ous values.
|
||
@endExample
|
||
|
||
@DefreqList {po, [@Var{offset}]}
|
||
@DefreqItem {po, @t{+}@Var{offset}}
|
||
@DefreqItem {po, @t{-}@Var{offset}}
|
||
@DefregListEnd {.o}
|
||
@pindex troffrc
|
||
Set horizontal page offset to @var{offset} (or increment or decrement
|
||
the current value by @var{offset}). Note that this request does not
|
||
cause a break, so changing the page offset in the middle of text being
|
||
filled may not yield the expected result. The initial value is
|
||
1@dmn{i}. For TTY output devices, it is set to 0 in the startup file
|
||
@file{troffrc}; the default scaling indicator is @samp{m} (and
|
||
not @samp{v} as incorrectly documented in the original
|
||
@acronym{UNIX} troff manual).
|
||
|
||
The current page offset can be found in the read-only number register
|
||
@samp{.o}.
|
||
|
||
If @code{po} is called without an argument, the page offset is reset to
|
||
the previous value before the last call to @code{po}.
|
||
|
||
@Example
|
||
.po 3i
|
||
\n[.o]
|
||
@result{} 720
|
||
.po -1i
|
||
\n[.o]
|
||
@result{} 480
|
||
.po
|
||
\n[.o]
|
||
@result{} 720
|
||
@endExample
|
||
@endDefreq
|
||
|
||
@DefreqList {in, [@Var{indent}]}
|
||
@DefreqItem {in, @t{+}@Var{indent}}
|
||
@DefreqItem {in, @t{-}@Var{indent}}
|
||
@DefregListEnd {.i}
|
||
Set indentation to @var{indent} (or increment or decrement the
|
||
current value by @var{indent}). This request causes a break.
|
||
Initially, there is no indentation.
|
||
|
||
If @code{in} is called without an argument, the indentation is reset to
|
||
the previous value before the last call to @code{in}. The default
|
||
scaling indicator is @samp{m}.
|
||
|
||
The indentation is associated with the current environment
|
||
(@pxref{Environments}).
|
||
|
||
If a negative indentation value is specified (which is not allowed),
|
||
@code{gtroff} emits a warning of type @samp{range} and sets the
|
||
indentation to zero.
|
||
|
||
The effect of @code{in} is delayed until a partially collected line (if
|
||
it exists) is output. A temporary indent value is reset to zero also.
|
||
|
||
The current indentation (as set by @code{in}) can be found in the
|
||
read-only number register @samp{.i}.
|
||
@endDefreq
|
||
|
||
@DefreqList {ti, offset}
|
||
@DefreqItem {ti, @t{+}@Var{offset}}
|
||
@DefreqItem {ti, @t{-}@Var{offset}}
|
||
@DefregListEnd {.in}
|
||
Temporarily indent the next output line by @var{offset}. If an
|
||
increment or decrement value is specified, adjust the temporary
|
||
indentation relative to the value set by the @code{in} request.
|
||
|
||
This request causes a break; its value is associated with the current
|
||
environment (@pxref{Environments}). The default scaling indicator
|
||
is @samp{m}. A call of @code{ti} without an argument is ignored.
|
||
|
||
If the total indentation value is negative (which is not allowed),
|
||
@code{gtroff} emits a warning of type @samp{range} and sets the
|
||
temporary indentation to zero. `Total indentation' is either
|
||
@var{offset} if specified as an absolute value, or the temporary plus
|
||
normal indentation, if @var{offset} is given as a relative value.
|
||
|
||
The effect of @code{ti} is delayed until a partially collected line (if
|
||
it exists) is output.
|
||
|
||
The read-only number register @code{.in} is the indentation that applies
|
||
to the current output line.
|
||
|
||
The difference between @code{.i} and @code{.in} is that the latter takes
|
||
into account whether a partially collected line still uses the old
|
||
indentation value or a temporary indentation value is active.
|
||
@endDefreq
|
||
|
||
@DefreqList {ll, [@Var{length}]}
|
||
@DefreqItem {ll, @t{+}@Var{length}}
|
||
@DefreqItem {ll, @t{-}@Var{length}}
|
||
@DefregItem {.l}
|
||
@DefregListEnd {.ll}
|
||
Set the line length to @var{length} (or increment or decrement the
|
||
current value by @var{length}). Initially, the line length is set to
|
||
6.5@dmn{i}. The effect of @code{ll} is delayed until a partially
|
||
collected line (if it exists) is output. The default scaling
|
||
indicator is @samp{m}.
|
||
|
||
If @code{ll} is called without an argument, the line length is reset to
|
||
the previous value before the last call to @code{ll}. If a negative
|
||
line length is specified (which is not allowed), @code{gtroff} emits a
|
||
warning of type @samp{range} and sets the line length to zero.
|
||
|
||
The line length is associated with the current environment
|
||
(@pxref{Environments}).
|
||
|
||
@cindex line length register (@code{.l})
|
||
The current line length (as set by @code{ll}) can be found in the
|
||
read-only number register @samp{.l}. The read-only number register
|
||
@code{.ll} is the line length that applies to the current output line.
|
||
|
||
Similar to @code{.i} and @code{.in}, the difference between @code{.l}
|
||
and @code{.ll} is that the latter takes into account whether a partially
|
||
collected line still uses the old line length value.
|
||
@endDefreq
|
||
|
||
|
||
@c =====================================================================
|
||
|
||
@node Line Control, Page Layout, Line Layout, gtroff Reference
|
||
@section Line Control
|
||
@cindex line control
|
||
@cindex control, line
|
||
|
||
It is important to understand how @code{gtroff} handles input and output
|
||
lines.
|
||
|
||
Many escapes use positioning relative to the input line. For example,
|
||
this
|
||
|
||
@Example
|
||
This is a \h'|1.2i'test.
|
||
|
||
This is a
|
||
\h'|1.2i'test.
|
||
@endExample
|
||
|
||
@noindent
|
||
produces
|
||
|
||
@Example
|
||
This is a test.
|
||
|
||
This is a test.
|
||
@endExample
|
||
|
||
The main usage of this feature is to define macros which act exactly
|
||
at the place where called.
|
||
|
||
@Example
|
||
.\" A simple macro to underline a word
|
||
.de underline
|
||
. nop \\$1\l'|0\[ul]'
|
||
..
|
||
@endExample
|
||
|
||
@noindent
|
||
In the above example, @samp{|0} specifies a negative distance from the
|
||
current position (at the end of the just emitted argument @code{\$1}) back
|
||
to the beginning of the input line. Thus, the @samp{\l} escape draws a
|
||
line from right to left.
|
||
|
||
@cindex input line continuation (@code{\})
|
||
@cindex line, input, continuation (@code{\})
|
||
@cindex continuation, input line (@code{\})
|
||
@cindex output line, continuation (@code{\c})
|
||
@cindex line, output, continuation (@code{\c})
|
||
@cindex continuation, output line (@code{\c})
|
||
@cindex interrupted line
|
||
@cindex line, interrupted
|
||
@code{gtroff} makes a difference between input and output line
|
||
continuation; the latter is also called @dfn{interrupting} a line.
|
||
|
||
@DefescList {\\@key{RET}, , ,}
|
||
@DefescItem {\\c, , ,}
|
||
@DefregListEnd{.int}
|
||
Continue a line. @code{\@key{RET}} (this is a backslash at the end
|
||
of a line immediately followed by a newline) works on the input level,
|
||
suppressing the effects of the following newline in the input.
|
||
|
||
@Example
|
||
This is a \
|
||
.test
|
||
@result{} This is a .test
|
||
@endExample
|
||
|
||
The @samp{|} operator is also affected.
|
||
|
||
@cindex @code{\R}, after @code{\c}
|
||
@code{\c} works on the output level. Anything after this escape on the
|
||
same line is ignored, except @code{\R} which works as usual. Anything
|
||
before @code{\c} on the same line will be appended to the current partial
|
||
output line. The next non-command line after an interrupted line counts
|
||
as a new input line.
|
||
|
||
The visual results depend on whether no-fill mode is active.
|
||
|
||
@itemize @bullet
|
||
@item
|
||
@cindex @code{\c}, and no-fill mode
|
||
@cindex no-fill mode, and @code{\c}
|
||
@cindex mode, no-fill, and @code{\c}
|
||
If no-fill mode is active (using the @code{nf} request), the next input
|
||
text line after @code{\c} will be handled as a continuation of the same
|
||
input text line.
|
||
|
||
@Example
|
||
.nf
|
||
This is a \c
|
||
test.
|
||
@result{} This is a test.
|
||
@endExample
|
||
|
||
@item
|
||
@cindex @code{\c}, and fill mode
|
||
@cindex fill mode, and @code{\c}
|
||
@cindex mode, fill, and @code{\c}
|
||
If fill mode is active (using the @code{fi} request), a word interrupted
|
||
with @code{\c} will be continued with the text on the next input text line,
|
||
without an intervening space.
|
||
|
||
@Example
|
||
This is a te\c
|
||
st.
|
||
@result{} This is a test.
|
||
@endExample
|
||
@end itemize
|
||
|
||
Note that an intervening control line which causes a break is stronger
|
||
than @code{\c}, flushing out the current partial line in the usual way.
|
||
|
||
@cindex interrupted line register (@code{.int})
|
||
The @code{.int} register contains a positive value
|
||
if the last output line was interrupted with @code{\c}; this is
|
||
associated with the current environment (@pxref{Environments}).
|
||
|
||
@endDefesc
|
||
|
||
@c =====================================================================
|
||
|
||
@node Page Layout, Page Control, Line Control, gtroff Reference
|
||
@section Page Layout
|
||
@cindex page layout
|
||
@cindex layout, page
|
||
|
||
@code{gtroff} provides some very primitive operations for controlling
|
||
page layout.
|
||
|
||
@DefreqList {pl, [@Var{length}]}
|
||
@DefreqItem {pl, @t{+}@Var{length}}
|
||
@DefreqItem {pl, @t{-}@Var{length}}
|
||
@DefregListEnd {.p}
|
||
@cindex page length (@code{pl})
|
||
@cindex length of page (@code{pl})
|
||
Set the @dfn{page length} to @var{length} (or increment or decrement
|
||
the current value by @var{length}). This is the length of the
|
||
physical output page. The default scaling indicator is @samp{v}.
|
||
|
||
@cindex page length register (@code{.p})
|
||
The current setting can be found in the read-only number register
|
||
@samp{.p}.
|
||
|
||
@cindex top margin
|
||
@cindex margin, top
|
||
@cindex bottom margin
|
||
@cindex margin, bottom
|
||
Note that this only specifies the size of the page, not the top and
|
||
bottom margins. Those are not set by @code{gtroff} directly.
|
||
@xref{Traps}, for further information on how to do this.
|
||
|
||
Negative @code{pl} values are possible also, but not very useful: No
|
||
trap is sprung, and each line is output on a single page (thus
|
||
suppressing all vertical spacing).
|
||
|
||
If no argument or an invalid argument is given, @code{pl} sets the page
|
||
length to 11@dmn{i}.
|
||
@endDefreq
|
||
|
||
@cindex headers
|
||
@cindex footers
|
||
@cindex titles
|
||
@code{gtroff} provides several operations which help in setting up top
|
||
and bottom titles (or headers and footers).
|
||
|
||
@Defreq {tl, @t{'}@Var{left}@t{'}@Var{center}@t{'}@Var{right}@t{'}}
|
||
@cindex title line (@code{tl})
|
||
@cindex three-part title (@code{tl})
|
||
@cindex page number character (@code{%})
|
||
Print a @dfn{title line}. It consists of three parts: a left
|
||
justified portion, a centered portion, and a right justified portion.
|
||
The argument separator @samp{'} can be replaced with any character not
|
||
occurring in the title line. The @samp{%} character is replaced with
|
||
the current page number. This character can be changed with the
|
||
@code{pc} request (see below).
|
||
|
||
Without argument, @code{tl} is ignored.
|
||
|
||
Some notes:
|
||
|
||
@itemize @bullet
|
||
@item
|
||
A title line is not restricted to the top or bottom of a page.
|
||
|
||
@item
|
||
@code{tl} prints the title line immediately, ignoring a partially filled
|
||
line (which stays untouched).
|
||
|
||
@item
|
||
It is not an error to omit closing delimiters. For example,
|
||
@w{@samp{.tl /foo}} is equivalent to @w{@samp{.tl /foo///}}: It prints a
|
||
title line with the left justified word @samp{foo}; the centered and
|
||
right justfied parts are empty.
|
||
|
||
@item
|
||
@code{tl} accepts the same parameter delimiting characters as the
|
||
@code{\A} escape; see @ref{Escapes}.
|
||
@end itemize
|
||
@endDefreq
|
||
|
||
@DefreqList {lt, [@Var{length}]}
|
||
@DefreqItem {lt, @t{+}@Var{length}}
|
||
@DefreqItem {lt, @t{-}@Var{length}}
|
||
@DefregListEnd {.lt}
|
||
@cindex length of title line (@code{lt})
|
||
@cindex title line, length (@code{lt})
|
||
@cindex title line length register (@code{.lt})
|
||
The title line is printed using its own line length, which is
|
||
specified (or incremented or decremented) with the @code{lt} request.
|
||
Initially, the title line length is set to 6.5@dmn{i}. If a negative
|
||
line length is specified (which is not allowed), @code{gtroff} emits a
|
||
warning of type @samp{range} and sets the title line length to zero.
|
||
The default scaling indicator is @samp{m}. If @code{lt} is called
|
||
without an argument, the title length is reset to the previous value
|
||
before the last call to @code{lt}.
|
||
|
||
The current setting of this is available in the @code{.lt} read-only
|
||
number register; it is associated with the current environment
|
||
(@pxref{Environments}).
|
||
|
||
@endDefreq
|
||
|
||
@DefreqList {pn, page}
|
||
@DefreqItem {pn, @t{+}@Var{page}}
|
||
@DefreqItem {pn, @t{-}@Var{page}}
|
||
@DefregListEnd {.pn}
|
||
@cindex page number (@code{pn})
|
||
@cindex number, page (@code{pn})
|
||
Change (increase or decrease) the page number of the @emph{next} page.
|
||
The only argument is the page number; the request is ignored without a
|
||
parameter.
|
||
|
||
The read-only number register @code{.pn} contains the number of the next
|
||
page: either the value set by a @code{pn} request, or the number of the
|
||
current page plus@w{ }1.
|
||
@endDefreq
|
||
|
||
@Defreg {%}
|
||
@cindex page number register (@code{%})
|
||
A read-write register holding the current page number.
|
||
@endDefreg
|
||
|
||
@Defreq {pc, [@Var{char}]}
|
||
@cindex changing the page number character (@code{pc})
|
||
@cindex page number character, changing (@code{pc})
|
||
@vindex %
|
||
Change the page number character (used by the @code{tl} request) to a
|
||
different character. With no argument, this mechanism is disabled.
|
||
Note that this doesn't affect the number register@w{ }@code{%}.
|
||
@endDefreq
|
||
|
||
@xref{Traps}.
|
||
|
||
|
||
@c =====================================================================
|
||
|
||
@node Page Control, Fonts, Page Layout, gtroff Reference
|
||
@section Page Control
|
||
@cindex page control
|
||
@cindex control, page
|
||
|
||
@DefreqList {bp, [@Var{page}]}
|
||
@DefreqItem {bp, @t{+}@Var{page}}
|
||
@DefreqListEnd {bp, @t{-}@Var{page}}
|
||
@cindex new page (@code{bp})
|
||
@cindex page, new (@code{bp})
|
||
Stop processing the current page and move to the next page. This
|
||
request causes a break. It can also take an argument to set
|
||
(increase, decrease) the page number of the next page. The only
|
||
difference between @code{bp} and @code{pn} is that @code{pn} does not
|
||
cause a break or actually eject a page.
|
||
|
||
@Example
|
||
.de newpage \" define macro
|
||
'bp \" begin page
|
||
'sp .5i \" vertical space
|
||
.tl 'left top'center top'right top' \" title
|
||
'sp .3i \" vertical space
|
||
.. \" end macro
|
||
@endExample
|
||
|
||
@cindex @code{bp} request, and top-level diversion
|
||
@cindex top-level diversion, and @code{bp}
|
||
@cindex diversion, top-level, and @code{bp}
|
||
@code{bp} has no effect if not called within the top-level diversion
|
||
(@pxref{Diversions}).
|
||
@endDefreq
|
||
|
||
@Defreq {ne, [@Var{space}]}
|
||
@cindex orphan lines, preventing with @code{ne}
|
||
@cindex conditional page break (@code{ne})
|
||
@cindex page break, conditional (@code{ne})
|
||
It is often necessary to force a certain amount of space before a new
|
||
page occurs. This is most useful to make sure that there is not a
|
||
single @dfn{orphan} line left at the bottom of a page. The @code{ne}
|
||
request ensures that there is a certain distance, specified by the
|
||
first argument, before the next page is triggered (see @ref{Traps},
|
||
for further information). The default scaling indicator for @code{ne}
|
||
is @samp{v}; the default value of @var{space} is@w{ }1@dmn{v} if no
|
||
argument is given.
|
||
|
||
For example, to make sure that no fewer than 2@w{ }lines get orphaned,
|
||
do the following before each paragraph:
|
||
|
||
@Example
|
||
.ne 2
|
||
text text text
|
||
@endExample
|
||
|
||
@code{ne} will then automatically cause a page break if there is space
|
||
for one line only.
|
||
@endDefreq
|
||
|
||
@DefreqList {sv, [@Var{space}]}
|
||
@DefreqListEnd {os, }
|
||
@cindex @code{ne} request, comparison with @code{sv}
|
||
@code{sv} is similar to the @code{ne} request; it reserves the
|
||
specified amount of vertical space. If the desired amount of space
|
||
exists before the next trap (or the bottom page boundary if no trap is
|
||
set), the space is output immediately (ignoring a partially filled line
|
||
which stays untouched). If there is not enough space, it is stored for
|
||
later output via the @code{os} request. The default value is@w{ }1@dmn{v}
|
||
if no argument is given; the default scaling indicator is @samp{v}.
|
||
|
||
@cindex @code{sv} request, and no-space mode
|
||
@cindex @code{os} request, and no-space mode
|
||
Both @code{sv} and @code{os} ignore no-space mode. While the @code{sv}
|
||
request allows negative values for @var{space}, @code{os} will ignore
|
||
them.
|
||
@endDefreq
|
||
|
||
@Defreg {nl}
|
||
This register contains the current vertical position. If the vertical
|
||
position is zero and the top of page transition hasn't happened yet,
|
||
@code{nl} is set to negative value. @code{gtroff} itself does this at
|
||
the very beginning of a document before anything has been printed, but
|
||
the main usage is to plant a header trap on a page if this page has
|
||
already started.
|
||
|
||
Consider the following:
|
||
|
||
@Example
|
||
.de xxx
|
||
. sp
|
||
. tl ''Header''
|
||
. sp
|
||
..
|
||
.
|
||
First page.
|
||
.bp
|
||
.wh 0 xxx
|
||
.nr nl (-1)
|
||
Second page.
|
||
@endExample
|
||
|
||
@noindent
|
||
Result:
|
||
|
||
@Example
|
||
First page.
|
||
|
||
...
|
||
|
||
Header
|
||
|
||
Second page.
|
||
|
||
...
|
||
@endExample
|
||
|
||
@noindent
|
||
Without resetting @code{nl} to a negative value, the just planted trap
|
||
would be active beginning with the @emph{next} page, not the current
|
||
one.
|
||
|
||
@xref{Diversions}, for a comparison with the @code{.h} and @code{.d}
|
||
registers.
|
||
@endDefreg
|
||
|
||
@c =====================================================================
|
||
|
||
@node Fonts, Sizes, Page Control, gtroff Reference
|
||
@section Fonts
|
||
@cindex fonts
|
||
|
||
@code{gtroff} can switch fonts at any point in the text.
|
||
|
||
The basic set of fonts is @samp{R}, @samp{I}, @samp{B}, and @samp{BI}.
|
||
These are Times Roman, Italic, Bold, and Bold Italic. For non-TTY
|
||
devices, there is also at least one symbol font which contains various
|
||
special symbols (Greek, mathematics).
|
||
|
||
@menu
|
||
* Changing Fonts::
|
||
* Font Families::
|
||
* Font Positions::
|
||
* Using Symbols::
|
||
* Special Fonts::
|
||
* Artificial Fonts::
|
||
* Ligatures and Kerning::
|
||
@end menu
|
||
|
||
@c ---------------------------------------------------------------------
|
||
|
||
@node Changing Fonts, Font Families, Fonts, Fonts
|
||
@subsection Changing Fonts
|
||
@cindex fonts
|
||
|
||
@DefreqList {ft, [@Var{font}]}
|
||
@DefescItem {\\f, , f, }
|
||
@DefescItem {\\f, @lparen{}, fn, }
|
||
@DefescListEnd {\\f, @lbrack{}, font, @rbrack}
|
||
@cindex changing fonts (@code{ft}, @code{\f})
|
||
@cindex fonts, changing (@code{ft}, @code{\f})
|
||
@cindex @code{sty} request, and changing fonts
|
||
@cindex @code{fam} request, and changing fonts
|
||
@cindex @code{\F}, and changing fonts
|
||
@kindex styles
|
||
@kindex family
|
||
@pindex DESC
|
||
The @code{ft} request and the @code{\f} escape change the current font
|
||
to @var{font} (one-character name@w{ }@var{f}, two-character name
|
||
@var{fn}).
|
||
|
||
If @var{font} is a style name (as set with the @code{sty} request or
|
||
with the @code{styles} command in the @file{DESC} file), use it within
|
||
the current font family (as set with the @code{fam} request, @code{\F}
|
||
escape, or with the @code{family} command in the @file{DESC} file).
|
||
|
||
@cindex previous font (@code{ft}, @code{\f[]}, @code{\fP})
|
||
@cindex font, previous (@code{ft}, @code{\f[]}, @code{\fP})
|
||
With no argument or using @samp{P} as an argument, @code{.ft} switches
|
||
to the previous font. Use @code{\f[]} to do this with the escape. The
|
||
old syntax forms @code{\fP} or @code{\f[P]} are also supported.
|
||
|
||
Fonts are generally specified as upper-case strings, which are usually
|
||
1@w{ }to 4 characters representing an abbreviation or acronym of the
|
||
font name. This is no limitation, just a convention.
|
||
|
||
The example below produces two identical lines.
|
||
|
||
@Example
|
||
eggs, bacon,
|
||
.ft B
|
||
spam
|
||
.ft
|
||
and sausage.
|
||
|
||
eggs, bacon, \fBspam\fP and sausage.
|
||
@endExample
|
||
|
||
Note that @code{\f} doesn't produce an input token in @code{gtroff}.
|
||
As a consequence, it can be used in requests like @code{mc} (which
|
||
expects a single character as an argument) to change the font on
|
||
the fly:
|
||
|
||
@Example
|
||
.mc \f[I]x\f[]
|
||
@endExample
|
||
|
||
@xref{Font Positions}, for an alternative syntax.
|
||
@endDefreq
|
||
|
||
@Defreq {ftr, f [@Var{g}]}
|
||
@cindex @code{ft} request, and font translations
|
||
@cindex @code{ul} request, and font translations
|
||
@cindex @code{bd} request, and font translations
|
||
@cindex @code{\f}, and font translations
|
||
@cindex @code{cs} request, and font translations
|
||
@cindex @code{tkf} request, and font translations
|
||
@cindex @code{special} request, and font translations
|
||
@cindex @code{fspecial} request, and font translations
|
||
@cindex @code{fp} request, and font translations
|
||
@cindex @code{sty} request, and font translations
|
||
Translate font@w{ }@var{f} to font@w{ }@var{g}. Whenever a font named@w{
|
||
}@var{f} is referred to in a @code{\f} escape sequence, or in the
|
||
@code{ft}, @code{ul}, @code{bd}, @code{cs}, @code{tkf},
|
||
@code{special}, @code{fspecial}, @code{fp}, or @code{sty} requests,
|
||
font@w{ }@var{g} is used. If @var{g} is missing or equal to@w{ }@var{f}
|
||
the translation is undone.
|
||
@endDefreq
|
||
|
||
@c ---------------------------------------------------------------------
|
||
|
||
@node Font Families, Font Positions, Changing Fonts, Fonts
|
||
@subsection Font Families
|
||
@cindex font families
|
||
@cindex families, font
|
||
@cindex font styles
|
||
@cindex styles, font
|
||
|
||
Due to the variety of fonts available, @code{gtroff} has added the
|
||
concept of @dfn{font families} and @dfn{font styles}. The fonts are
|
||
specified as the concatenation of the font family and style. Specifying
|
||
a font without the family part causes @code{gtroff} to use that style of
|
||
the current family.
|
||
|
||
@cindex PostScript fonts
|
||
@cindex fonts, PostScript
|
||
Currently, fonts for the devices @option{-Tps}, @option{-Tdvi}, and
|
||
@option{-Tlbp} are set up to this mechanism.
|
||
By default, @code{gtroff} uses the Times family with the four styles
|
||
@samp{R}, @samp{I}, @samp{B}, and @samp{BI}.
|
||
|
||
This way, it is possible to use the basic four fonts and to select a
|
||
different font family on the command line (@pxref{Groff Options}).
|
||
|
||
@DefreqList {fam, [@Var{family}]}
|
||
@DefregItem {.fam}
|
||
@DefescItem {\\F, , f, }
|
||
@DefescItem {\\F, @lparen{}, fm, }
|
||
@DefescItem {\\F, @lbrack{}, family, @rbrack}
|
||
@DefregListEnd {.fn}
|
||
@cindex changing font family (@code{fam}, @code{\F})
|
||
@cindex font family, changing (@code{fam}, @code{\F})
|
||
Switch font family to @var{family} (one-character name@w{ }@var{f},
|
||
two-character name @var{fm}). If no argument is given, switch
|
||
back to the previous font family. Use @code{\F[]} to do this with the
|
||
escape. Note that @code{\FP} doesn't work; it selects font family
|
||
@samp{P} instead.
|
||
|
||
The value at start-up is @samp{T}.
|
||
The current font family is available in the read-only number register
|
||
@samp{.fam} (this is a string-valued register); it is associated with
|
||
the current environment.
|
||
|
||
@Example
|
||
spam,
|
||
.fam H \" helvetica family
|
||
spam, \" used font is family H + style R = HR
|
||
.ft B \" family H + style B = font HB
|
||
spam,
|
||
.fam T \" times family
|
||
spam, \" used font is family T + style B = TB
|
||
.ft AR \" font AR (not a style)
|
||
baked beans,
|
||
.ft R \" family T + style R = font TR
|
||
and spam.
|
||
@endExample
|
||
|
||
Note that @code{\F} doesn't produce an input token in @code{gtroff}.
|
||
As a consequence, it can be used in requests like @code{mc} (which
|
||
expects a single character as an argument) to change the font family on
|
||
the fly:
|
||
|
||
@Example
|
||
.mc \F[P]x\F[]
|
||
@endExample
|
||
|
||
The @samp{.fn} register contains the current @dfn{real font name}
|
||
of the current font.
|
||
This is a string-valued register.
|
||
If the current font is a style, the value of @code{\n[.fn]}
|
||
is the proper concatenation of family and style name.
|
||
@endDefreq
|
||
|
||
@Defreq {sty, n style}
|
||
@cindex changing font style (@code{sty})
|
||
@cindex font style, changing (@code{sty})
|
||
@cindex @code{cs} request, and font styles
|
||
@cindex @code{bd} request, and font styles
|
||
@cindex @code{tkf} request, and font styles
|
||
@cindex @code{uf} request, and font styles
|
||
@cindex @code{fspecial} request, and font styles
|
||
Associate @var{style} with font position@w{ }@var{n}. A font position
|
||
can be associated either with a font or with a style. The current
|
||
font is the index of a font position and so is also either a font or a
|
||
style. If it is a style, the font that is actually used is the font
|
||
which name is the concatenation of the name of the current
|
||
family and the name of the current style. For example, if the current
|
||
font is@w{ }1 and font position@w{ }1 is associated with style
|
||
@samp{R} and the current font family is @samp{T}, then font
|
||
@samp{TR} will be used. If the current font is not a style, then the
|
||
current family is ignored. If the requests @code{cs}, @code{bd},
|
||
@code{tkf}, @code{uf}, or @code{fspecial} are applied to a style,
|
||
they will instead be applied to the member of the current family
|
||
corresponding to that style.
|
||
|
||
@var{n}@w{ }must be a non-negative integer value.
|
||
|
||
@pindex DESC
|
||
@kindex styles
|
||
The default family can be set with the @option{-f} option
|
||
(@pxref{Groff Options}). The @code{styles} command in the @file{DESC}
|
||
file controls which font positions (if any) are initially associated
|
||
with styles rather than fonts. For example, the default setting for
|
||
@sc{PostScript} fonts
|
||
|
||
@Example
|
||
styles R I B BI
|
||
@endExample
|
||
|
||
@noindent
|
||
is equivalent to
|
||
|
||
@Example
|
||
.sty 1 R
|
||
.sty 2 I
|
||
.sty 3 B
|
||
.sty 4 BI
|
||
@endExample
|
||
|
||
@code{fam} and @code{\F} always check whether the current font position
|
||
is valid; this can give surprising results if the current font position is
|
||
associated with a style.
|
||
|
||
In the following example, we want to access the @sc{PostScript} font
|
||
@code{FooBar} from the font family @code{Foo}:
|
||
|
||
@Example
|
||
.sty \n[.fp] Bar
|
||
.fam Foo
|
||
@result{} warning: can't find font `FooR'
|
||
@endExample
|
||
|
||
@noindent
|
||
The default font position at start-up is@w{ }1; for the
|
||
@sc{PostScript} device, this is associated with style @samp{R}, so
|
||
@code{gtroff} tries to open @code{FooR}.
|
||
|
||
A solution to this problem is to use a dummy font like the following:
|
||
|
||
@Example
|
||
.fp 0 dummy TR \" set up dummy font at position 0
|
||
.sty \n[.fp] Bar \" register style `Bar'
|
||
.ft 0 \" switch to font at position 0
|
||
.fam Foo \" activate family `Foo'
|
||
.ft Bar \" switch to font `FooBar'
|
||
@endExample
|
||
|
||
@xref{Font Positions}.
|
||
@endDefreq
|
||
|
||
@c ---------------------------------------------------------------------
|
||
|
||
@node Font Positions, Using Symbols, Font Families, Fonts
|
||
@subsection Font Positions
|
||
@cindex font positions
|
||
@cindex positions, font
|
||
|
||
For the sake of old phototypesetters and compatibility with old versions
|
||
of @code{troff}, @code{gtroff} has the concept of font @dfn{positions},
|
||
on which various fonts are mounted.
|
||
|
||
@DefreqList {fp, pos font [@Var{external-name}]}
|
||
@DefregItem {.f}
|
||
@DefregListEnd {.fp}
|
||
@cindex mounting font (@code{fp})
|
||
@cindex font, mounting (@code{fp})
|
||
Mount font @var{font} at position @var{pos} (which must be a
|
||
non-negative integer). This numeric position can then be referred to
|
||
with font changing commands. When @code{gtroff} starts it is using
|
||
font position@w{ }1 (which must exist; position@w{ }0 is unused
|
||
usually at start-up).
|
||
|
||
@cindex font position register (@code{.f})
|
||
The current font in use, as a font position, is available in the
|
||
read-only number register @samp{.f}. This can be useful to remember the
|
||
current font for later recall. It is associated with the current
|
||
environment (@pxref{Environments}).
|
||
|
||
@Example
|
||
.nr save-font \n[.f]
|
||
.ft B
|
||
... text text text ...
|
||
.ft \n[save-font]
|
||
@endExample
|
||
|
||
@cindex next free font position register (@code{.fp})
|
||
The number of the next free font position is available in the read-only
|
||
number register @samp{.fp}. This is useful when mounting a new font,
|
||
like so:
|
||
|
||
@Example
|
||
.fp \n[.fp] NEATOFONT
|
||
@endExample
|
||
|
||
@pindex DESC@r{, and font mounting}
|
||
Fonts not listed in the @file{DESC} file are automatically mounted on
|
||
the next available font position when they are referenced. If a font
|
||
is to be mounted explicitly with the @code{fp} request on an unused
|
||
font position, it should be mounted on the first unused font position,
|
||
which can be found in the @code{.fp} register. Although @code{gtroff}
|
||
does not enforce this strictly, it is not allowed to mount a font at a
|
||
position whose number is much greater (approx.@: 1000 positions) than
|
||
that of any currently used position.
|
||
|
||
The @code{fp} request has an optional third argument. This argument
|
||
gives the external name of the font, which is used for finding the font
|
||
description file. The second argument gives the internal name of the
|
||
font which is used to refer to the font in @code{gtroff} after it has
|
||
been mounted. If there is no third argument then the internal name is
|
||
used as the external name. This feature makes it possible to use
|
||
fonts with long names in compatibility mode.
|
||
@endDefreq
|
||
|
||
Both the @code{ft} request and the @code{\f} escape have alternative
|
||
syntax forms to access font positions.
|
||
|
||
@DefreqList {ft, nnn}
|
||
@DefescItem {\\f, , n, }
|
||
@DefescItem {\\f, @lparen{}, nn, }
|
||
@DefescListEnd {\\f, @lbrack{}, nnn, @rbrack}
|
||
@cindex changing font position (@code{\f})
|
||
@cindex font position, changing (@code{\f})
|
||
@cindex @code{sty} request, and font positions
|
||
@cindex @code{fam} request, and font positions
|
||
@cindex @code{\F}, and font positions
|
||
@kindex styles
|
||
@kindex family
|
||
@pindex DESC
|
||
Change the current font position to @var{nnn} (one-digit position@w{
|
||
}@var{n}, two-digit position @var{nn}), which must be a non-negative
|
||
integer.
|
||
|
||
If @var{nnn} is associated with a style (as set with the @code{sty}
|
||
request or with the @code{styles} command in the @file{DESC} file), use
|
||
it within the current font family (as set with the @code{fam} request,
|
||
the @code{\F} escape, or with the @code{family} command in the @file{DESC}
|
||
file).
|
||
|
||
@Example
|
||
this is font 1
|
||
.ft 2
|
||
this is font 2
|
||
.ft \" switch back to font 1
|
||
.ft 3
|
||
this is font 3
|
||
.ft
|
||
this is font 1 again
|
||
@endExample
|
||
|
||
@xref{Changing Fonts}, for the standard syntax form.
|
||
@endDefreq
|
||
|
||
@c ---------------------------------------------------------------------
|
||
|
||
@node Using Symbols, Special Fonts, Font Positions, Fonts
|
||
@subsection Using Symbols
|
||
@cindex using symbols
|
||
@cindex symbols, using
|
||
|
||
@cindex glyph
|
||
@cindex character
|
||
@cindex ligature
|
||
A @dfn{glyph} is a graphical representation of a @dfn{character}.
|
||
While a character is an abstract entity containing semantic
|
||
information, a glyph is something which can be actually seen on screen
|
||
or paper. It is possible that a character has multiple glyph
|
||
representation forms (for example, the character `A' can be either
|
||
written in a roman or an italic font, yielding two different glyphs);
|
||
sometimes more than one character maps to a single glyph (this is a
|
||
@dfn{ligature} -- the most common is `fi').
|
||
|
||
@cindex symbol
|
||
@cindex special fonts
|
||
@kindex fonts
|
||
@pindex DESC
|
||
A @dfn{symbol} is simply a named glyph. Within @code{gtroff}, all
|
||
glyph names of a particular font are defined in its font file. If the
|
||
user requests a glyph not available in this font, @code{gtroff} looks
|
||
up an ordered list of @dfn{special fonts}. By default, the
|
||
@sc{PostScript} output device supports the two special fonts @samp{SS}
|
||
(slanted symbols) and @samp{S} (symbols) (the former is looked up
|
||
before the latter). Other output devices use different names for
|
||
special fonts. Fonts mounted with the @code{fonts} keyword in the
|
||
@file{DESC} file are globally available. To install additional
|
||
special fonts locally (i.e.@: for a particular font), use the
|
||
@code{fspecial} request.
|
||
|
||
In summary, @code{gtroff} tries the following to find a given symbol:
|
||
|
||
@itemize @bullet
|
||
@item
|
||
If the symbol has been defined with the @code{char} request, use it.
|
||
This hides a symbol with the same name in the current font.
|
||
|
||
@item
|
||
Check the current font.
|
||
|
||
@item
|
||
If the symbol has been defined with the @code{fchar} request, use it.
|
||
|
||
@item
|
||
Check all fonts given with the @code{fspecial} request, in the order
|
||
of appearance in @code{fspecial} calls.
|
||
|
||
@item
|
||
Check all fonts given with the @code{special} request, in the order
|
||
of appearance in @code{special} calls (inclusively the special fonts
|
||
defined in the @file{DESC} file, which come first).
|
||
|
||
@item
|
||
As a last resort, consult all fonts loaded up to now (in the order they
|
||
have been called the first time) for special fonts and check them.
|
||
@end itemize
|
||
|
||
@xref{Font Files}, and @ref{Special Fonts}, for more details.
|
||
|
||
@DefescList {\\, @lparen{}, nm, }
|
||
@DefescListEnd {\\, @lbrack{}, name, @rbrack}
|
||
Insert a symbol @var{name} (two-character name @var{nm}). There is no
|
||
special syntax for one-character names -- the natural form
|
||
@samp{\@var{n}} would collide with escapes.@footnote{Note that a
|
||
one-character symbol is not the same as an input character, i.e., the
|
||
character @code{a} is not the same as @code{\[a]}. By default,
|
||
@code{groff} defines only a single one-character symbol, @code{\[-]};
|
||
it is usually accessed as @code{\-}. On the other hand, @code{gtroff}
|
||
has the special feature that @code{\[char@var{XXX}]} is the same as the
|
||
input character with character code @var{XXX}. For example,
|
||
@code{\[char97]} is identical to the letter @code{a} if @acronym{ASCII}
|
||
encoding is active.}
|
||
|
||
If @var{name} is undefined, a warning of type @samp{char} is generated,
|
||
and the escape is ignored. @xref{Debugging}, for information about
|
||
warnings.
|
||
|
||
@cindex list of available glyphs (@cite{groff_char(7)} man page)
|
||
@cindex available glyphs, list (@cite{groff_char(7)} man page)
|
||
@cindex glyphs, available, list (@cite{groff_char(7)} man page)
|
||
The list of available symbols is device dependent; see the
|
||
@cite{groff_char(7)} man page for a complete list for the given output
|
||
device. For example, say
|
||
|
||
@Example
|
||
man -Tdvi groff_char > groff_char.dvi
|
||
@endExample
|
||
|
||
@noindent
|
||
for a list using the default DVI fonts (not all versions of the
|
||
@code{man} program support the @option{-T} option). If you want to
|
||
use an additional macro package to change the used fonts, @code{groff}
|
||
must be called directly:
|
||
|
||
@Example
|
||
groff -Tdvi -mec -man groff_char.7 > groff_char.dvi
|
||
@endExample
|
||
|
||
@c XXX list of common symbols
|
||
@endDefesc
|
||
|
||
@Defesc {\\C, ', xxx, '}
|
||
@cindex named character (@code{\C})
|
||
@cindex character, named (@code{\C})
|
||
Typeset the glyph named @var{xxx}.@footnote{@code{\C} is actually a
|
||
misnomer since it accesses an output glyph.} Normally it is more
|
||
convenient to use @code{\[@var{xxx}]}, but @code{\C} has the advantage
|
||
that it is compatible with newer versions of @acronym{AT&T}
|
||
@code{troff} and is available in compatibility mode.
|
||
@endDefesc
|
||
|
||
@Defesc {\\N, ', n, '}
|
||
@cindex numbered glyph (@code{\N})
|
||
@cindex glyph, numbered (@code{\N})
|
||
@cindex @code{char} request, used with @code{\N}
|
||
@cindex Unicode
|
||
Typeset the glyph with code@w{ }@var{n} in the current font
|
||
(@code{n}@w{ }is @strong{not} the input character code). The
|
||
number @var{n}@w{ }can be any non-negative decimal integer. Most devices
|
||
only have glyphs with codes between 0 and@w{ }255; the Unicode
|
||
output device uses codes in the range 0--65535. If the current
|
||
font does not contain a glyph with that code, special fonts are
|
||
@emph{not} searched. The @code{\N} escape sequence can be
|
||
conveniently used in conjunction with the @code{char} request:
|
||
|
||
@Example
|
||
.char \[phone] \f[ZD]\N'37'
|
||
@endExample
|
||
|
||
@noindent
|
||
@pindex DESC
|
||
@cindex unnamed glyphs
|
||
@cindex glyphs, unnamed
|
||
The code of each glyph is given in the fourth column in the font
|
||
description file after the @code{charset} command. It is possible to
|
||
include unnamed glyphs in the font description file by using a
|
||
name of @samp{---}; the @code{\N} escape sequence is the only way to
|
||
use these.
|
||
@endDefesc
|
||
|
||
Some escape sequences directly map onto special glyphs.
|
||
|
||
@Defesc {\\', , , }
|
||
This is a backslash followed by the apostrophe character, @acronym{ASCII}
|
||
character @code{0x27} (@acronym{EBCDIC} character @code{0x7D}). The same
|
||
as @code{\[aa]}, the acute accent.
|
||
@endDefesc
|
||
|
||
@Defesc {\\`, , , }
|
||
This is a backslash followed by @acronym{ASCII} character @code{0x60}
|
||
(@acronym{EBCDIC} character @code{0x79} usually). The same as
|
||
@code{\[ga]}, the grave accent.
|
||
@endDefesc
|
||
|
||
@Defesc {\\-, , , }
|
||
This is the same as @code{\[-]}, the minus sign in the current font.
|
||
@endDefesc
|
||
|
||
@Defreq {cflags, n c1 c2 @dots{}}
|
||
@cindex glyph properties (@code{cflags})
|
||
@cindex character properties (@code{cflags})
|
||
@cindex properties of glyphs (@code{cflags})
|
||
@cindex properties of characters (@code{cflags})
|
||
Input characters and symbols have certain properties associated
|
||
with it.@footnote{Note that the output glyphs themselves don't have
|
||
such properties. For @code{gtroff}, a glyph is a numbered box with
|
||
a given width, depth, and height, nothing else. All manipulations
|
||
with the @code{cflags} request work on the input level.} These
|
||
properties can be modified with the @code{cflags} request. The
|
||
first argument is the sum of the desired flags and the remaining
|
||
arguments are the characters or symbols to have those properties.
|
||
It is possible to omit the spaces between the characters or symbols.
|
||
|
||
@table @code
|
||
@item 1
|
||
@cindex end-of-sentence characters
|
||
@cindex characters, end-of-sentence
|
||
The character ends sentences (initially characters @samp{.?!} have this
|
||
property).
|
||
|
||
@item 2
|
||
@cindex hyphenating characters
|
||
@cindex characters, hyphenation
|
||
Lines can be broken before the character (initially no characters have
|
||
this property).
|
||
|
||
@item 4
|
||
@cindex @code{hy} glyph, and @code{cflags}
|
||
@cindex @code{em} glyph, and @code{cflags}
|
||
Lines can be broken after the character (initially the character
|
||
@samp{-} and the symbols @samp{\(hy} and @samp{\(em} have this property).
|
||
|
||
@item 8
|
||
@cindex overlapping characters
|
||
@cindex characters, overlapping
|
||
@cindex @code{ul} glyph, and @code{cflags}
|
||
@cindex @code{rn} glyph, and @code{cflags}
|
||
@cindex @code{ru} glyph, and @code{cflags}
|
||
The character overlaps horizontally (initially the symbols
|
||
@samp{\(ul\(rn\(ru} have this property).
|
||
|
||
@item 16
|
||
@cindex @code{br} glyph, and @code{cflags}
|
||
The character overlaps vertically (initially symbol @samp{\(br} has
|
||
this property).
|
||
|
||
@item 32
|
||
@cindex transparent characters
|
||
@cindex character, transparent
|
||
@cindex @code{"}, at end of sentence
|
||
@cindex @code{'}, at end of sentence
|
||
@cindex @code{)}, at end of sentence
|
||
@cindex @code{]}, at end of sentence
|
||
@cindex @code{*}, at end of sentence
|
||
@cindex @code{dg} glyph, at end of sentence
|
||
@cindex @code{rq} glyph, at end of sentence
|
||
An end-of-sentence character followed by any number of characters with
|
||
this property is treated as the end of a sentence if followed by a
|
||
newline or two spaces; in other words the character is
|
||
@dfn{transparent} for the purposes of end-of-sentence recognition --
|
||
this is the same as having a zero space factor in @TeX{} (initially
|
||
characters @samp{"')]*} and the symbols @samp{\(dg\(rq} have this
|
||
property).
|
||
@end table
|
||
@endDefreq
|
||
|
||
@DefreqList {char, g [@Var{string}]}
|
||
@DefreqListEnd {fchar, g [@Var{string}]}
|
||
@cindex defining character (@code{char})
|
||
@cindex character, defining (@code{char})
|
||
@cindex creating new characters (@code{char})
|
||
@cindex defining symbol (@code{char})
|
||
@cindex symbol, defining (@code{char})
|
||
@cindex defining glyph (@code{char})
|
||
@cindex glyph, defining (@code{char})
|
||
@cindex escape character, while defining glyph
|
||
@cindex character, escape, while defining glyph
|
||
@cindex @code{tr} request, and glyph definitions
|
||
@cindex @code{cp} request, and glyph definitions
|
||
@cindex @code{rc} request, and glyph definitions
|
||
@cindex @code{lc} request, and glyph definitions
|
||
@cindex @code{\l}, and glyph definitions
|
||
@cindex @code{\L}, and glyph definitions
|
||
@cindex @code{\&}, and glyph definitions
|
||
@cindex @code{\e}, and glyph definitions
|
||
@cindex @code{hcode} request, and glyph definitions
|
||
Define a new glyph@w{ }@var{g} to be @var{string} (which can be
|
||
empty).@footnote{@code{char} is a misnomer since an output glyph is
|
||
defined.} Every time glyph@w{ }@var{g} needs to be printed,
|
||
@var{string} is processed in a temporary environment and the result is
|
||
wrapped up into a single object. Compatibility mode is turned off and
|
||
the escape character is set to @samp{\} while @var{string} is being
|
||
processed. Any emboldening, constant spacing or track kerning is
|
||
applied to this object rather than to individual characters in
|
||
@var{string}.
|
||
|
||
A glyph defined by this request can be used just
|
||
like a normal glyph provided by the output device. In particular,
|
||
other characters can be translated to it with the @code{tr} or
|
||
@code{trin} requests; it can be made the leader character by the
|
||
@code{lc} request; repeated patterns can be drawn with the glyph
|
||
using the @code{\l} and @code{\L} escape sequences; words containing
|
||
the glyph can be hyphenated correctly if the @code{hcode} request
|
||
is used to give the glyph's symbol a hyphenation code.
|
||
|
||
There is a special anti-recursion feature: Use of @code{g} within
|
||
the glyph's definition is handled like normal characters and symbols
|
||
not defined with @code{char}.
|
||
|
||
Note that the @code{tr} and @code{trin} requests take precedence if
|
||
@code{char} accesses the same symbol.
|
||
|
||
@Example
|
||
.tr XY
|
||
X
|
||
@result{} Y
|
||
.char X Z
|
||
X
|
||
@result{} Y
|
||
.tr XX
|
||
X
|
||
@result{} Z
|
||
@endExample
|
||
|
||
The @code{fchar} request defines a fallback glyph:
|
||
@code{gtroff} only checks for glyphs defined with @code{fchar}
|
||
if it cannot find the glyph in the current font.
|
||
@code{gtroff} carries out this test before checking special fonts.
|
||
@endDefreq
|
||
|
||
@Defreq {rchar, c1 c2 @dots{}}
|
||
@cindex removing glyph definition (@code{rchar})
|
||
@cindex glyph, removing definition (@code{rchar})
|
||
Remove the definitions of glyphs @var{c1}, @var{c2},@w{
|
||
}@enddots{} This undoes the effect of a @code{char} or @code{fchar}
|
||
request.
|
||
|
||
It is possible to omit the whitespace between arguments.
|
||
@endDefreq
|
||
|
||
@xref{Special Characters}.
|
||
|
||
@c ---------------------------------------------------------------------
|
||
|
||
@node Special Fonts, Artificial Fonts, Using Symbols, Fonts
|
||
@subsection Special Fonts
|
||
@cindex special fonts
|
||
@cindex fonts, special
|
||
|
||
Special fonts are those that @code{gtroff} searches
|
||
when it cannot find the requested glyph in the current font.
|
||
The Symbol font is usually a special font.
|
||
|
||
@code{gtroff} provides the following two requests to add more special
|
||
fonts. @xref{Using Symbols}, for a detailed description of the glyph
|
||
searching mechanism in @code{gtroff}.
|
||
|
||
Usually, only non-TTY devices have special fonts.
|
||
|
||
@DefreqList {special, s1 s2 @dots{}}
|
||
@DefreqListEnd {fspecial, f s1 s2 @dots{}}
|
||
@kindex fonts
|
||
@pindex DESC
|
||
Use the @code{special} request to define special fonts. They are
|
||
appended to the list of global special fonts in the given order.
|
||
The first entries in this list are the fonts defined with the
|
||
@code{fonts} command in the @file{DESC} file which are marked as
|
||
special in the corresponding font description files.
|
||
|
||
Use the @code{fspecial} request to designate special fonts
|
||
only when font@w{ }@var{f} font is active. They are appended to the
|
||
list of special fonts for @var{f} in the given order. Initially, this
|
||
list is empty.
|
||
@endDefreq
|
||
|
||
@c ---------------------------------------------------------------------
|
||
|
||
@node Artificial Fonts, Ligatures and Kerning, Special Fonts, Fonts
|
||
@subsection Artificial Fonts
|
||
@cindex artificial fonts
|
||
@cindex fonts, artificial
|
||
|
||
There are a number of requests and escapes for artificially creating
|
||
fonts. These are largely vestiges of the days when output devices
|
||
did not have a wide variety of fonts, and when @code{nroff} and
|
||
@code{troff} were separate programs. Most of them are no longer
|
||
necessary in GNU @code{troff}. Nevertheless, they are supported.
|
||
|
||
@DefescList {\\H, ', height, '}
|
||
@DefescItem {\\H, ', @t{+}@Var{height}, '}
|
||
@DefescListEnd {\\H, ', @t{-}@Var{height}, '}
|
||
@cindex changing the font height (@code{\H})
|
||
@cindex font height, changing (@code{\H})
|
||
@cindex height, font, changing (@code{\H})
|
||
Change (increment, decrement) the height of the current font, but not
|
||
the width. If @var{height} is zero, restore the original height.
|
||
Default scaling indicator is @samp{z}.
|
||
|
||
Currently, only the @option{-Tps} device supports this feature.
|
||
|
||
Note that @code{\H} doesn't produce an input token in @code{gtroff}.
|
||
As a consequence, it can be used in requests like @code{mc} (which
|
||
expects a single character as an argument) to change the font on
|
||
the fly:
|
||
|
||
@Example
|
||
.mc \H'+5z'x\H'0'
|
||
@endExample
|
||
|
||
In compatibility mode, @code{gtroff} behaves differently: If an
|
||
increment or decrement is used, it is always taken relative to the
|
||
current point size and not relative to the previously selected font
|
||
height. Thus,
|
||
|
||
@Example
|
||
.cp 1
|
||
\H'+5'test \H'+5'test
|
||
@endExample
|
||
|
||
@noindent
|
||
prints the word @samp{test} twice with the same font height (five
|
||
points larger than the current font size).
|
||
@endDefesc
|
||
|
||
@DefescList {\\S, ', slant, '}
|
||
@cindex changing the font slant (@code{\S})
|
||
@cindex font slant, changing (@code{\S})
|
||
@cindex slant, font, changing (@code{\S})
|
||
Slant the current font by @var{slant} degrees. Positive values slant
|
||
to the right.
|
||
|
||
Currently, only the @option{-Tps} device supports this feature.
|
||
|
||
Note that @code{\S} doesn't produce an input token in @code{gtroff}.
|
||
As a consequence, it can be used in requests like @code{mc} (which
|
||
expects a single character as an argument) to change the font on
|
||
the fly:
|
||
|
||
@Example
|
||
.mc \S'20'x\S'0'
|
||
@endExample
|
||
|
||
This request is incorrectly documented in the original @acronym{UNIX}
|
||
troff manual; the slant is always set to an absolute value.
|
||
@endDefesc
|
||
|
||
@Defreq {ul, [@Var{lines}]}
|
||
@cindex underlining (@code{ul})
|
||
The @code{ul} request normally underlines subsequent lines if a TTY
|
||
output device is used. Otherwise, the lines are printed in italics
|
||
(only the term `underlined' is used in the following). The single
|
||
argument is the number of input lines to be underlined; with no
|
||
argument, the next line is underlined. If @var{lines} is zero or
|
||
negative, stop the effects of @code{ul} (if it was active). Requests
|
||
and empty lines do not count for computing the number of underlined
|
||
input lines, even if they produce some output like @code{tl}. Lines
|
||
inserted by macros (e.g.@: invoked by a trap) do count.
|
||
|
||
At the beginning of @code{ul}, the current font is stored and the
|
||
underline font is activated. Within the span of a @code{ul} request,
|
||
it is possible to change fonts, but after the last line affected by
|
||
@code{ul} the saved font is restored.
|
||
|
||
This number of lines still to be underlined is associated with the
|
||
current environment (@pxref{Environments}). The underline font can be
|
||
changed with the @code{uf} request.
|
||
|
||
@c XXX @xref should be changed to grotty
|
||
|
||
@c @xref{Troff and Nroff Mode}, for a discussion how underlining is
|
||
@c implemented in for TTY output devices, and which problems can arise.
|
||
|
||
The @code{ul} request does not underline spaces.
|
||
@endDefreq
|
||
|
||
@Defreq {cu, [@Var{lines}]}
|
||
@cindex continuous underlining (@code{cu})
|
||
@cindex underlining, continuous (@code{cu})
|
||
The @code{cu} request is similar to @code{ul} but underlines spaces as
|
||
well (if a TTY output device is used).
|
||
@endDefreq
|
||
|
||
@Defreq {uf, font}
|
||
@cindex underline font (@code{uf})
|
||
@cindex font for underlining (@code{uf})
|
||
Set the underline font (globally) used by @code{ul} and @code{cu}. By
|
||
default, this is the font at position@w{ }2. @var{font} can be either
|
||
a non-negative font position or the name of a font.
|
||
@endDefreq
|
||
|
||
@DefreqList {bd, font [@Var{offset}]}
|
||
@DefreqItem {bd, font1 font2 [@Var{offset}]}
|
||
@DefregListEnd {.b}
|
||
@cindex imitating bold face (@code{bd})
|
||
@cindex bold face, imitating (@code{bd})
|
||
Artificially create a bold font by printing each glyph twice,
|
||
slightly offset.
|
||
|
||
Two syntax forms are available.
|
||
|
||
@itemize @bullet
|
||
@item
|
||
Imitate a bold font unconditionally. The first argument specifies the
|
||
font to embolden, and the second is the number of basic units, minus
|
||
one, by which the two glyphs are offset. If the second argument is
|
||
missing, emboldening is turned off.
|
||
|
||
@var{font} can be either a non-negative font position or the name of a
|
||
font.
|
||
|
||
@var{offset} is available in the @code{.b} read-only register if a
|
||
special font is active; in the @code{bd} request, its default unit is
|
||
@samp{u}.
|
||
|
||
@cindex @code{fspecial} request, and imitating bold
|
||
@kindex special
|
||
@cindex embolding of special fonts
|
||
@cindex special fonts, emboldening
|
||
@item
|
||
Imitate a bold form conditionally. Embolden @var{font1} by
|
||
@var{offset} only if font @var{font2} is the current font. This
|
||
command can be issued repeatedly to set up different emboldening
|
||
values for different current fonts. If the second argument is
|
||
missing, emboldening is turned off for this particular current font.
|
||
|
||
This affects special fonts only (either set up with the @code{special}
|
||
command in font files or with the @code{fspecial} request).
|
||
@end itemize
|
||
@endDefreq
|
||
|
||
@Defreq {cs, font [@Var{width} [@Var{em-size}]]}
|
||
@cindex constant glyph space mode (@code{cs})
|
||
@cindex mode for constant glyph space (@code{cs})
|
||
@cindex glyph, constant space
|
||
@cindex @code{ps} request, and constant glyph space mode
|
||
Switch to and from @dfn{constant glyph space mode}. If activated, the
|
||
width of every glyph is @math{@var{width}/36} ems. The em size is
|
||
given absolutely by @var{em-size}; if this argument is missing, the em
|
||
value is taken from the current font size (as set with the @code{ps}
|
||
request) when the font is effectively in use. Without second and
|
||
third argument, constant glyph space mode is deactivated.
|
||
|
||
Default scaling indicator for @var{em-size} is @samp{z}; @var{width} is
|
||
an integer.
|
||
@endDefreq
|
||
|
||
@c ---------------------------------------------------------------------
|
||
|
||
@node Ligatures and Kerning, , Artificial Fonts, Fonts
|
||
@subsection Ligatures and Kerning
|
||
@cindex ligatures and kerning
|
||
@cindex kerning and ligatures
|
||
|
||
Ligatures are groups of characters that are run together, i.e, producing
|
||
a single glyph. For example, the letters `f' and `i' can form a
|
||
ligature `fi' as in the word `file'. This produces a cleaner look
|
||
(albeit subtle) to the printed output. Usually, ligatures are not
|
||
available in fonts for TTY output devices.
|
||
|
||
Most @sc{PostScript} fonts support the fi and fl ligatures. The C/A/T
|
||
typesetter that was the target of @acronym{AT&T} @code{troff} also
|
||
supported `ff', `ffi', and `ffl' ligatures. Advanced typesetters or
|
||
`expert' fonts may include ligatures for `ft' and `ct', although GNU
|
||
@code{troff} does not support these (yet).
|
||
|
||
@DefreqList {lg, [@Var{flag}]}
|
||
@DefregListEnd {.lg}
|
||
@cindex activating ligatures (@code{lg})
|
||
@cindex ligatures, activating (@code{lg})
|
||
@cindex ligatures enabled register (@code{.lg})
|
||
Switch the ligature mechanism on or off; if the parameter is non-zero
|
||
or missing, ligatures are enabled, otherwise disabled. Default is on.
|
||
The current ligature mode can be found in the read-only number register
|
||
@code{.lg} (set to 1 or@w{ }2 if ligatures are enabled, 0@w{ }otherwise).
|
||
|
||
Setting the ligature mode to@w{ }2 enables the two-character ligatures
|
||
(fi, fl, and ff) and disables the three-character ligatures (ffi and
|
||
ffl).
|
||
@endDefreq
|
||
|
||
@dfn{Pairwise kerning} is another subtle typesetting mechanism that
|
||
modifies the distance between a glyph pair to improve readability.
|
||
In most cases (but not always) the distance is decreased.
|
||
@ifnotinfo
|
||
For example, compare the combination of the letters `V' and `A'. With
|
||
kerning, `VA' is printed. Without kerning it appears as `V@w{}A'.
|
||
@end ifnotinfo
|
||
Typewriter-like fonts and fonts for terminals where all glyphs
|
||
have the same width don't use kerning.
|
||
|
||
@DefreqList {kern, [@Var{flag}]}
|
||
@DefregListEnd {.kern}
|
||
@cindex activating kerning (@code{kern})
|
||
@cindex kerning, activating (@code{kern})
|
||
@cindex kerning enabled register (@code{.kern})
|
||
Switch kerning on or off. If the parameter is non-zero or missing,
|
||
enable pairwise kerning, otherwise disable it. The read-only number
|
||
register @code{.kern} is set to@w{ }1 if pairwise kerning is enabled,
|
||
0@w{ }otherwise.
|
||
|
||
@cindex zero width space character (@code{\&})
|
||
@cindex character, zero width space (@code{\&})
|
||
@cindex space character, zero width (@code{\&})
|
||
If the font description file contains pairwise kerning information,
|
||
glyphs from that font are kerned. Kerning between two glyphs
|
||
can be inhibited by placing @code{\&} between them: @samp{V\&A}.
|
||
|
||
@xref{Font File Format}.
|
||
@endDefreq
|
||
|
||
@cindex track kerning
|
||
@cindex kerning, track
|
||
@dfn{Track kerning} expands or reduces the space between glyphs.
|
||
This can be handy, for example, if you need to squeeze a long word
|
||
onto a single line or spread some text to fill a narrow column. It
|
||
must be used with great care since it is usually considered bad
|
||
typography if the reader notices the effect.
|
||
|
||
@Defreq {tkf, f s1 n1 s2 n2}
|
||
@cindex activating track kerning (@code{tkf})
|
||
@cindex track kerning, activating (@code{tkf})
|
||
Enable track kerning for font@w{ }@var{f}. If the current font is@w{
|
||
}@var{f} the width of every glyph is increased by an amount
|
||
between @var{n1} and @var{n2} (@var{n1}, @var{n2} can be negative); if
|
||
the current point size is less than or equal to @var{s1} the width is
|
||
increased by @var{n1}; if it is greater than or equal to @var{s2} the
|
||
width is increased by @var{n2}; if the point size is greater than or
|
||
equal to @var{s1} and less than or equal to @var{s2} the increase in
|
||
width is a linear function of the point size.
|
||
|
||
The default scaling indicator is @samp{z} for @var{s1} and @var{s2},
|
||
@samp{p} for @var{n1} and @var{n2}.
|
||
|
||
Note that the track kerning amount is added even to the rightmost glyph
|
||
in a line; for large values it is thus recommended to increase the line
|
||
length by the same amount to compensate it.
|
||
@endDefreq
|
||
|
||
Sometimes, when typesetting letters of different fonts, more or less
|
||
space at such boundaries are needed. There are two escapes to help
|
||
with this.
|
||
|
||
@Defesc {\\/, , , }
|
||
@cindex italic correction (@code{\/})
|
||
@cindex correction, italic (@code{\/})
|
||
@cindex correction between italic and roman glyph (@code{\/}, @code{\,})
|
||
@cindex roman glyph, correction after italic glyph (@code{\/})
|
||
@cindex italic glyph, correction before roman glyph (@code{\/})
|
||
@cindex glyph, italic correction (@code{\/})
|
||
Increase the width of the preceding glyph so that the spacing
|
||
between that glyph and the following glyph is correct if the
|
||
following glyph is a roman glyph. For example, if an
|
||
italic@w{ }@code{f} is immediately followed by a roman right
|
||
parenthesis, then in many fonts the top right portion of the@w{ }@code{f}
|
||
overlaps the top left of the right parenthesis. Use this escape
|
||
sequence whenever an italic glyph is immediately followed by a
|
||
roman glyph without any intervening space. This small amount of
|
||
space is also called @dfn{italic correction}.
|
||
|
||
@iftex
|
||
@example
|
||
@group
|
||
\f[I]f\f[R])
|
||
@result{} {@it f}@r{)}
|
||
\f[I]f\/\f[R])
|
||
@result{} @i{f}@r{)}
|
||
@end group
|
||
@end example
|
||
@end iftex
|
||
@endDefesc
|
||
|
||
@Defesc {\\\,, , , }
|
||
@cindex left italic correction (@code{\,})
|
||
@cindex correction, left italic (@code{\,})
|
||
@cindex glyph, left italic correction (@code{\,})
|
||
@cindex roman glyph, correction before italic glyph (@code{\,})
|
||
@cindex italic glyph, correction after roman glyph (@code{\,})
|
||
Modify the spacing of the following glyph so that the spacing
|
||
between that glyph and the preceding glyph is correct if the
|
||
preceding glyph is a roman glyph. Use this escape sequence
|
||
whenever a roman glyph is immediately followed by an italic
|
||
glyph without any intervening space. In analogy to above, this
|
||
space could be called @dfn{left italic correction}, but this term
|
||
isn't used widely.
|
||
|
||
@iftex
|
||
@example
|
||
@group
|
||
q\f[I]f
|
||
@result{} @r{q}@i{f}
|
||
q\,\f[I]f
|
||
@result{} @r{q}@math{@ptexcomma}@i{f}
|
||
@end group
|
||
@end example
|
||
@end iftex
|
||
@endDefesc
|
||
|
||
@Defesc {\\&, , , }
|
||
Insert a zero-width character, which is invisible. Its intended use
|
||
is to stop interaction of a character with its surrounding.
|
||
|
||
@itemize @bullet
|
||
@item
|
||
It prevents the insertion of extra space after an end-of-sentence
|
||
character.
|
||
|
||
@Example
|
||
Test.
|
||
Test.
|
||
@result{} Test. Test.
|
||
Test.\&
|
||
Test.
|
||
@result{} Test. Test.
|
||
@endExample
|
||
|
||
@item
|
||
It prevents interpretation of a control character at the beginning of
|
||
an input line.
|
||
|
||
@Example
|
||
.Test
|
||
@result{} warning: `Test' not defined
|
||
\&.Test
|
||
@result{} .Test
|
||
@endExample
|
||
|
||
@item
|
||
It prevents kerning between two glyphs.
|
||
|
||
@ifnotinfo
|
||
@example
|
||
@group
|
||
VA
|
||
@result{} @r{VA}
|
||
V\&A
|
||
@result{} @r{V@w{}A}
|
||
@end group
|
||
@end example
|
||
@end ifnotinfo
|
||
|
||
@item
|
||
It is needed to map an arbitrary character to nothing in the @code{tr}
|
||
request (@pxref{Character Translations}).
|
||
@end itemize
|
||
@endDefesc
|
||
|
||
@Defesc {\\), , , }
|
||
This escape is similar to @code{\&} except that it behaves like a
|
||
character declared with the @code{cflags} request to be transparent
|
||
for the purposes of an end-of-sentence character.
|
||
|
||
Its main usage is in macro definitions to protect against arguments
|
||
starting with a control character.
|
||
|
||
@Example
|
||
.de xxx
|
||
\)\\$1
|
||
..
|
||
.de yyy
|
||
\&\\$1
|
||
..
|
||
This is a test.\c
|
||
.xxx '
|
||
This is a test.
|
||
@result{}This is a test.' This is a test.
|
||
This is a test.\c
|
||
.yyy '
|
||
This is a test.
|
||
@result{}This is a test.' This is a test.
|
||
@endExample
|
||
@endDefesc
|
||
|
||
|
||
@c =====================================================================
|
||
|
||
@node Sizes, Strings, Fonts, gtroff Reference
|
||
@section Sizes
|
||
@cindex sizes
|
||
|
||
@cindex baseline
|
||
@cindex type size
|
||
@cindex size of type
|
||
@cindex vertical spacing
|
||
@cindex spacing, vertical
|
||
@code{gtroff} uses two dimensions with each line of text, type size
|
||
and vertical spacing. The @dfn{type size} is approximately the height
|
||
of the tallest glyph.@footnote{This is usually the parenthesis.
|
||
Note that in most cases the real dimensions of the glyphs in a font
|
||
are @emph{not} related to its type size! For example, the standard
|
||
@sc{PostScript} font families `Times Roman', `Helvetica', and
|
||
`Courier' can't be used together at 10@dmn{pt}; to get acceptable
|
||
output, the size of `Helvetica' has to be reduced by one point, and
|
||
the size of `Courier' must be increased by one point.} @dfn{Vertical
|
||
spacing} is the amount of space @code{gtroff} allows for a line of
|
||
text; normally, this is about 20%@w{ }larger than the current type
|
||
size. Ratios smaller than this can result in hard-to-read text;
|
||
larger than this, it spreads the text out more vertically (useful for
|
||
term papers). By default, @code{gtroff} uses 10@w{ }point type on
|
||
12@w{ }point spacing.
|
||
|
||
@cindex leading
|
||
The difference between type size and vertical spacing is known, by
|
||
typesetters, as @dfn{leading} (this is pronounced `ledding').
|
||
|
||
@menu
|
||
* Changing Type Sizes::
|
||
* Fractional Type Sizes::
|
||
@end menu
|
||
|
||
@c ---------------------------------------------------------------------
|
||
|
||
@node Changing Type Sizes, Fractional Type Sizes, Sizes, Sizes
|
||
@subsection Changing Type Sizes
|
||
|
||
@DefreqList {ps, [@Var{size}]}
|
||
@DefreqItem {ps, @t{+}@Var{size}}
|
||
@DefreqItem {ps, @t{-}@Var{size}}
|
||
@DefescItem {\\s, , size, }
|
||
@DefregListEnd {.s}
|
||
@cindex changing type sizes (@code{ps}, @code{\s})
|
||
@cindex type sizes, changing (@code{ps}, @code{\s})
|
||
@cindex point sizes, changing (@code{ps}, @code{\s})
|
||
Use the @code{ps} request or the @code{\s} escape to change (increase,
|
||
decrease) the type size (in points). Specify @var{size} as either an
|
||
absolute point size, or as a relative change from the current size.
|
||
The size@w{ }0, or no argument, goes back to the previous size.
|
||
|
||
Default scaling indicator of @code{size} is @samp{z}. If @code{size}
|
||
is zero or negative, it is set to 1@dmn{u}.
|
||
|
||
@cindex type size registers (@code{.s}, @code{.ps})
|
||
@cindex point size registers (@code{.s}, @code{.ps})
|
||
The read-only number register @code{.s} returns the point size in
|
||
points as a decimal fraction. This is a string. To get the point
|
||
size in scaled points, use the @code{.ps} register instead.
|
||
|
||
@code{.s} is associated with the current environment
|
||
(@pxref{Environments}).
|
||
|
||
@Example
|
||
snap, snap,
|
||
.ps +2
|
||
grin, grin,
|
||
.ps +2
|
||
wink, wink, \s+2nudge, nudge,\s+8 say no more!
|
||
.ps 10
|
||
@endExample
|
||
|
||
The @code{\s} escape may be called in a variety of ways. Much like
|
||
other escapes there must be a way to determine where the argument ends
|
||
and the text begins. Any of the following forms are valid:
|
||
|
||
@table @code
|
||
@item \s@var{n}
|
||
Set the point size to @var{n}@w{ }points. @var{n}@w{ }must be either
|
||
0 or in the range 4 to@w{ }39.
|
||
|
||
@item \s+@var{n}
|
||
@itemx \s-@var{n}
|
||
Increase or decrease the point size by @var{n}@w{ }points. @var{n}@w{
|
||
}must be exactly one digit.
|
||
|
||
@item \s(@var{nn}
|
||
Set the point size to @var{nn}@w{ }points. @var{nn} must be exactly
|
||
two digits.
|
||
|
||
@item \s+(@var{nn}
|
||
@itemx \s-(@var{nn}
|
||
@itemx \s(+@var{nn}
|
||
@itemx \s(-@var{nn}
|
||
Increase or decrease the point size by @var{nn}@w{ }points. @var{nn}
|
||
must be exactly two digits.
|
||
@end table
|
||
|
||
Note that @code{\s} doesn't produce an input token in @code{gtroff}.
|
||
As a consequence, it can be used in requests like @code{mc} (which
|
||
expects a single character as an argument) to change the font on
|
||
the fly:
|
||
|
||
@Example
|
||
.mc \s[20]x\s[0]
|
||
@endExample
|
||
|
||
@xref{Fractional Type Sizes}, for yet another syntactical form of
|
||
using the @code{\s} escape.
|
||
@endDefreq
|
||
|
||
@Defreq {sizes, s1 s2 @dots{} sn [0]}
|
||
Some devices may only have certain permissible sizes, in which case
|
||
@code{gtroff} rounds to the nearest permissible size.
|
||
The @file{DESC} file specifies which sizes are permissible for the device.
|
||
|
||
Use the @code{sizes} request to change the permissible sizes
|
||
for the current output device.
|
||
Arguments are in scaled points;
|
||
the @code{sizescale} line in the
|
||
@file{DESC} file for the output device
|
||
provides the scaling factor.
|
||
For example, if the scaling factor is 1000,
|
||
then the value 12000 is 12@w{ }points.
|
||
|
||
Each argument can be a single point size (such as @samp{12000}),
|
||
or a range of sizes (such as @samp{4000-72000}).
|
||
You can optionally end the list with a zero.
|
||
@endDefreq
|
||
|
||
@DefreqList {vs, [@Var{space}]}
|
||
@DefreqItem {vs, @t{+}@Var{space}}
|
||
@DefreqItem {vs, @t{-}@Var{space}}
|
||
@DefregListEnd {.v}
|
||
@cindex changing vertical line spacing (@code{vs})
|
||
@cindex vertical line spacing, changing (@code{vs})
|
||
@cindex vertical line spacing register (@code{.v})
|
||
Change (increase, decrease) the vertical spacing by @var{space}. The
|
||
default scaling indicator is @samp{p}.
|
||
|
||
If @code{vs} is called without an argument, the vertical spacing is
|
||
reset to the previous value before the last call to @code{vs}.
|
||
|
||
@cindex @code{.V} register, and @code{vs}
|
||
@code{gtroff} creates a warning of type @samp{range} if @var{space} is
|
||
zero or negative; the vertical spacing is then set to the vertical
|
||
resolution (as given in the @code{.V} register).
|
||
|
||
The read-only number register @code{.v} contains the current vertical
|
||
spacing; it is associated with the current environment
|
||
(@pxref{Environments}).
|
||
@endDefreq
|
||
|
||
@cindex vertical line spacing, effective value
|
||
The effective vertical line spacing consists of four components.
|
||
|
||
@itemize @bullet
|
||
@item
|
||
The vertical line spacing as set with the @code{vs} request.
|
||
|
||
@cindex post-vertical line spacing
|
||
@cindex line spacing, post-vertical (@code{pvs})
|
||
@item
|
||
The @dfn{post-vertical line spacing} as set with the @code{pvs} request.
|
||
This is vertical space which will be added after a line has been
|
||
output.
|
||
|
||
@cindex extra pre-vertical line space (@code{\x})
|
||
@cindex line space, extra pre-vertical (@code{\x})
|
||
@item
|
||
The @dfn{extra pre-vertical line space} as set with the @code{\x} request,
|
||
using a negative value. This is vertical space which will be added once
|
||
before the current line has been output.
|
||
|
||
@cindex extra post-vertical line space (@code{\x})
|
||
@cindex line space, extra post-vertical (@code{\x})
|
||
@item
|
||
The @dfn{extra post-vertical line space} as set with the @code{\x} request,
|
||
using a positive value. This is vertical space which will be added once
|
||
after the current line has been output.
|
||
@end itemize
|
||
|
||
@cindex double-spacing (@code{vs}, @code{pvs})
|
||
It is usually better to use @code{vs} or @code{pvs} instead of @code{ls}
|
||
to produce double-spaced documents: @code{vs} and @code{pvs} have a finer
|
||
granularity for the inserted vertical space compared to @code{ls};
|
||
furthermore, certain preprocessors assume single-spacing.
|
||
|
||
@xref{Manipulating Spacing}, for more details on the @code{\x} escape
|
||
and the @code{ls} request.
|
||
|
||
@DefreqList {pvs, [@Var{space}]}
|
||
@DefreqItem {pvs, @t{+}@Var{space}}
|
||
@DefreqItem {pvs, @t{-}@Var{space}}
|
||
@DefregListEnd {.pvs}
|
||
@cindex @code{ls} request, alternative to (@code{pvs})
|
||
@cindex post-vertical line spacing, changing (@code{pvs})
|
||
@cindex post-vertical line spacing register (@code{.pvs})
|
||
Change (increase, decrease) the post-vertical spacing by
|
||
@var{space}. The default scaling indicator is @samp{p}.
|
||
|
||
If @code{pvs} is called without an argument, the post-vertical spacing is
|
||
reset to the previous value before the last call to @code{pvs}.
|
||
|
||
@code{gtroff} creates a warning of type @samp{range} if @var{space} is
|
||
zero or negative; the vertical spacing is then set to zero.
|
||
|
||
The read-only number register @code{.pvs} contains the current
|
||
post-vertical spacing; it is associated with the current environment
|
||
(@pxref{Environments}).
|
||
@endDefreq
|
||
|
||
|
||
@c ---------------------------------------------------------------------
|
||
|
||
@node Fractional Type Sizes, , Changing Type Sizes, Sizes
|
||
@subsection Fractional Type Sizes
|
||
@cindex fractional type sizes
|
||
@cindex fractional point sizes
|
||
@cindex type sizes, fractional
|
||
@cindex point sizes, fractional
|
||
@cindex sizes, fractional
|
||
|
||
@cindex @code{s} unit
|
||
@cindex unit, @code{s}
|
||
@cindex @code{z} unit
|
||
@cindex unit, @code{z}
|
||
@cindex @code{ps} request, with fractional type sizes
|
||
@cindex @code{cs} request, with fractional type sizes
|
||
@cindex @code{tkf} request, with fractional type sizes
|
||
@cindex @code{\H}, with fractional type sizes
|
||
@cindex @code{\s}, with fractional type sizes
|
||
A @dfn{scaled point} is equal to @math{1/@var{sizescale}} points,
|
||
where @var{sizescale} is specified in the @file{DESC} file (1@w{ }by
|
||
default). There is a new scale indicator @samp{z} which has the
|
||
effect of multiplying by @var{sizescale}. Requests and escape
|
||
sequences in @code{gtroff} interpret arguments that represent a point
|
||
size as being in units of scaled points, but they evaluate each such
|
||
argument using a default scale indicator of @samp{z}. Arguments
|
||
treated in this way are the argument to the @code{ps} request, the
|
||
third argument to the @code{cs} request, the second and fourth
|
||
arguments to the @code{tkf} request, the argument to the @code{\H}
|
||
escape sequence, and those variants of the @code{\s} escape sequence
|
||
that take a numeric expression as their argument (see below).
|
||
|
||
For example, suppose @var{sizescale} is@w{ }1000; then a scaled point
|
||
is equivalent to a millipoint; the request @w{@samp{.ps 10.25}} is
|
||
equivalent to @w{@samp{.ps 10.25z}} and thus sets the point size to
|
||
10250@w{ }scaled points, which is equal to 10.25@w{ }points.
|
||
|
||
@code{gtroff} disallows the use of the @samp{z} scale indicator in
|
||
instances where it would make no sense, such as a numeric
|
||
expression whose default scale indicator was neither @samp{u} nor
|
||
@samp{z}. Similarly it would make
|
||
no sense to use a scaling indicator other than @samp{z} or @samp{u} in a
|
||
numeric expression whose default scale indicator was @samp{z}, and so
|
||
@code{gtroff} disallows this as well.
|
||
|
||
There is also new scale indicator @samp{s} which multiplies by the
|
||
number of units in a scaled point. So, for example, @samp{\n[.ps]s} is
|
||
equal to @samp{1m}. Be sure not to confuse the @samp{s} and @samp{z}
|
||
scale indicators.
|
||
|
||
@Defreg {.ps}
|
||
A read-only number register returning the point size in scaled points.
|
||
|
||
@code{.ps} is associated with the current environment
|
||
(@pxref{Environments}).
|
||
@endDefreg
|
||
|
||
@DefregList {.psr}
|
||
@DefregListEnd {.sr}
|
||
@cindex last-requested point size registers (@code{.psr}, @code{.sr})
|
||
@cindex point size registers, last-requested (@code{.psr}, @code{.sr})
|
||
@cindex @code{.ps} register, in comparison with @code{.psr}
|
||
@cindex @code{.s} register, in comparison with @code{.sr}
|
||
The last-requested point size in scaled points is contained in the
|
||
@code{.psr} read-only number register. The last requested point size
|
||
in points as a decimal fraction can be found in @code{.sr}. This is a
|
||
string-valued read-only number register.
|
||
|
||
Note that the requested point sizes are device-independent, whereas
|
||
the values returned by the @code{.ps} and @code{.s} registers are not.
|
||
For example, if a point size of 11@dmn{pt} is requested, and a
|
||
@code{sizes} request (or a @code{sizescale} line in a @file{DESC} file)
|
||
specifies 10.95@dmn{pt} instead, this value is actually used.
|
||
|
||
Both registers are associated with the current environment
|
||
(@pxref{Environments}).
|
||
@endDefreg
|
||
|
||
The @code{\s} escape has the following syntax for working with
|
||
fractional type sizes:
|
||
|
||
@table @code
|
||
@item \s[@var{n}]
|
||
@itemx \s'@var{n}'
|
||
Set the point size to @var{n}@w{ }scaled points; @var{n}@w{ }is a numeric
|
||
expression with a default scale indicator of @samp{z}.
|
||
|
||
@item \s[+@var{n}]
|
||
@itemx \s[-@var{n}]
|
||
@itemx \s+[@var{n}]
|
||
@itemx \s-[@var{n}]
|
||
@itemx \s'+@var{n}'
|
||
@itemx \s'-@var{n}'
|
||
@itemx \s+'@var{n}'
|
||
@itemx \s-'@var{n}'
|
||
Increase or or decrease the point size by @var{n}@w{ }scaled points;
|
||
@var{n}@w{ }is a numeric expression with a default scale indicator of
|
||
@samp{z}.
|
||
@end table
|
||
|
||
@xref{Font Files}.
|
||
|
||
|
||
@c =====================================================================
|
||
|
||
@node Strings, Conditionals and Loops, Sizes, gtroff Reference
|
||
@section Strings
|
||
@cindex strings
|
||
|
||
@code{gtroff} has string variables, which are entirely for user
|
||
convenience (i.e.@: there are no built-in strings exept @code{.T}, but
|
||
even this is a read-write string variable).
|
||
|
||
@DefreqList {ds, name [@Var{string}]}
|
||
@DefreqItem {ds1, name [@Var{string}]}
|
||
@DefescItem {\\*, , n, }
|
||
@DefescItem {\\*, @lparen{}, nm, }
|
||
@DefescListEnd {\\*, @lbrack{}, name arg1 arg2 @dots{}, @rbrack{}}
|
||
@cindex string interpolation (@code{\*})
|
||
@cindex string expansion (@code{\*})
|
||
@cindex interpolation of strings (@code{\*})
|
||
@cindex expansion of strings (@code{\*})
|
||
@cindex string arguments
|
||
@cindex arguments, of strings
|
||
Define and access a string variable @var{name} (one-character name@w{
|
||
}@var{n}, two-character name @var{nm}). If @var{name} already exists,
|
||
@code{ds} overwrites the previous definition. Only the syntax form
|
||
using brackets can take arguments which are handled identically to
|
||
macro arguments; the single exception is that a closing bracket as an
|
||
argument must be enclosed in double quotes. @xref{Request Arguments},
|
||
and @ref{Parameters}.
|
||
|
||
Example:
|
||
|
||
@Example
|
||
.ds foo a \\$1 test
|
||
.
|
||
This is \*[foo nice].
|
||
@result{} This is a nice test.
|
||
@endExample
|
||
|
||
The @code{\*} escape @dfn{interpolates} (expands in-place) a
|
||
previously-defined string variable. To be more precise, the stored
|
||
string is pushed onto the input stack which is then parsed by
|
||
@code{gtroff}. Similar to number registers, it is possible to nest
|
||
strings, i.e. string variables can be called within string variables.
|
||
|
||
If the string named by the @code{\*} escape does not exist, it is
|
||
defined as empty, and a warning of type @samp{mac} is emitted (see
|
||
@ref{Debugging}, for more details).
|
||
|
||
@cindex comments, with @code{ds}
|
||
@cindex @code{ds} request, and comments
|
||
@strong{Caution:} Unlike other requests, the second argument to the
|
||
@code{ds} request takes up the entire line including trailing spaces.
|
||
This means that comments on a line with such a request can introduce
|
||
unwanted space into a string.
|
||
|
||
@Example
|
||
.ds UX \s-1UNIX\s0\u\s-3tm\s0\d \" UNIX trademark
|
||
@endExample
|
||
|
||
@noindent
|
||
Instead the comment should be put on another line or have the comment
|
||
escape adjacent with the end of the string.
|
||
|
||
@Example
|
||
.ds UX \s-1UNIX\s0\u\s-3tm\s0\d\" UNIX trademark
|
||
@endExample
|
||
|
||
@cindex trailing quotes
|
||
@cindex quotes, trailing
|
||
@cindex leading spaces with @code{ds}
|
||
@cindex spaces with @code{ds}
|
||
@cindex @code{ds} request, and leading spaces
|
||
To produce leading space the string can be started with a double
|
||
quote. No trailing quote is needed; in fact, any trailing quote is
|
||
included in your string.
|
||
|
||
@Example
|
||
.ds sign " Yours in a white wine sauce,
|
||
@endExample
|
||
|
||
@cindex multi-line strings
|
||
@cindex strings, multi-line
|
||
@cindex newline character, in strings, escaping
|
||
@cindex escaping newline characters, in strings
|
||
Strings are not limited to a single line of text. A string can span
|
||
several lines by escaping the newlines with a backslash. The
|
||
resulting string is stored @emph{without} the newlines.
|
||
|
||
@Example
|
||
.ds foo lots and lots \
|
||
of text are on these \
|
||
next several lines
|
||
@endExample
|
||
|
||
It is not possible to have real newlines in a string. To put a single
|
||
double quote character into a string, use two consecutive double quote
|
||
characters.
|
||
|
||
The @code{ds1} request turns off compatibility mode
|
||
while interpreting a string. To be more precise, a @dfn{compatibility
|
||
save} input token is inserted at the beginning of the string, and a
|
||
@dfn{compatibility restore} input token at the end.
|
||
|
||
@Example
|
||
.nr xxx 12345
|
||
.ds aa The value of xxx is \\n[xxx].
|
||
.ds1 bb The value of xxx ix \\n[xxx].
|
||
.
|
||
.cp 1
|
||
.
|
||
\*(aa
|
||
@result{} warning: number register `[' not defined
|
||
@result{} The value of xxx is 0xxx].
|
||
\*(bb
|
||
@result{} The value of xxx ix 12345.
|
||
@endExample
|
||
|
||
@cindex name space, common, of macros, diversions, and strings
|
||
@cindex common name space of macros, diversions, and strings
|
||
@cindex macros, shared name space with strings and diversions
|
||
@cindex strings, shared name space with macros and diversions
|
||
@cindex diversions, shared name space with macros and strings
|
||
Strings, macros, and diversions (and boxes) share the same name space.
|
||
Internally, even the same mechanism is used to store them. This has
|
||
some interesting consequences. For example, it is possible to call a
|
||
macro with string syntax and vice versa.
|
||
|
||
@Example
|
||
.de xxx
|
||
a funny test.
|
||
..
|
||
This is \*[xxx]
|
||
@result{} This is a funny test.
|
||
|
||
.ds yyy a funny test
|
||
This is
|
||
.yyy
|
||
@result{} This is a funny test.
|
||
@endExample
|
||
|
||
Diversions and boxes can be also called with string syntax.
|
||
|
||
Another consequence is that you can copy one-line diversions or boxes
|
||
to a string.
|
||
|
||
@Example
|
||
.di xxx
|
||
a \fItest\fR
|
||
.br
|
||
.di
|
||
.ds yyy This is \*[xxx]\c
|
||
\*[yyy].
|
||
@result{} @r{This is a }@i{test}.
|
||
@endExample
|
||
|
||
@noindent
|
||
As the previous example shows, it is possible to store formatted
|
||
output in strings. The @code{\c} escape prevents the insertion of an
|
||
additional blank line in the output.
|
||
|
||
Copying diversions longer than a single output line produces
|
||
unexpected results.
|
||
|
||
@Example
|
||
.di xxx
|
||
a funny
|
||
.br
|
||
test
|
||
.br
|
||
.di
|
||
.ds yyy This is \*[xxx]\c
|
||
\*[yyy].
|
||
@result{} test This is a funny.
|
||
@endExample
|
||
|
||
Usually, it is not predictable whether a diversion contains one or
|
||
more output lines, so this mechanism should be avoided. With
|
||
@acronym{UNIX} @code{troff}, this was the only solution to strip off a
|
||
final newline from a diversion. Another disadvantage is that the
|
||
spaces in the copied string are already formatted, making them
|
||
unstretchable. This can cause ugly results.
|
||
|
||
@cindex stripping final newline in diversions
|
||
@cindex diversion, stripping final newline
|
||
@cindex final newline, stripping in diversions
|
||
@cindex newline, final, stripping in diversions
|
||
@cindex horizontal space, unformatting
|
||
@cindex space, horizontal, unformatting
|
||
@cindex unformatting horizontal space
|
||
A clean solution to this problem is available in GNU @code{troff},
|
||
using the requests @code{chop} to remove the final newline of a
|
||
diversion, and @code{unformat} to make the horizontal spaces
|
||
stretchable again.
|
||
|
||
@Example
|
||
.box xxx
|
||
a funny
|
||
.br
|
||
test
|
||
.br
|
||
.box
|
||
.chop xxx
|
||
.unformat xxx
|
||
This is \*[xxx].
|
||
@result{} This is a funny test.
|
||
@endExample
|
||
|
||
@xref{Gtroff Internals}, for more information.
|
||
@endDefreq
|
||
|
||
@DefreqList {as, name [@Var{string}]}
|
||
@DefreqListEnd {as1, name [@Var{string}]}
|
||
@cindex appending to a string (@code{as})
|
||
@cindex string, appending (@code{as})
|
||
The @code{as} request is similar to @code{ds} but appends @var{string}
|
||
to the string stored as @var{name} instead of redefining it. If
|
||
@var{name} doesn't exist yet, it is created.
|
||
|
||
@Example
|
||
.as sign " with shallots, onions and garlic,
|
||
@endExample
|
||
|
||
The @code{as1} request is similar to @code{as}, but compatibility mode
|
||
is switched off while the appended string is interpreted. To be more
|
||
precise, a @dfn{compatibility save} input token is inserted at the
|
||
beginning of the appended string, and a @dfn{compatibility restore}
|
||
input token at the end.
|
||
@endDefreq
|
||
|
||
Rudimentary string manipulation routines are given with the next two
|
||
requests.
|
||
|
||
@Defreq {substring, str n1 [@Var{n2}]}
|
||
@cindex substring (@code{substring})
|
||
Replace the string named @var{str} with the substring
|
||
defined by the indices @var{n1} and@w{ }@var{n2}. The first character
|
||
in the string has index@w{ }0. If @var{n2} is omitted, it is taken to
|
||
be equal to the string's length. If the index value @var{n1} or
|
||
@var{n2} is negative, it is counted from the end of the
|
||
string, going backwards: The last character has index@w{ }@minus{}1, the
|
||
character before the last character has index@w{ }@minus{}2, etc.
|
||
|
||
@Example
|
||
.ds xxx abcdefgh
|
||
.substring xxx 1 -4
|
||
\*[xxx]
|
||
@result{} bcde
|
||
@endExample
|
||
@endDefreq
|
||
|
||
@Defreq {length, reg str}
|
||
@cindex length of a string (@code{length})
|
||
@cindex string, length of (@code{length})
|
||
Compute the number of characters of @var{str} and return it in the
|
||
number register @var{reg}. If @var{reg} doesn't exist, it is created.
|
||
@code{str} is read in copy mode.
|
||
|
||
@Example
|
||
.ds xxx abcd\h'3i'efgh
|
||
.length yyy \n[xxx]
|
||
\n[yyy]
|
||
@result{} 14
|
||
@endExample
|
||
@endDefreq
|
||
|
||
@Defreq {rn, xx yy}
|
||
@cindex renaming request (@code{rn})
|
||
@cindex request, renaming (@code{rn})
|
||
@cindex renaming macro (@code{rn})
|
||
@cindex macro, renaming (@code{rn})
|
||
@cindex renaming string (@code{rn})
|
||
@cindex string, renaming (@code{rn})
|
||
@cindex renaming diversion (@code{rn})
|
||
@cindex diversion, renaming (@code{rn})
|
||
Rename the request, macro, diversion, or string @var{xx} to @var{yy}.
|
||
@endDefreq
|
||
|
||
@Defreq {rm, xx}
|
||
@cindex removing request (@code{rm})
|
||
@cindex request, removing (@code{rm})
|
||
@cindex removing macro (@code{rm})
|
||
@cindex macro, removing (@code{rm})
|
||
@cindex removing string (@code{rm})
|
||
@cindex string, removing (@code{rm})
|
||
@cindex removing diversion (@code{rm})
|
||
@cindex diversion, removing (@code{rm})
|
||
Remove the request, macro, diversion, or string @var{xx}. @code{gtroff}
|
||
treats subsequent invocations as if the object had never been defined.
|
||
@endDefreq
|
||
|
||
@Defreq {als, new old}
|
||
@cindex alias, string, creating (@code{als})
|
||
@cindex alias, macro, creating (@code{als})
|
||
@cindex alias, diversion, creating (@code{als})
|
||
@cindex creating alias, for string (@code{als})
|
||
@cindex creating alias, for macro (@code{als})
|
||
@cindex creating alias, for diversion (@code{als})
|
||
@cindex string, creating alias (@code{als})
|
||
@cindex macro, creating alias (@code{als})
|
||
@cindex diversion, creating alias (@code{als})
|
||
Create an alias named @var{new} for the request, string, macro, or
|
||
diversion object named @var{old}. The new name and the old name are
|
||
exactly equivalent (it is similar to a hard rather than a soft
|
||
link). If @var{old} is undefined, @code{gtroff} generates a warning of
|
||
type @samp{mac} and ignores the request.
|
||
@endDefreq
|
||
|
||
@Defreq {chop, xx}
|
||
Remove (chop) the last character from the macro, string, or diversion
|
||
named @var{xx}. This is useful for removing the newline from the end
|
||
of diversions that are to be interpolated as strings. This command
|
||
can be used repeatedly; see @ref{Gtroff Internals}, for details on
|
||
nodes inserted additionally by @code{gtroff}.
|
||
@endDefreq
|
||
|
||
@xref{Identifiers}, and @ref{Comments}.
|
||
|
||
|
||
@c =====================================================================
|
||
|
||
@node Conditionals and Loops, Writing Macros, Strings, gtroff Reference
|
||
@section Conditionals and Loops
|
||
@cindex conditionals and loops
|
||
@cindex loops and conditionals
|
||
|
||
@menu
|
||
* Operators in Conditionals::
|
||
* if-else::
|
||
* while::
|
||
@end menu
|
||
|
||
@c ---------------------------------------------------------------------
|
||
|
||
@node Operators in Conditionals, if-else, Conditionals and Loops, Conditionals and Loops
|
||
@subsection Operators in Conditionals
|
||
|
||
@cindex @code{if} request, operators to use with
|
||
@cindex @code{while} request, operators to use with
|
||
In @code{if} and @code{while} requests, there are several more
|
||
operators available:
|
||
|
||
@table @code
|
||
@item e
|
||
@itemx o
|
||
True if the current page is even or odd numbered (respectively).
|
||
|
||
@item n
|
||
True if the document is being processed in nroff mode (i.e., the
|
||
@code{.nroff} command has been issued).
|
||
|
||
@item t
|
||
True if the document is being processed in troff mode (i.e., the
|
||
@code{.troff} command has been issued).
|
||
|
||
@item v
|
||
Always false. This condition is for compatibility with other
|
||
@code{troff} versions only.
|
||
|
||
@item '@var{xxx}'@var{yyy}'
|
||
True if the string @var{xxx} is equal to the string @var{yyy}. Other
|
||
characters can be used in place of the single quotes; the same set of
|
||
delimiters as for the @code{\D} escape is used (@pxref{Escapes}).
|
||
@code{gtroff} formats the strings before being compared:
|
||
|
||
@Example
|
||
.ie "|"\fR|\fP" \
|
||
true
|
||
.el \
|
||
false
|
||
@result{} true
|
||
@endExample
|
||
|
||
@noindent
|
||
The resulting motions, glyph sizes, and fonts have to
|
||
match,@footnote{The created output nodes must be identical.
|
||
@xref{Gtroff Internals}.} and not the individual motion, size, and
|
||
font requests. In the previous example, @samp{|} and @samp{\fR|\fP}
|
||
both result in a roman @samp{|} glyph with the same point size and
|
||
at the same location on the page, so the strings are equal. If
|
||
@samp{.ft@w{ }I} had been added before the @samp{.ie}, the result
|
||
would be ``false'' because (the first) @samp{|} produces an italic
|
||
@samp{|} rather than a roman one.
|
||
|
||
@item r @var{xxx}
|
||
True if there is a number register named @var{xxx}.
|
||
|
||
@item d @var{xxx}
|
||
True if there is a string, macro, diversion, or request named @var{xxx}.
|
||
|
||
@item m @var{xxx}
|
||
True if there is a color named @var{xxx}.
|
||
|
||
@item c @var{g}
|
||
True if there is a glyph @var{g} available@footnote{The name of this
|
||
conditional operator is a misnomer since it tests names of output
|
||
glyphs.}; @var{g} is either an @acronym{ASCII} character or a special
|
||
character (@code{\(@var{gg}} or @code{\[@var{ggg}]}); the condition
|
||
is also true if @var{g} has been defined by the @code{char} request.
|
||
@end table
|
||
|
||
Note that these operators can't be combined with other operators like
|
||
@samp{:} or @samp{&}; only a leading @samp{!} (without whitespace
|
||
between the exclamation mark and the operator) can be used to negate
|
||
the result.
|
||
|
||
@Example
|
||
.nr xxx 1
|
||
.ie !r xxx \
|
||
true
|
||
.el \
|
||
false
|
||
@result{} false
|
||
@endExample
|
||
|
||
A whitespace after @samp{!} always evaluates to zero (this bizarre
|
||
behaviour is due to compatibility with @acronym{UNIX} @code{troff}).
|
||
|
||
@Example
|
||
.nr xxx 1
|
||
.ie ! r xxx \
|
||
true
|
||
.el \
|
||
false
|
||
@result{} r xxx true
|
||
@endExample
|
||
|
||
It is possible to omit the whitespace before the argument to the
|
||
@samp{r}, @samp{d}, and @samp{c} operators.
|
||
|
||
@xref{Expressions}.
|
||
|
||
@c ---------------------------------------------------------------------
|
||
|
||
@node if-else, while, Operators in Conditionals, Conditionals and Loops
|
||
@subsection if-else
|
||
@cindex if-else
|
||
|
||
@code{gtroff} has if-then-else constructs like other languages, although
|
||
the formatting can be painful.
|
||
|
||
@Defreq {if, expr anything}
|
||
Evaluate the expression @var{expr}, and executes @var{anything} (the
|
||
remainder of the line) if @var{expr} evaluates to non-zero (true).
|
||
@var{anything} is interpreted as though it was on a line by itself
|
||
(except that leading spaces are swallowed). @xref{Expressions}, for
|
||
more info.
|
||
|
||
@Example
|
||
.nr xxx 1
|
||
.nr yyy 2
|
||
.if ((\n[xxx] == 1) & (\n[yyy] == 2)) true
|
||
@result{} true
|
||
@endExample
|
||
@endDefreq
|
||
|
||
@Defreq{nop, anything}
|
||
Executes @var{anything}.
|
||
This is similar to @code{.if@w{ }1}.
|
||
@endDefreq
|
||
|
||
@DefreqList {ie, expr anything}
|
||
@DefreqListEnd {el, anything}
|
||
Use the @code{ie} and @code{el} requests to write an if-then-else.
|
||
The first request is the `if' part and the latter is the `else' part.
|
||
|
||
@Example
|
||
.ie n .ls 2 \" double-spacing in nroff
|
||
.el .ls 1 \" single-spacing in troff
|
||
@endExample
|
||
@endDefreq
|
||
|
||
@c there is a bug in makeinfo <= 4.1a: you can't have `@{' as an argument
|
||
@c to @deffn
|
||
@c
|
||
@c and in 4.2 you still can't use @{ in macros.
|
||
|
||
@c @DefescList {\@{, , , }
|
||
@c @DefescListEnd {\@}, , , }
|
||
@deffn Escape @t{\@{}
|
||
@deffnx Escape @t{\@}}
|
||
@esindex \@{
|
||
@esindex \@}
|
||
@cindex begin of conditional block (@code{\@{})
|
||
@cindex end of conditional block (@code{\@}})
|
||
@cindex conditional block, begin (@code{\@{})
|
||
@cindex conditional block, end (@code{\@}})
|
||
@cindex block, conditional, begin (@code{\@{})
|
||
@cindex block, condititional, end (@code{\@}})
|
||
In many cases, an if (or if-else) construct needs to execute more than
|
||
one request. This can be done using the @code{\@{} and @code{\@}}
|
||
escapes. The following example shows the possible ways to use these
|
||
escapes (note the position of the opening and closing braces).
|
||
|
||
@Example
|
||
.ie t \@{\
|
||
. ds lq ``
|
||
. ds rq ''
|
||
.\@}
|
||
.el \
|
||
.\@{\
|
||
. ds lq "
|
||
. ds rq "\@}
|
||
@endExample
|
||
@c @endDefesc
|
||
@end deffn
|
||
|
||
@xref{Expressions}.
|
||
|
||
@c ---------------------------------------------------------------------
|
||
|
||
@node while, , if-else, Conditionals and Loops
|
||
@subsection while
|
||
@cindex while
|
||
|
||
@code{gtroff} provides a looping construct using the @code{while}
|
||
request, which is used much like the @code{if} (and related) requests.
|
||
|
||
@Defreq {while, expr anything}
|
||
Evaluate the expression @var{expr}, and repeatedly execute
|
||
@var{anything} (the remainder of the line) until @var{expr} evaluates
|
||
to@w{ }0.
|
||
|
||
@Example
|
||
.nr a 0 1
|
||
.while (\na < 9) \@{\
|
||
\n+a,
|
||
.\@}
|
||
\n+a
|
||
@result{} 1, 2, 3, 4, 5, 6, 7, 8, 9, 10
|
||
@endExample
|
||
|
||
Some remarks.
|
||
|
||
@cindex @code{de} request, and @code{while}
|
||
@itemize @bullet
|
||
@item
|
||
The body of a @code{while} request is treated like the body of a
|
||
@code{de} request: @code{gtroff} temporarily stores it in a macro
|
||
which is deleted after the loop has been exited. It can considerably
|
||
slow down a macro if the body of the @code{while} request (within the
|
||
macro) is large. Each time the macro is executed, the @code{while}
|
||
body is parsed and stored again as a temporary macro.
|
||
|
||
@Example
|
||
.de xxx
|
||
. nr num 10
|
||
. while (\\n[num] > 0) \@{\
|
||
. \" many lines of code
|
||
. nr num -1
|
||
. \@}
|
||
..
|
||
@endExample
|
||
|
||
@cindex recursive macros
|
||
@cindex macros, recursive
|
||
@noindent
|
||
The traditional and ofter better solution (@acronym{UNIX} @code{troff}
|
||
doesn't have the @code{while} request) is to use a recursive macro
|
||
instead which is parsed only once during its definition.
|
||
|
||
@Example
|
||
.de yyy
|
||
. if (\\n[num] > 0) \@{\
|
||
. \" many lines of code
|
||
. nr num -1
|
||
. yyy
|
||
. \@}
|
||
..
|
||
.
|
||
.de xxx
|
||
. nr num 10
|
||
. yyy
|
||
..
|
||
@endExample
|
||
|
||
@noindent
|
||
Note that the number of available recursion levels is set to@w{ }1000
|
||
(this is a compile-time constant value of @code{gtroff}).
|
||
|
||
@item
|
||
The closing brace of a @code{while} body must end a line.
|
||
|
||
@Example
|
||
.if 1 \@{\
|
||
. nr a 0 1
|
||
. while (\n[a] < 10) \@{\
|
||
. nop \n+[a]
|
||
.\@}\@}
|
||
@result{} unbalanced \@{ \@}
|
||
@endExample
|
||
@end itemize
|
||
@endDefreq
|
||
|
||
@Defreq {break, }
|
||
@cindex @code{while} request, confusing with @code{br}
|
||
@cindex @code{break} request, in a @code{while} loop
|
||
@cindex @code{continue} request, in a @code{while} loop
|
||
Break out of a @code{while} loop. Be sure not to confuse this with
|
||
the @code{br} request (causing a line break).
|
||
@endDefreq
|
||
|
||
@Defreq {continue, }
|
||
Finish the current iteration of a @code{while} loop, immediately
|
||
restarting the next iteration.
|
||
@endDefreq
|
||
|
||
@xref{Expressions}.
|
||
|
||
|
||
@c =====================================================================
|
||
|
||
@node Writing Macros, Page Motions, Conditionals and Loops, gtroff Reference
|
||
@section Writing Macros
|
||
@cindex writing macros
|
||
@cindex macros, writing
|
||
|
||
A @dfn{macro} is a collection of text and embedded commands which can
|
||
be invoked multiple times. Use macros to define common operations.
|
||
|
||
@DefreqList {de, name [@Var{end}]}
|
||
@DefreqItem {de1, name [@Var{end}]}
|
||
@DefreqListEnd {dei, name [@Var{end}]}
|
||
Define a new macro named @var{name}. @code{gtroff} copies subsequent
|
||
lines (starting with the next one) into an internal buffer until it
|
||
encounters the line @samp{..} (two dots). The optional second
|
||
argument to @code{de} changes this to a macro to @samp{.@var{end}}.
|
||
|
||
There can be whitespace after the first dot in the line containing the
|
||
ending token (either @samp{.} or macro @samp{@var{end}}).
|
||
|
||
Here a small example macro called @samp{P} which causes a break and
|
||
inserts some vertical space. It could be used to separate paragraphs.
|
||
|
||
@Example
|
||
.de P
|
||
. br
|
||
. sp .8v
|
||
..
|
||
@endExample
|
||
|
||
The following example defines a macro within another. Remember that
|
||
expansion must be protected twice; once for reading the macro and
|
||
once for executing.
|
||
|
||
@Example
|
||
\# a dummy macro to avoid a warning
|
||
.de end
|
||
..
|
||
.
|
||
.de foo
|
||
. de bar end
|
||
. nop \f[B]Hallo \\\\$1!\f[]
|
||
. end
|
||
..
|
||
.
|
||
.foo
|
||
.bar Joe
|
||
@result{} @b{Hallo Joe!}
|
||
@endExample
|
||
|
||
@noindent
|
||
Since @code{\f} has no expansion, it isn't necessary to protect its
|
||
backslash. Had we defined another macro within @code{bar} which takes
|
||
a parameter, eight backslashes would be necessary before @samp{$1}.
|
||
|
||
The @code{de1} request turns off compatibility mode
|
||
while executing the macro. On entry, the current compatibility mode
|
||
is saved and restored at exit.
|
||
|
||
@Example
|
||
.nr xxx 12345
|
||
.
|
||
.de aa
|
||
The value of xxx is \\n[xxx].
|
||
..
|
||
.de1 bb
|
||
The value of xxx ix \\n[xxx].
|
||
..
|
||
.
|
||
.cp 1
|
||
.
|
||
.aa
|
||
@result{} warning: number register ' not defined
|
||
@result{} The value of xxx is 0xxx].
|
||
.bb
|
||
@result{} The value of xxx ix 12345.
|
||
@endExample
|
||
|
||
The @code{dei} request defines a macro indirectly.
|
||
That is, it expands strings whose names
|
||
are @var{name} or @var{end} before performing the append.
|
||
|
||
This:
|
||
|
||
@Example
|
||
.ds xx aa
|
||
.ds yy bb
|
||
.dei xx yy
|
||
@endExample
|
||
|
||
@noindent
|
||
is equivalent to:
|
||
|
||
@Example
|
||
.de aa bb
|
||
@endExample
|
||
|
||
@pindex trace.tmac
|
||
Using @file{trace.tmac}, you can trace calls to @code{de} and @code{de1}.
|
||
|
||
Note that macro identifiers are shared with identifiers for strings and
|
||
diversions.
|
||
@endDefreq
|
||
|
||
@DefreqList {am, xx}
|
||
@DefreqItem {am1, xx}
|
||
@DefreqListEnd {ami, xx yy}
|
||
@cindex appending to a macro (@code{am})
|
||
@cindex macro, appending (@code{am})
|
||
Works similarly to @code{de} except it appends onto the macro named
|
||
@var{xx}. So, to make the previously defined @samp{P} macro actually
|
||
do indented instead of block paragraphs, add the necessary code to the
|
||
existing macro like this:
|
||
|
||
@Example
|
||
.am P
|
||
.ti +5n
|
||
..
|
||
@endExample
|
||
|
||
The @code{am1} request turns off compatibility mode
|
||
while executing the appended macro piece. To be more precise, a
|
||
@dfn{compatibility save} input token is inserted at the beginning of
|
||
the appended code, and a @dfn{compatibility restore} input token at
|
||
the end.
|
||
|
||
The @code{ami} request appends indirectly,
|
||
meaning that @code{gtroff} expands strings whose names
|
||
are @var{xx} or @var{yy} before performing the append.
|
||
|
||
@pindex trace.tmac
|
||
Using @file{trace.tmac}, you can trace calls to @code{am} and @code{am1}.
|
||
@endDefreq
|
||
|
||
@xref{Strings}, for the @code{als} request to rename a macro.
|
||
|
||
The @code{de}, @code{am}, @code{di}, @code{da}, @code{ds}, and
|
||
@code{as} requests (together with its variants) only create a new object
|
||
if the name of the macro, diversion or string diversion is currently
|
||
undefined or if it is defined to be a request; normally they modify the
|
||
value of an existing object.
|
||
|
||
@Defreq {return, }
|
||
Exit a macro, immediately returning to the caller.
|
||
@endDefreq
|
||
|
||
@menu
|
||
* Copy-in Mode::
|
||
* Parameters::
|
||
@end menu
|
||
|
||
@c ---------------------------------------------------------------------
|
||
|
||
@node Copy-in Mode, Parameters, Writing Macros, Writing Macros
|
||
@subsection Copy-in Mode
|
||
@cindex copy-in mode
|
||
@cindex mode, copy-in
|
||
|
||
@cindex @code{\n}, when reading text for a macro
|
||
@cindex @code{\$}, when reading text for a macro
|
||
@cindex @code{\*}, when reading text for a macro
|
||
@cindex @code{\\}, when reading text for a macro
|
||
@cindex \@key{RET}, when reading text for a macro
|
||
When @code{gtroff} reads in the text for a macro, string, or diversion,
|
||
it copies the text (including request lines, but excluding escapes) into
|
||
an internal buffer. Escapes are converted into an internal form,
|
||
except for @code{\n}, @code{\$}, @code{\*}, @code{\\} and
|
||
@code{\@key{RET}} which are evaluated and inserted into the text where
|
||
the escape was located. This is known as @dfn{copy-in} mode or
|
||
@dfn{copy} mode.
|
||
|
||
What this means is that you can specify when these escapes are to be
|
||
evaluated (either at copy-in time or at the time of use) by insulating
|
||
the escapes with an extra backslash. Compare this to the @code{\def}
|
||
and @code{\edef} commands in @TeX{}.
|
||
|
||
The following example prints the numbers 20 and@w{ }10:
|
||
|
||
@Example
|
||
.nr x 20
|
||
.de y
|
||
.nr x 10
|
||
\&\nx
|
||
\&\\nx
|
||
..
|
||
.y
|
||
@endExample
|
||
|
||
@c ---------------------------------------------------------------------
|
||
|
||
@node Parameters, , Copy-in Mode, Writing Macros
|
||
@subsection Parameters
|
||
@cindex parameters
|
||
|
||
The arguments to a macro or string can be examined using a variety of
|
||
escapes.
|
||
|
||
@Defreg {.$}
|
||
@cindex number of arguments register (@code{.$})
|
||
The number of arguments passed to a macro or string. This is a read-only
|
||
number register.
|
||
@endDefreg
|
||
|
||
Any individual argument can be retrieved with one of the following
|
||
escapes:
|
||
|
||
@DefescList {\\$, , n, }
|
||
@DefescItem {\\$, @lparen{}, nn, }
|
||
@DefescListEnd {\\$, @lbrack{}, nnn, @rbrack{}}
|
||
@cindex copy-in mode, and macro arguments
|
||
@cindex macro, arguments (@code{\$})
|
||
@cindex arguments, macro (@code{\$})
|
||
Retrieve the @var{n}@dmn{th}, @var{nn}@dmn{th} or @var{nnn}@dmn{th}
|
||
argument. As usual, the first form only accepts a single number
|
||
(larger than zero), the second a two-digit number (larger or equal
|
||
to@w{ }10), and the third any positive integer value (larger
|
||
than zero). Macros and strings can have an unlimited number of arguments.
|
||
Note that due to copy-in mode, use two backslashes on these in actual use
|
||
to prevent interpolation until the macro is actually invoked.
|
||
@endDefesc
|
||
|
||
@Defreq {shift, [@Var{n}]}
|
||
Shift the arguments 1@w{ }position, or as
|
||
many positions as specified by its argument. After executing this
|
||
request, argument@w{ }@var{i} becomes argument @math{@var{i}-@var{n}};
|
||
arguments 1 to@w{ }@var{n} are no longer available. Shifting by
|
||
negative amounts is currently undefined.
|
||
@endDefreq
|
||
|
||
@DefescList {\\$*, , , }
|
||
@DefescListEnd {\\$@@, , , }
|
||
In some cases it is convenient to use all of the arguments at once (for
|
||
example, to pass the arguments along to another macro). The @code{\$*}
|
||
escape concatenates all the arguments separated by spaces. A
|
||
similar escape is @code{\$@@}, which concatenates all the
|
||
arguments with each surrounded by double quotes, and separated by
|
||
spaces. If not in compatibility mode, the input level of double quotes
|
||
is preserved (see @ref{Request Arguments}).
|
||
@endDefesc
|
||
|
||
@Defesc {\\$0, , , }
|
||
@cindex macro name register (@code{\$0})
|
||
@cindex @code{als} request, and @code{\$0}
|
||
The name used to invoke the current macro.
|
||
The @code{als} request can make a macro have more than one name.
|
||
|
||
@Example
|
||
.de generic-macro
|
||
. ...
|
||
. if \\n[error] \@{\
|
||
. tm \\$0: Houston, we have a problem.
|
||
. return
|
||
. \@}
|
||
..
|
||
.
|
||
.als foo generic-macro
|
||
.als bar generic-macro
|
||
@endExample
|
||
@endDefesc
|
||
|
||
@xref{Request Arguments}.
|
||
|
||
|
||
@c =====================================================================
|
||
|
||
@node Page Motions, Drawing Requests, Writing Macros, gtroff Reference
|
||
@section Page Motions
|
||
@cindex page motions
|
||
@cindex motions, page
|
||
|
||
@xref{Manipulating Spacing}, for a discussion of the main request for
|
||
vertical motion, @code{sp}.
|
||
|
||
@DefreqList {mk, [@Var{reg}]}
|
||
@DefreqListEnd {rt, [@Var{dist}]}
|
||
@cindex marking vertical page location (@code{mk})
|
||
@cindex page location, vertical, marking (@code{mk})
|
||
@cindex location, vertical, page, marking (@code{mk})
|
||
@cindex vertical page location, marking (@code{mk})
|
||
@cindex returning to marked vertical page location (@code{rt})
|
||
@cindex page location, vertical, returning to marked (@code{rt})
|
||
@cindex location, vertical, page, returning to marked (@code{rt})
|
||
@cindex vertical page location, returning to marked (@code{rt})
|
||
The request @code{mk} can be used to mark a location on a page, for
|
||
movement to later. This request takes a register name as an argument
|
||
in which to store the current page location. With no argument it
|
||
stores the location in an internal register. The results of this can
|
||
be used later by the @code{rt} or the @code{sp} request (or the
|
||
@code{\v} escape).
|
||
|
||
The @code{rt} request returns @emph{upwards} to the location marked
|
||
with the last @code{mk} request. If used with an argument, return to
|
||
a position which distance from the top of the page is @var{dist} (no
|
||
previous call to @code{mk} is necessary in this case). Default scaling
|
||
indicator is @samp{v}.
|
||
|
||
Here a primitive solution for a two-column macro.
|
||
|
||
@Example
|
||
.nr column-length 1.5i
|
||
.nr column-gap 4m
|
||
.nr bottom-margin 1m
|
||
.
|
||
@endExample
|
||
@Example
|
||
.de 2c
|
||
. br
|
||
. mk
|
||
. ll \\n[column-length]u
|
||
. wh -\\n[bottom-margin]u 2c-trap
|
||
. nr right-side 0
|
||
..
|
||
.
|
||
@endExample
|
||
@Example
|
||
.de 2c-trap
|
||
. ie \\n[right-side] \@{\
|
||
. nr right-side 0
|
||
. po -(\\n[column-length]u + \\n[column-gap]u)
|
||
. \" remove trap
|
||
. wh -\\n[bottom-margin]u
|
||
. \@}
|
||
. el \@{\
|
||
. \" switch to right side
|
||
. nr right-side 1
|
||
. po +(\\n[column-length]u + \\n[column-gap]u)
|
||
. rt
|
||
. \@}
|
||
..
|
||
.
|
||
@endExample
|
||
@Example
|
||
.pl 1.5i
|
||
.ll 4i
|
||
This is a small test which shows how the
|
||
rt request works in combination with mk.
|
||
|
||
.2c
|
||
Starting here, text is typeset in two columns.
|
||
Note that this implementation isn't robust
|
||
and thus not suited for a real two-column
|
||
macro.
|
||
@endExample
|
||
|
||
Result:
|
||
|
||
@Example
|
||
This is a small test which shows how the
|
||
rt request works in combination with mk.
|
||
|
||
Starting here, isn't robust
|
||
text is typeset and thus not
|
||
in two columns. suited for a
|
||
Note that this real two-column
|
||
implementation macro.
|
||
@endExample
|
||
@endDefreq
|
||
|
||
The following escapes give fine control of movements about the page.
|
||
|
||
@Defesc {\\v, ', e, '}
|
||
@cindex vertical motion (@code{\v})
|
||
@cindex motion, vertical (@code{\v})
|
||
Move vertically, usually from the current location on the page (if no
|
||
absolute position operator @samp{|} is used). The
|
||
argument@w{ }@var{e} specifies the distance to move; positive is
|
||
downwards and negative upwards. The default scaling indicator for this
|
||
escape is @samp{v}. Beware, however, that @code{gtroff} continues text
|
||
processing at the point where the motion ends, so you should always
|
||
balance motions to avoid interference with text processing.
|
||
|
||
@code{\v} doesn't trigger a trap. This can be quite useful; for example,
|
||
consider a page bottom trap macro which prints a marker in the margin to
|
||
indicate continuation of a footnote or something similar.
|
||
@endDefesc
|
||
|
||
There are some special-case escapes for vertical motion.
|
||
|
||
@Defesc {\\r, , , }
|
||
Move upwards@w{ }1@dmn{v}.
|
||
@endDefesc
|
||
|
||
@Defesc {\\u, , , }
|
||
Move upwards@w{ }.5@dmn{v}.
|
||
@endDefesc
|
||
|
||
@Defesc {\\d, , , }
|
||
Move down@w{ }.5@dmn{v}.
|
||
@endDefesc
|
||
|
||
@Defesc {\\h, ', e, '}
|
||
@cindex inserting horizontal space (@code{\h})
|
||
@cindex horizontal space (@code{\h})
|
||
@cindex space, horizontal (@code{\h})
|
||
@cindex horizontal motion (@code{\h})
|
||
@cindex motion, horizontal (@code{\h})
|
||
Move horizontally, usually from the current location (if no absolute
|
||
position operator @samp{|} is used). The expression@w{ }@var{e}
|
||
indicates how far to move: positive is rightwards and negative
|
||
leftwards. The default scaling indicator for this escape is @samp{m}.
|
||
@endDefesc
|
||
|
||
There are a number of special-case escapes for horizontal motion.
|
||
|
||
@Defesc {\\@key{SP}, , , }
|
||
@cindex space, unbreakable
|
||
@cindex unbreakable space
|
||
An unbreakable and unpaddable (i.e.@: not expanded during filling)
|
||
space. (Note: This is a backslash followed by a space.)
|
||
@endDefesc
|
||
|
||
@Defesc {\\~, , , }
|
||
An unbreakable space that stretches like a normal inter-word space
|
||
when a line is adjusted.
|
||
@endDefesc
|
||
|
||
@Defesc {\\|, , , }
|
||
A 1/6@dmn{th} em space. Ignored for TTY output devices (rounded to
|
||
zero).
|
||
@endDefesc
|
||
|
||
@Defesc {\\^, , , }
|
||
A 1/12@dmn{th} em space. Ignored for TTY output devices (rounded to
|
||
zero).
|
||
@endDefesc
|
||
|
||
@Defesc {\\0, , , }
|
||
@cindex space, width of a digit (@code{\0})
|
||
@cindex digit width space (@code{\0})
|
||
A space the size of a digit.
|
||
@endDefesc
|
||
|
||
The following string sets the @TeX{} logo:
|
||
|
||
@Example
|
||
.ds TeX T\h'-.1667m'\v'.224m'E\v'-.224m'\h'-.125m'X
|
||
@endExample
|
||
|
||
@DefescList {\\w, ', text, '}
|
||
@DefregItem {st}
|
||
@DefregItem {sb}
|
||
@DefregItem {rst}
|
||
@DefregItem {rsb}
|
||
@DefregItem {ct}
|
||
@DefregItem {ssc}
|
||
@DefregListEnd {skw}
|
||
@cindex width escape (@code{\w})
|
||
Return the width of the specified @var{text} in basic units.
|
||
This allows horizontal movement based on the width of some
|
||
arbitrary text (e.g.@: given as an argument to a macro).
|
||
|
||
@Example
|
||
The length of the string `abc' is \w'abc'u.
|
||
@result{} The length of the string `abc' is 72u.
|
||
@endExample
|
||
|
||
Font changes may occur in @var{text} which don't affect current
|
||
settings.
|
||
|
||
After use, @code{\w} sets several registers:
|
||
|
||
@table @code
|
||
@item st
|
||
@itemx sb
|
||
The highest and lowest point of the baseline, respectively, in @var{text}.
|
||
|
||
@item rst
|
||
@itemx rsb
|
||
Like the @code{st} and @code{sb} registers, but takes account of the
|
||
heights and depths of glyphs. With other words, this gives the
|
||
highest and lowest point of @var{text}.
|
||
|
||
@item ct
|
||
Defines the kinds of glyphs occurring in @var{text}:
|
||
|
||
@table @asis
|
||
@item 0
|
||
only short glyphs, no descenders or tall glyphs.
|
||
|
||
@item 1
|
||
at least one descender.
|
||
|
||
@item 2
|
||
at least one tall glyph.
|
||
|
||
@item 3
|
||
at least one each of a descender and a tall glyph.
|
||
@end table
|
||
|
||
@item ssc
|
||
The amount of horizontal space (possibly negative) that should be added
|
||
to the last glyph before a subscript.
|
||
|
||
@item skw
|
||
How far to right of the center of the last glyph in the @code{\w}
|
||
argument, the center of an accent from a roman font should be placed
|
||
over that glyph.
|
||
@end table
|
||
@endDefesc
|
||
|
||
@DefescList {\\k, , p, }
|
||
@DefescItem {\\k, @lparen{}, ps, }
|
||
@DefescListEnd {\\k, @lbrack{}, position, @rbrack}
|
||
@cindex saving horizontal input line position (@code{\k})
|
||
@cindex horizontal input line position, saving (@code{\k})
|
||
@cindex input line position, horizontal, saving (@code{\k})
|
||
@cindex position, horizontal input line, saving (@code{\k})
|
||
@cindex line, input, horizontal position, saving (@code{\k})
|
||
Store the current horizontal position in the @emph{input} line in
|
||
number register with name @var{position} (one-character name@w{ }@var{p},
|
||
two-character name @var{ps}). Use this, for example, to return to the
|
||
beginning of a string for highlighting or other decoration.
|
||
@endDefesc
|
||
|
||
@Defreg {hp}
|
||
@cindex horizontal input line position register (@code{hp})
|
||
@cindex input line, horizontal position, register (@code{hp})
|
||
@cindex position, horizontal, in input line, register (@code{hp})
|
||
@cindex line, input, horizontal position, register (@code{hp})
|
||
The current horizontal position at the input line.
|
||
@endDefreg
|
||
|
||
@Defreg {.k}
|
||
@cindex horizontal output line position register (@code{.k})
|
||
@cindex output line, horizontal position, register (@code{.k})
|
||
@cindex position, horizontal, in output line, register (@code{.k})
|
||
@cindex line, output, horizontal position, register (@code{.k})
|
||
A read-only number register containing the current horizontal output
|
||
position.
|
||
@endDefreg
|
||
|
||
@Defesc {\\o, ', @Var{a}@Var{b}@Var{c}, '}
|
||
@cindex overstriking glyphs (@code{\o})
|
||
@cindex glyphs, overstriking (@code{\o})
|
||
Overstrike glyphs @var{a}, @var{b}, @var{c}, @dots{}; the glyphs
|
||
are centered, and the resulting spacing is the largest width of the
|
||
affected glyphs.
|
||
@endDefesc
|
||
|
||
@Defesc {\\z, , g, , }
|
||
@cindex zero-width printing (@code{\z}, @code{\Z})
|
||
@cindex printing, zero-width (@code{\z}, @code{\Z})
|
||
Print glyph @var{g} with zero width, i.e., without spacing. Use
|
||
this to overstrike glyphs left-aligned.
|
||
@endDefesc
|
||
|
||
@Defesc {\\Z, ', anything, '}
|
||
@cindex zero-width printing (@code{\z}, @code{\Z})
|
||
@cindex printing, zero-width (@code{\z}, @code{\Z})
|
||
Print @var{anything}, then restore the horizontal and vertical position.
|
||
The argument may not contain tabs or leaders.
|
||
|
||
The following is an example of a strike-through macro:
|
||
|
||
@Example
|
||
.de ST
|
||
.nr ww \w'\\$1'
|
||
\Z@@\v'-.25m'\l'\\n[ww]u'@@\\$1
|
||
..
|
||
.
|
||
This is
|
||
.ST "a test"
|
||
an actual emergency!
|
||
@endExample
|
||
@endDefesc
|
||
|
||
|
||
@c =====================================================================
|
||
|
||
@node Drawing Requests, Traps, Page Motions, gtroff Reference
|
||
@section Drawing Requests
|
||
@cindex drawing requests
|
||
@cindex requests for drawing
|
||
|
||
@code{gtroff} provides a number of ways to draw lines and other figures
|
||
on the page. Used in combination with the page motion commands (see
|
||
@ref{Page Motions}, for more info), a wide variety of figures can be
|
||
drawn. However, for complex drawings these operations can be quite
|
||
cumbersome, and it may be wise to use graphic preprocessors like
|
||
@code{gpic} or @code{ggrn}. @xref{gpic}, and @ref{ggrn}, for more
|
||
information.
|
||
|
||
All drawing is done via escapes.
|
||
|
||
@DefescList {\\l, ', @Var{l}, '}
|
||
@DefescListEnd {\\l, ', @Var{l}@Var{g}, '}
|
||
@cindex drawing horizontal lines (@code{\l})
|
||
@cindex horizontal line, drawing (@code{\l})
|
||
@cindex line, horizontal, drawing (@code{\l})
|
||
Draw a line horizontally. @var{l} is the length of the line to be
|
||
drawn. If it is positive, start the line at the current location and
|
||
draw to the right; its end point is the new current location. Negative
|
||
values are handled differently: The line starts at the current location
|
||
and draws to the left, but the current location doesn't move.
|
||
|
||
@var{l} can also be specified absolutely (i.e.@: with a leading
|
||
@samp{|}) which draws back to the beginning of the input line.
|
||
Default scaling indicator is @samp{m}.
|
||
|
||
@cindex underscore glyph (@code{\[ru]})
|
||
@cindex glyph, underscore (@code{\[ru]})
|
||
@cindex line drawing glyph
|
||
@cindex glyph, for line drawing
|
||
The optional second parameter@w{ }@var{g} is a glyph to draw the line
|
||
with. If this second argument is not specified, @code{gtroff} uses
|
||
the underscore glyph, @code{\[ru]}.
|
||
|
||
@cindex zero width space character (@code{\&})
|
||
@cindex character, zero width space (@code{\&})
|
||
@cindex space character, zero width (@code{\&})
|
||
To separate the two arguments (to prevent @code{gtroff} from
|
||
interpreting a drawing glyph as a scaling indicator if the glyph is
|
||
represented by a single character) use @code{\&}.
|
||
|
||
Here a small useful example:
|
||
|
||
@Example
|
||
.de box
|
||
\[br]\\$*\[br]\l'|0\[rn]'\l'|0\[ul]'
|
||
..
|
||
@endExample
|
||
|
||
@noindent
|
||
Note that this works by outputting a box rule (a vertical line), then
|
||
the text given as an argument and then another box rule. Finally, the
|
||
line drawing escapes both draw from the current location to the
|
||
beginning of the @emph{input} line -- this works because the line
|
||
length is negative, not moving the current point.
|
||
@endDefesc
|
||
|
||
@DefescList {\\L, ', @Var{l}, '}
|
||
@DefescListEnd {\\L, ', @Var{l}@Var{g}, '}
|
||
@cindex drawing vertical lines (@code{\L})
|
||
@cindex vertical line drawing (@code{\L})
|
||
@cindex line, vertical, drawing (@code{\L})
|
||
@cindex line drawing glyph
|
||
@cindex glyph for line drawing
|
||
@cindex box rule glyph (@code{\[br]})
|
||
@cindex glyph, box rule (@code{\[br]})
|
||
Draw vertical lines. Its parameters are
|
||
similar to the @code{\l} escape, except that the default scaling
|
||
indicator is @samp{v}. The movement is downwards for positive values,
|
||
and upwards for negative values. The default glyph is the box rule
|
||
glyph, @code{\[br]}. As with the vertical motion escapes, text
|
||
processing blindly continues where the line ends.
|
||
|
||
@Example
|
||
This is a \L'3v'test.
|
||
@endExample
|
||
|
||
@noindent
|
||
Here the result, produced with @code{grotty}.
|
||
|
||
@Example
|
||
This is a
|
||
|
|
||
|
|
||
|test.
|
||
@endExample
|
||
@endDefesc
|
||
|
||
@Defesc {\\D, ', command arg @dots{}, '}
|
||
The @code{\D} escape provides a variety of drawing functions.
|
||
Note that on character devices, only vertical and horizontal lines are
|
||
supported within @code{grotty}; other devices may only support a subset
|
||
of the available drawing functions.
|
||
|
||
The default scaling indicator for all subcommands of @code{\D} is
|
||
@samp{m} for horizontal distances and @samp{v} for vertical ones.
|
||
Exceptions are @w{@code{\D'f @dots{}'}} and @w{@code{\D't @dots{}'}}
|
||
which use @code{u} as the default.
|
||
|
||
@table @code
|
||
@item \D'l @var{dx} @var{dy}'
|
||
@cindex line, drawing (@w{@code{\D'l @dots{}'}})
|
||
@cindex drawing a line (@w{@code{\D'l @dots{}'}})
|
||
Draw a line from the current location to the relative point specified by
|
||
(@var{dx},@var{dy}).
|
||
|
||
The following example is a macro for creating a box around a text string;
|
||
for simplicity, the box margin is taken as a fixed value, 0.2@dmn{m}.
|
||
|
||
@Example
|
||
.de BOX
|
||
. nr @@wd \w'\\$1'
|
||
\h'.2m'\
|
||
\h'-.2m'\v'(.2m - \\n[rsb]u)'\
|
||
\D'l 0 -(\\n[rst]u - \\n[rsb]u + .4m)'\
|
||
\D'l (\\n[@@wd]u + .4m) 0'\
|
||
\D'l 0 (\\n[rst]u - \\n[rsb]u + .4m)'\
|
||
\D'l -(\\n[@@wd]u + .4m) 0'\
|
||
\h'.2m'\v'-(.2m - \\n[rsb]u)'\
|
||
\\$1\
|
||
\h'.2m'
|
||
..
|
||
@endExample
|
||
|
||
@noindent
|
||
First, the width of the string is stored in register @code{@@wd}. Then,
|
||
four lines are drawn to form a box, properly offset by the box margin.
|
||
The registers @code{rst} and @code{rsb} are set by the @code{\w} escape,
|
||
containing the largest height and depth of the whole string.
|
||
|
||
@item \D'c @var{d}'
|
||
@cindex circle, drawing (@w{@code{\D'c @dots{}'}})
|
||
@cindex drawing a circle (@w{@code{\D'c @dots{}'}})
|
||
Draw a circle with a diameter of@w{ }@var{d} with the leftmost point at the
|
||
current position.
|
||
|
||
@item \D'C @var{d}'
|
||
@cindex circle, solid, drawing (@w{@code{\D'C @dots{}'}})
|
||
@cindex drawing a solid circle (@w{@code{\D'C @dots{}'}})
|
||
@cindex solid circle, drawing (@w{@code{\D'C @dots{}'}})
|
||
Draw a solid circle with the same parameters as an outlined circle. No
|
||
outline is drawn.
|
||
|
||
@item \D'e @var{x} @var{y}'
|
||
@cindex drawing an ellipse (@w{@code{\D'e @dots{}'}})
|
||
@cindex ellipse, drawing (@w{@code{\D'e @dots{}'}})
|
||
Draw an ellipse with a horizontal diameter of @var{x} and a vertical
|
||
diameter of @var{y} with the leftmost point at the current position.
|
||
|
||
@item \D'E @var{x} @var{y}'
|
||
@cindex ellipse, solid, drawing (@w{@code{\D'E @dots{}'}})
|
||
@cindex drawing a solid ellipse (@w{@code{\D'E @dots{}'}})
|
||
@cindex solid ellipse, drawing (@w{@code{\D'E @dots{}'}})
|
||
Draw a solid ellipse with the same parameters as an outlined ellipse.
|
||
No outline is drawn.
|
||
|
||
@item \D'a @var{dx1} @var{dy1} @var{dx2} @var{dy2}'
|
||
@cindex arc, drawing (@w{@code{\D'a @dots{}'}})
|
||
@cindex drawing an arc (@w{@code{\D'a @dots{}'}})
|
||
Draw an arc clockwise from the current location through the two
|
||
specified relative locations (@var{dx1},@var{dy1}) and
|
||
(@var{dx2},@var{dy2}). The coordinates of the first point are relative
|
||
to the current position, and the coordinates of the second point are
|
||
relative to the first point.
|
||
|
||
@item \D'~ @var{dx1} @var{dy1} @var{dx2} @var{dy2} @dots{}'
|
||
@cindex drawing a spline (@w{@code{\D'~ @dots{}'}})
|
||
@cindex spline, drawing (@w{@code{\D'~ @dots{}'}})
|
||
Draw a spline from the current location to the relative point
|
||
(@var{dx1},@var{dy1}) and then to (@var{dx2},@var{dy2}), and so on.
|
||
|
||
@item \D'f @var{n}'
|
||
@cindex gray shading (@w{@code{\D'f @dots{}'}})
|
||
@cindex shading filled objects (@w{@code{\D'f @dots{}'}})
|
||
Set the shade of gray to be used for filling solid objects to@w{
|
||
}@var{n}; @var{n}@w{ }must be an integer between 0 and@w{ }1000, where 0
|
||
corresponds solid white and 1000 to solid black, and values in between
|
||
correspond to intermediate shades of gray. This applies only to solid
|
||
circles, solid ellipses, and solid polygons. By default, a level of
|
||
1000 is used.
|
||
|
||
@item \D'p @var{dx1} @var{dy1} @var{dx2} @var{dy2} @dots{}'
|
||
@cindex drawing a polygon (@w{@code{\D'p @dots{}'}})
|
||
@cindex polygon, drawing (@w{@code{\D'p @dots{}'}})
|
||
Draw a polygon from the current location to the relative position
|
||
(@var{dx1},@var{dy1}) and then to (@var{dx2},@var{dy2}) and so on.
|
||
When the specified data points are exhausted, a line is drawn back
|
||
to the starting point.
|
||
|
||
@item \D'P @var{dx1} @var{dy1} @var{dx2} @var{dy2} @dots{}'
|
||
@cindex polygon, solid, drawing (@w{@code{\D'P @dots{}'}})
|
||
@cindex drawing a solid polygon (@w{@code{\D'P @dots{}'}})
|
||
@cindex solid polygon, drawing (@w{@code{\D'P @dots{}'}})
|
||
Draw a solid polygon with the same parameters as an outlined polygon.
|
||
No outline is drawn.
|
||
|
||
Here a better variant of the box macro to fill the box with some color.
|
||
Note that the box must be drawn before the text since colors in
|
||
@code{gtroff} are not transparent; the filled polygon would hide the
|
||
text completely.
|
||
|
||
@Example
|
||
.de BOX
|
||
. nr @@wd \w'\\$1'
|
||
\h'.2m'\
|
||
\h'-.2m'\v'(.2m - \\n[rsb]u)'\
|
||
\M[lightcyan]\
|
||
\D'P 0 -(\\n[rst]u - \\n[rsb]u + .4m) \
|
||
(\\n[@@wd]u + .4m) 0 \
|
||
0 (\\n[rst]u - \\n[rsb]u + .4m) \
|
||
-(\\n[@@wd]u + .4m) 0'\
|
||
\h'.2m'\v'-(.2m - \\n[rsb]u)'\
|
||
\M[]\
|
||
\\$1\
|
||
\h'.2m'
|
||
..
|
||
@endExample
|
||
|
||
@item \D't @var{n}'
|
||
@cindex line thickness (@w{@code{\D't @dots{}'}})
|
||
@cindex thickness of lines (@w{@code{\D't @dots{}'}})
|
||
Set the current line thickness to @var{n}@w{ }machine units. A value of
|
||
zero selects the smallest available line thickness. A negative value
|
||
makes the line thickness proportional to the current point size (this is
|
||
the default behaviour of @acronym{AT&T} @code{troff}).
|
||
@end table
|
||
@endDefesc
|
||
|
||
@xref{Graphics Commands}.
|
||
|
||
@Defesc {\\b, ', string, '}
|
||
@cindex pile, glyph (@code{\b})
|
||
@cindex glyph pile (@code{\b})
|
||
@cindex stacking glyphs (@code{\b})
|
||
@dfn{Pile} a sequence of glyphs vertically, and center it vertically
|
||
on the current line. Use it to build large brackets and braces.
|
||
|
||
Here an example how to create a large opening brace:
|
||
|
||
@Example
|
||
\b'\[lt]\[bv]\[lk]\[bv]\[lb]'
|
||
@endExample
|
||
|
||
@cindex @code{\b}, limitations
|
||
@cindex limitations of @code{\b} escape
|
||
The first glyph is on the top, the last glyph in @var{string} is
|
||
at the bottom. Note that @code{gtroff} separates the glyphs
|
||
vertically by 1@dmn{m}, and the whole object is centered 0.5@dmn{m}
|
||
above the current baseline; the largest glyph width is used as the
|
||
width for the whole object. This rather unflexible positioning
|
||
algorithm doesn't work with @option{-Tdvi} since the bracket pieces vary
|
||
in height for this device. Instead, use the @code{eqn} preprocessor.
|
||
|
||
@xref{Manipulating Spacing}, how to adjust the vertical spacing with
|
||
the @code{\x} escape.
|
||
@endDefesc
|
||
|
||
|
||
@c =====================================================================
|
||
|
||
@node Traps, Diversions, Drawing Requests, gtroff Reference
|
||
@section Traps
|
||
@cindex traps
|
||
|
||
@dfn{Traps} are locations, which, when reached, call a specified
|
||
macro. These traps can occur at a given location on the page, at a
|
||
given location in the current diversion, at a blank line,
|
||
after a certain number of input lines, or at the end of input.
|
||
|
||
@cindex planting a trap
|
||
@cindex trap, planting
|
||
Setting a trap is also called @dfn{planting}.
|
||
@cindex trap, springing
|
||
@cindex springing a trap
|
||
It is also said that a trap is @dfn{sprung} if the associated macro
|
||
is executed.
|
||
|
||
@menu
|
||
* Page Location Traps::
|
||
* Diversion Traps::
|
||
* Input Line Traps::
|
||
* Blank Line Traps::
|
||
* End-of-input Traps::
|
||
@end menu
|
||
|
||
@c ---------------------------------------------------------------------
|
||
|
||
@node Page Location Traps, Diversion Traps, Traps, Traps
|
||
@subsection Page Location Traps
|
||
@cindex page location traps
|
||
@cindex traps, page location
|
||
|
||
@dfn{Page location traps} perform an action when @code{gtroff}
|
||
reaches or passes a certain vertical location on the page. Page
|
||
location traps have a variety of purposes, including:
|
||
|
||
@itemize
|
||
@item
|
||
setting headers and footers
|
||
|
||
@item
|
||
setting body text in multiple columns
|
||
|
||
@item
|
||
setting footnotes
|
||
@end itemize
|
||
|
||
@DefreqList {vpt, flag}
|
||
@DefregListEnd {.vpt}
|
||
@cindex enabling vertical position traps (@code{vpt})
|
||
@cindex vertical position traps, enabling (@code{vpt})
|
||
@cindex vertical position trap enable register (@code{.vpt})
|
||
Enable vertical position traps if @var{flag} is non-zero, or disables
|
||
them otherwise. Vertical position traps are traps set by the @code{wh}
|
||
or @code{dt} requests. Traps set by the @code{it} request are not
|
||
vertical position traps. The parameter that controls whether vertical
|
||
position traps are enabled is global. Initially vertical position traps
|
||
are enabled. The current setting of this is available in the
|
||
@code{.vpt} read-only number register.
|
||
@endDefreq
|
||
|
||
@Defreq {wh, dist [@Var{macro}]}
|
||
Set a page location trap. Positive values for @var{dist} set
|
||
the trap relative to the top of the page; negative values set
|
||
the trap relative to the bottom of the page. Default scaling
|
||
indicator is @samp{v}.
|
||
|
||
@var{macro} is the name of the macro to execute when the
|
||
trap is sprung. If @var{macro} is missing, remove the first trap
|
||
(if any) at @var{dist}.
|
||
|
||
@cindex page headers
|
||
@cindex page footers
|
||
@cindex headers
|
||
@cindex footers
|
||
The following is a simple example of how many macro packages
|
||
set headers and footers.
|
||
|
||
@Example
|
||
.de hd \" Page header
|
||
' sp .5i
|
||
. tl 'Title''date'
|
||
' sp .3i
|
||
..
|
||
.
|
||
.de fo \" Page footer
|
||
' sp 1v
|
||
. tl ''%''
|
||
' bp
|
||
..
|
||
.
|
||
.wh 0 hd \" trap at top of the page
|
||
.wh -1i fo \" trap one inch from bottom
|
||
@endExample
|
||
|
||
A trap at or below the bottom of the page is ignored; it can be made
|
||
active by either moving it up or increasing the page length so that the
|
||
trap is on the page.
|
||
|
||
It is possible to have more than one trap at the same location; to do so,
|
||
the traps must be defined at different locations, then moved together with
|
||
the @code{ch} request; otherwise the second trap would replace the first
|
||
one. Earlier defined traps hide later defined traps if moved to the same
|
||
position (the many empty lines caused by the @code{bp} request are omitted):
|
||
|
||
@Example
|
||
.de a
|
||
. nop a
|
||
..
|
||
.de b
|
||
. nop b
|
||
..
|
||
.de c
|
||
. nop c
|
||
..
|
||
.
|
||
.wh 1i a
|
||
.wh 2i b
|
||
.wh 3i c
|
||
.bp
|
||
@result{} a b c
|
||
@endExample
|
||
@Example
|
||
.ch b 1i
|
||
.ch c 1i
|
||
.bp
|
||
@result{} a
|
||
@endExample
|
||
@Example
|
||
.ch a 0.5i
|
||
.bp
|
||
@result{} a b
|
||
@endExample
|
||
@endDefreq
|
||
|
||
@Defreg {.t}
|
||
@cindex distance to next trap register (@code{.t})
|
||
@cindex trap, distance, register (@code{.t})
|
||
A read-only number register holding the distance to the next trap.
|
||
|
||
If there are no traps between the current position and the bottom of the
|
||
page, it contains the distance to the page bottom. In a diversion, the
|
||
distance to the page bottom is infinite (the returned value is the biggest
|
||
integer which can be represented in @code{groff}) if there are no diversion
|
||
traps.
|
||
@endDefreg
|
||
|
||
@Defreq {ch, macro dist}
|
||
@cindex changing trap location (@code{ch})
|
||
@cindex trap, changing location (@code{ch})
|
||
Change the location of a trap.
|
||
The first argument is the name of the macro to be invoked at
|
||
the trap, and the second argument is the new location for the trap
|
||
(note that the parameters are specified the opposite of the @code{wh}
|
||
request). This is useful for building up footnotes in a diversion to
|
||
allow more space at the bottom of the page for them.
|
||
|
||
Default scaling indicator for @var{dist} is @samp{v}. If @var{dist}
|
||
is missing, the trap is removed.
|
||
|
||
@c XXX
|
||
|
||
@ignore
|
||
@Example
|
||
... (simplified) footnote example ...
|
||
@endExample
|
||
@end ignore
|
||
@endDefreq
|
||
|
||
@Defreg {.ne}
|
||
The read-only number register @code{.ne} contains the amount of space
|
||
that was needed in the last @code{ne} request that caused a trap to be
|
||
sprung. Useful in conjunction with the @code{.trunc} register.
|
||
@xref{Page Control}, for more information.
|
||
@endDefreg
|
||
|
||
@Defreg {.trunc}
|
||
@cindex @code{ne} request, and the @code{.trunc} register
|
||
@cindex truncated vertical space register (@code{.trunc})
|
||
A read-only register containing the amount of vertical space truncated
|
||
by the most recently sprung vertical position trap, or, if the trap was
|
||
sprung by an @code{ne} request, minus the amount of vertical motion
|
||
produced by the @code{ne} request. In other words, at the point a trap
|
||
is sprung, it represents the difference of what the vertical position
|
||
would have been but for the trap, and what the vertical position
|
||
actually is.
|
||
@endDefreg
|
||
|
||
@c ---------------------------------------------------------------------
|
||
|
||
@node Diversion Traps, Input Line Traps, Page Location Traps, Traps
|
||
@subsection Diversion Traps
|
||
@cindex diversion traps
|
||
@cindex traps, diversion
|
||
|
||
@Defreq {dt, dist macro}
|
||
@cindex @code{.t} register, and diversions
|
||
@cindex setting diversion trap (@code{dt})
|
||
@cindex diversion trap, setting (@code{dt})
|
||
@cindex trap, diversion, setting (@code{dt})
|
||
Set a trap @emph{within} a diversion.
|
||
@var{dist} is the location of the trap
|
||
(identical to the @code{.wh} request; default scaling indicator is
|
||
@samp{v}) and @var{macro} is the name of the macro to be invoked. The
|
||
number register @code{.t} still works within diversions.
|
||
@xref{Diversions}, for more information.
|
||
@endDefreq
|
||
|
||
@c ---------------------------------------------------------------------
|
||
|
||
@node Input Line Traps, Blank Line Traps, Diversion Traps, Traps
|
||
@subsection Input Line Traps
|
||
@cindex input line traps
|
||
@cindex traps, input line
|
||
|
||
@DefreqList {it, n macro}
|
||
@DefreqItem {itc, n macro}
|
||
@cindex setting input line trap (@code{it})
|
||
@cindex input line trap, setting (@code{it})
|
||
@cindex trap, input line, setting (@code{it})
|
||
Set an input line trap.
|
||
@var{n}@w{ }is the number of lines of input which may be read before
|
||
springing the trap, @var{macro} is the macro to be invoked.
|
||
Request lines are not counted as input lines.
|
||
|
||
For example, one possible use is to have a macro which prints the
|
||
next @var{n}@w{ }lines in a bold font.
|
||
|
||
@Example
|
||
.de B
|
||
. it \\$1 B-end
|
||
. ft B
|
||
..
|
||
.
|
||
.de B-end
|
||
. ft R
|
||
..
|
||
@endExample
|
||
|
||
@cindex input line traps and interrupted lines (@code{itc})
|
||
@cindex interrupted lines and input line traps (@code{itc})
|
||
@cindex traps, input line, and interrupted lines (@code{itc})
|
||
@cindex lines, interrupted, and input line traps (@code{itc})
|
||
The @code{itc} request is identical,
|
||
except that a line interrupted with @code{\c}
|
||
counts as one input line.
|
||
|
||
Both requests are associated with the current environment
|
||
(@pxref{Environments}); switching to another environment disables the
|
||
current input trap, and going back reactivates it, restoring the number
|
||
of already processed lines.
|
||
@endDefreq
|
||
|
||
@c ---------------------------------------------------------------------
|
||
|
||
@node Blank Line Traps, End-of-input Traps, Input Line Traps, Traps
|
||
@subsection Blank Line Traps
|
||
@cindex blank line traps
|
||
@cindex traps, blank line
|
||
|
||
@Defreq {blm, macro}
|
||
@cindex blank line macro (@code{blm})
|
||
Set a blank line trap.
|
||
@code{gtroff} executes @var{macro} when it encounters a blank line in
|
||
the input file.
|
||
@endDefreq
|
||
|
||
@c ---------------------------------------------------------------------
|
||
|
||
@node End-of-input Traps, , Blank Line Traps, Traps
|
||
@subsection End-of-input Traps
|
||
@cindex end-of-input traps
|
||
@cindex traps, end-of-input
|
||
|
||
@Defreq {em, macro}
|
||
@cindex setting end-of-input trap (@code{em})
|
||
@cindex end-of-input trap, setting (@code{em})
|
||
@cindex trap, end-of-input, setting (@code{em})
|
||
@cindex end-of-input macro (@code{em})
|
||
@cindex macro, end-of-input (@code{em})
|
||
Set a trap at the end of input. @var{macro} is executed after the
|
||
last line of the input file has been processed.
|
||
|
||
For example, if the document had to have a section at the bottom of the
|
||
last page for someone to approve it, the @code{em} request could be
|
||
used.
|
||
|
||
@Example
|
||
.de approval
|
||
. ne 5v
|
||
. sp |(\\n[.t] - 6v)
|
||
. in +4i
|
||
. lc _
|
||
. br
|
||
Approved:\t\a
|
||
. sp
|
||
Date:\t\t\a
|
||
..
|
||
.
|
||
.em approval
|
||
@endExample
|
||
@endDefreq
|
||
|
||
|
||
@c =====================================================================
|
||
|
||
@node Diversions, Environments, Traps, gtroff Reference
|
||
@section Diversions
|
||
@cindex diversions
|
||
|
||
In @code{gtroff} it is possible to @dfn{divert} text into a named
|
||
storage area. Due to the similarity to defining macros it is sometimes
|
||
said to be stored in a macro. This is used for saving text for output
|
||
at a later time, which is useful for keeping blocks of text on the same
|
||
page, footnotes, tables of contents, and indices.
|
||
|
||
@cindex top-level diversion
|
||
@cindex diversion, top-level
|
||
For orthogonality it is said that @code{gtroff} is in the @dfn{top-level
|
||
diversion} if no diversion is active (i.e., the data is diverted to the
|
||
output device).
|
||
|
||
@DefreqList {di, macro}
|
||
@DefreqListEnd {da, macro}
|
||
@cindex beginning diversion (@code{di})
|
||
@cindex diversion, beginning (@code{di})
|
||
@cindex ending diversion (@code{di})
|
||
@cindex diversion, ending (@code{di})
|
||
@cindex appending to a diversion (@code{da})
|
||
@cindex diversion, appending (@code{da})
|
||
Begin a diversion. Like the @code{de}
|
||
request, it takes an argument of a macro name to divert subsequent text
|
||
into. The @code{da} macro appends to an existing diversion.
|
||
|
||
@code{di} or @code{da} without an argument ends the diversion.
|
||
@endDefreq
|
||
|
||
@DefreqList {box, macro}
|
||
@DefreqListEnd {boxa, macro}
|
||
Begin (or appends to) a diversion like the
|
||
@code{di} and @code{da} requests.
|
||
The difference is that @code{box} and @code{boxa}
|
||
do not include a partially-filled line in the diversion.
|
||
|
||
Compare this:
|
||
|
||
@Example
|
||
Before the box.
|
||
.box xxx
|
||
In the box.
|
||
.br
|
||
.box
|
||
After the box.
|
||
.br
|
||
@result{} Before the box. After the box.
|
||
.xxx
|
||
@result{} In the box.
|
||
@endExample
|
||
|
||
@noindent
|
||
with this:
|
||
|
||
@Example
|
||
Before the diversion.
|
||
.di yyy
|
||
In the diversion.
|
||
.br
|
||
.di
|
||
After the diversion.
|
||
.br
|
||
@result{} After the diversion.
|
||
.yyy
|
||
@result{} Before the diversion. In the diversion.
|
||
@endExample
|
||
|
||
@code{box} or @code{boxa} without an argument ends the diversion.
|
||
@endDefreq
|
||
|
||
@DefregList {.z}
|
||
@DefregListEnd {.d}
|
||
@cindex @code{nl} register, and @code{.d}
|
||
@cindex nested diversions
|
||
@cindex diversion, nested
|
||
@cindex diversion name register (@code{.z})
|
||
@cindex vertical position in diversion register (@code{.d})
|
||
@cindex position, vertical, in diversion, register (@code{.d})
|
||
@cindex diversion, vertical position in, register (@code{.d})
|
||
Diversions may be nested. The read-only number register @code{.z}
|
||
contains the name of the current diversion (this is a string-valued
|
||
register). The read-only number register @code{.d} contains the current
|
||
vertical place in the diversion. If not in a diversion it is the same
|
||
as the register @code{nl}.
|
||
@endDefreg
|
||
|
||
@Defreg {.h}
|
||
@cindex high-water mark register (@code{.h})
|
||
@cindex mark, high-water, register (@code{.h})
|
||
@cindex position of lowest text line (@code{.h})
|
||
@cindex text line, position of lowest (@code{.h})
|
||
The @dfn{high-water mark} on the current page. It corresponds to the
|
||
text baseline of the lowest line on the page. This is a read-only
|
||
register.
|
||
|
||
@Example
|
||
.tm .h==\n[.h], nl==\n[nl]
|
||
@result{} .h==0, nl==-1
|
||
This is a test.
|
||
.br
|
||
.sp 2
|
||
.tm .h==\n[.h], nl==\n[nl]
|
||
@result{} .h==40, nl==120
|
||
@endExample
|
||
|
||
@cindex @code{.h} register, difference to @code{nl}
|
||
@cindex @code{nl} register, difference to @code{.h}
|
||
@noindent
|
||
As can be seen in the previous example, empty lines are not considered
|
||
in the return value of the @code{.h} register.
|
||
@endDefreg
|
||
|
||
@DefregList {dn}
|
||
@DefregListEnd {dl}
|
||
After completing a diversion, the read-write number registers @code{dn}
|
||
and @code{dl} contain the vertical and horizontal size of the diversion.
|
||
|
||
@Example
|
||
.\" Center text both horizontally & vertically
|
||
.
|
||
.\" Enclose macro definitions in .eo and .ec
|
||
.\" to avoid the doubling of the backslash
|
||
.eo
|
||
.\" macro .(c starts centering mode
|
||
.de (c
|
||
. br
|
||
. ev (c
|
||
. evc 0
|
||
. in 0
|
||
. nf
|
||
. di @@c
|
||
..
|
||
@endExample
|
||
@Example
|
||
.\" macro .)c terminates centering mode
|
||
.de )c
|
||
. br
|
||
. ev
|
||
. di
|
||
. nr @@s (((\n[.t]u - \n[dn]u) / 2u) - 1v)
|
||
. sp \n[@@s]u
|
||
. ce 1000
|
||
. @@c
|
||
. ce 0
|
||
. sp \n[@@s]u
|
||
. br
|
||
. fi
|
||
. rr @@s
|
||
. rm @@s
|
||
. rm @@c
|
||
..
|
||
.\" End of macro definitions, restore escape mechanism
|
||
.ec
|
||
@endExample
|
||
@endDefreg
|
||
|
||
@DefescList {\\!, , , }
|
||
@DefescListEnd {\\?, , @Var{anything}, \\?}
|
||
@cindex transparent output (@code{\!}, @code{\?})
|
||
@cindex output, transparent (@code{\!}, @code{\?})
|
||
Prevent requests, macros, and escapes from being
|
||
interpreted when read into a diversion. This takes the given text
|
||
and @dfn{transparently} embeds it into the diversion. This is useful for
|
||
macros which shouldn't be invoked until the diverted text is actually
|
||
output.
|
||
|
||
The @code{\!} escape transparently embeds text up to
|
||
and including the end of the line.
|
||
The @code{\?} escape transparently embeds text until the next
|
||
occurrence of the @code{\?} escape. For example:
|
||
|
||
@Example
|
||
\?@var{anything}\?
|
||
@endExample
|
||
|
||
@noindent
|
||
@var{anything} may not contain newlines; use @code{\!} to embed
|
||
newlines in a diversion. The escape sequence @code{\?} is also
|
||
recognized in copy mode and turned into a single internal code; it is
|
||
this code that terminates @var{anything}. Thus the following example
|
||
prints@w{ }4.
|
||
|
||
@Example
|
||
.nr x 1
|
||
.nf
|
||
.di d
|
||
\?\\?\\\\?\\\\\\\\nx\\\\?\\?\?
|
||
.di
|
||
.nr x 2
|
||
.di e
|
||
.d
|
||
.di
|
||
.nr x 3
|
||
.di f
|
||
.e
|
||
.di
|
||
.nr x 4
|
||
.f
|
||
@endExample
|
||
|
||
Both escapes read the data in copy mode.
|
||
|
||
@cindex @code{\!}, in top-level diversion
|
||
@cindex top-level diversion, and @code{\!}
|
||
@cindex diversion, top-level, and @code{\!}
|
||
If @code{\!} is used in the top-level diversion, its argument is
|
||
directly embedded into the @code{gtroff} intermediate output. This can
|
||
be used for example to control a postprocessor which processes the data
|
||
before it is sent to the device driver.
|
||
|
||
@cindex @code{\?}, in top-level diversion
|
||
@cindex top-level diversion, and @code{\?}
|
||
@cindex diversion, top-level, and @code{\?}
|
||
The @code{\?} escape used in the top-level diversion produces no output
|
||
at all; its argument is simply ignored.
|
||
@endDefesc
|
||
|
||
@cindex @code{\!}, and @code{output}
|
||
@cindex @code{output} request, and @code{\!}
|
||
@Defreq {output, string}
|
||
Emit @var{string} directly to the @code{gtroff} intermediate output
|
||
(subject to copy-mode interpretation); this is similar to @code{\!} used
|
||
at the top level. An initial double quote in @var{string} is stripped off
|
||
to allow initial blanks.
|
||
|
||
This request can't be used before the first page has started -- if you get
|
||
an error, simply insert @code{.br} before the @code{output} request.
|
||
|
||
Without argument, @code{output} is ignored.
|
||
|
||
Use with caution! It is normally only needed for mark-up used by a
|
||
postprocessor which does something with the output before sending it to
|
||
the output device, filtering out @code{string} again.
|
||
@endDefreq
|
||
|
||
@Defreq {asciify, div}
|
||
@cindex unformatting diversions (@code{asciify})
|
||
@cindex diversion, unformatting (@code{asciify})
|
||
@cindex @code{trin} request, and @code{asciify}
|
||
@dfn{Unformat} the diversion specified by @var{div}
|
||
in such a way that @acronym{ASCII} characters, characters translated with
|
||
the @code{trin} request, space characters, and some escape sequences that
|
||
were formatted and diverted are treated like ordinary input
|
||
characters when the diversion is reread. It can be also used for gross
|
||
hacks; for example, the following sets register@w{ }@code{n} to@w{ }1.
|
||
|
||
@Example
|
||
.tr @@.
|
||
.di x
|
||
@@nr n 1
|
||
.br
|
||
.di
|
||
.tr @@@@
|
||
.asciify x
|
||
.x
|
||
@endExample
|
||
|
||
@xref{Copy-in Mode}.
|
||
@endDefreq
|
||
|
||
@Defreq {unformat, div}
|
||
Like @code{asciify}, unformat the specified diversion.
|
||
However, @code{unformat} only unformats spaces and tabs
|
||
between words.
|
||
Unformatted tabs are treated as input tokens,
|
||
and spaces are stretchable again.
|
||
|
||
The vertical size of lines is not preserved; glyph information (font,
|
||
font size, space width, etc.)@: is retained.
|
||
@endDefreq
|
||
|
||
|
||
@c =====================================================================
|
||
|
||
@node Environments, Suppressing output, Diversions, gtroff Reference
|
||
@section Environments
|
||
@cindex environments
|
||
|
||
It happens frequently that some text should be printed in a certain
|
||
format regardless of what may be in effect at the time, for example, in
|
||
a trap invoked macro to print headers and footers. To solve this
|
||
@code{gtroff} processes text in @dfn{environments}. An
|
||
environment contains most of the parameters that control text
|
||
processing. It is possible to switch amongst these environments; by
|
||
default @code{gtroff} processes text in environment@w{ }0. The
|
||
following is the information kept in an environment.
|
||
|
||
@itemize @bullet
|
||
@item
|
||
font parameters (size, family, style, glyph height and slant, space
|
||
and sentence space size)
|
||
|
||
@item
|
||
page parameters (line length, title length, vertical spacing,
|
||
line spacing, indentation, line numbering, centering, right-justifying,
|
||
underlining, hyphenation data)
|
||
|
||
@item
|
||
fill and adjust mode
|
||
|
||
@item
|
||
tab stops, tab and leader characters, escape character,
|
||
no-break and hyphen indicators, margin character data
|
||
|
||
@item
|
||
partially collected lines
|
||
|
||
@item
|
||
input traps
|
||
|
||
@item
|
||
drawing and fill colours
|
||
@end itemize
|
||
|
||
These environments may be given arbitrary names (see @ref{Identifiers},
|
||
for more info). Old versions of @code{troff} only had environments
|
||
named @samp{0}, @samp{1}, and @samp{2}.
|
||
|
||
@DefreqList {ev, [@Var{env}]}
|
||
@DefregListEnd {.ev}
|
||
@cindex switching environments (@code{ev})
|
||
@cindex environment, switching (@code{ev})
|
||
@cindex environment number/name register (@code{.ev})
|
||
Switch to another environment. The argument @var{env} is the name of
|
||
the environment to switch to. With no argument, @code{gtroff} switches
|
||
back to the previous environment. There is no limit on the number of
|
||
named environments; they are created the first time that they are
|
||
referenced. The @code{.ev} read-only register contains the name or
|
||
number of the current environment. This is a string-valued register.
|
||
|
||
Note that a call to @code{ev} (with argument) pushes the previously
|
||
active environment onto a stack. If, say, environments @samp{foo},
|
||
@samp{bar}, and @samp{zap} are called (in that order), the first
|
||
@code{ev} request without parameter switches back to environment
|
||
@samp{bar} (which is popped off the stack), and a second call
|
||
switches back to environment @samp{foo}.
|
||
|
||
Here is an example:
|
||
|
||
@Example
|
||
.ev footnote-env
|
||
.fam N
|
||
.ps 6
|
||
.vs 8
|
||
.ll -.5i
|
||
.ev
|
||
|
||
...
|
||
|
||
.ev footnote-env
|
||
\(dg Note the large, friendly letters.
|
||
.ev
|
||
@endExample
|
||
@endDefreq
|
||
|
||
@Defreq {evc, env}
|
||
@cindex copying environment (@code{evc})
|
||
@cindex environment, copying (@code{evc})
|
||
Copy the environment @var{env} into the current environment.
|
||
|
||
The following environment data is not copied:
|
||
|
||
@itemize @bullet
|
||
@item
|
||
Partially filled lines.
|
||
|
||
@item
|
||
The status whether the previous line was interrupted.
|
||
|
||
@item
|
||
The number of lines still to center, or to right-justify, or to underline
|
||
(with or without underlined spaces); they are set to zero.
|
||
|
||
@item
|
||
The status whether a temporary indent is active.
|
||
|
||
@item
|
||
Input traps and its associated data.
|
||
|
||
@item
|
||
Line numbering mode is disabled; it can be reactivated with
|
||
@w{@samp{.nm +0}}.
|
||
|
||
@item
|
||
The number of consecutive hyphenated lines (set to zero).
|
||
@end itemize
|
||
@endDefreq
|
||
|
||
@DefregList {.cht}
|
||
@DefregItem {.cdp}
|
||
@DefregListEnd {.csk}
|
||
@cindex environment, last glyph
|
||
The @code{\n[.cht]} register contains the
|
||
maximum extent (above the baseline)
|
||
of the last glyph added to the current environment.
|
||
|
||
The @code{\n[.cdp]} register contains the
|
||
maximum extent (below the baseline)
|
||
of the last glyph added to the current environment.
|
||
|
||
The @code{\n[.csk]} register contains the
|
||
@dfn{skew} (how far to the right of the glyph's center
|
||
that @code{gtroff} shold place an accent)
|
||
of the last glyph added to the current environment.
|
||
@endDefreg
|
||
|
||
|
||
@c =====================================================================
|
||
|
||
@node Suppressing output, Colors, Environments, gtroff Reference
|
||
@section Suppressing output
|
||
|
||
@Defesc {\\O, , num, }
|
||
@cindex suppressing output (@code{\O})
|
||
@cindex output, suppressing (@code{\O})
|
||
Disable or enable output depending on the value of @var{num}:
|
||
|
||
@table @samp
|
||
@item \O0
|
||
Disable any glyphs from being emitted to the device driver, provided that
|
||
the escape occurs at the outer level (see @code{\O[3]} and @code{\O[4]}).
|
||
Motion is not suppressed so effectively @code{\O[0]} means @emph{pen up}.
|
||
|
||
@item \O1
|
||
Enable output of glyphs, provided that the escape occurs at the outer
|
||
level.
|
||
@end table
|
||
|
||
@vindex opminx
|
||
@vindex opminy
|
||
@vindex opmaxx
|
||
@vindex opmaxy
|
||
@code{\O0} and @code{\O1} also reset the four registers @samp{opminx},
|
||
@samp{opminy}, @samp{opmaxx}, and @samp{opmaxy} to @minus{}1.
|
||
@xref{Register Index}. These four registers mark the top left and
|
||
bottom right hand corners of a box which encompasses all written glyphs.
|
||
|
||
For example the input text:
|
||
|
||
@Example
|
||
Hello \O[0]world \O[1]this is a test.
|
||
@endExample
|
||
|
||
@noindent
|
||
produces the following output:
|
||
|
||
@Example
|
||
Hello this is a test.
|
||
@endExample
|
||
|
||
@table @samp
|
||
@item \O2
|
||
Provided that the escape occurs at the outer level, enable output of
|
||
glyphs and also write out to @code{stderr} the page number and four
|
||
registers encompassing the glyphs previously written since the last call
|
||
to @code{\O}.
|
||
|
||
@item \O3
|
||
Begin a nesting level. At start-up, @code{gtroff} is at outer level.
|
||
|
||
@item \O4
|
||
End a nesting level.
|
||
|
||
@item \O[5@var{P}@var{filename}]
|
||
This escape is @code{grohtml} specific. Provided that this escape
|
||
occurs at the outer nesting level write the @code{filename} to
|
||
@code{stderr}. The position of the image, @var{P}, must be specified
|
||
and must be one of @code{l}, @code{r}, @code{c}, or@w{ }@code{i} (left,
|
||
right, centered, inline). @var{filename} will be associated with the
|
||
production of the next inline image.
|
||
@end table
|
||
@endDefesc
|
||
|
||
@c =====================================================================
|
||
|
||
@node Colors, I/O, Suppressing output, gtroff Reference
|
||
@section Colors
|
||
@cindex colors
|
||
|
||
@DefreqList {color, [@Var{n}]}
|
||
@DefregListEnd {.color}
|
||
If @var{n} is missing or non-zero, activate colors (this is the default);
|
||
otherwise, turn it off.
|
||
|
||
The read-only number register @code{.color} is@w{ }1 if colors are active,
|
||
0@w{ }otherwise.
|
||
|
||
Internally, @code{color} sets a global flag; it does not produce a token.
|
||
Similar to the @code{cp} request, you should use it at the beginning of
|
||
your document to control color output.
|
||
|
||
Colors can be also turned off with the @option{-c} command line option.
|
||
@endDefreq
|
||
|
||
@Defreq {defcolor, ident scheme color_components}
|
||
Define color with name @var{ident}. @var{scheme} can be one of the
|
||
following values: @code{rgb} (three components), @code{cym} (three
|
||
components), @code{cmyk} (four components), and @code{gray} or
|
||
@code{grey} (one component).
|
||
|
||
@cindex default color
|
||
@cindex color, default
|
||
Color components can be given either as a hexadecimal string or as
|
||
positive decimal integers in the range 0--65535. A hexadecimal string
|
||
contains all color components concatenated. It must start with either
|
||
@code{#} or @code{##}; the former specifies hex values in the range
|
||
0--255 (which are internally multiplied by@w{ }257), the latter in the
|
||
range 0--65535. Examples: @code{#FFC0CB} (pink), @code{##ffff0000ffff}
|
||
(magenta). The default color name @c{default} can't be redefined; its
|
||
value is device-specific (usually black). It is possible that the
|
||
default color for @code{\m} and @code{\M} is not identical.
|
||
|
||
@cindex @code{f} unit, and colors
|
||
@cindex unit, @code{f}, and colors
|
||
A new scaling indicator@w{ }@code{f} has been introduced which multiplies
|
||
its value by 65536; this makes it convenient to specify color components
|
||
as fractions in the range 0 to@w{ }1 (1f equals 65536u). Example:
|
||
|
||
@Example
|
||
.defcolor darkgreen rgb 0.1f 0.5f 0.2f
|
||
@endExample
|
||
|
||
Note that @code{f} is the default scaling indicator for the
|
||
@code{defcolor} request, thus the above statement is equivalent to
|
||
|
||
@Example
|
||
.defcolor darkgreen rgb 0.1 0.5 0.2
|
||
@endExample
|
||
@endDefreq
|
||
|
||
@DefescList {\\m, , c, }
|
||
@DefescItem {\\m, @lparen{}, co, }
|
||
@DefescListEnd {\\m, @lbrack{}, color, @rbrack}
|
||
Set drawing color. The following example shows how to turn the next four
|
||
words red.
|
||
|
||
@Example
|
||
\m[red]these are in red\m[] and these words are in black.
|
||
@endExample
|
||
|
||
The escape @code{\m[]} returns to the previous color.
|
||
|
||
The drawing color is associated with the current environment
|
||
(@pxref{Environments}).
|
||
|
||
Note that @code{\m} doesn't produce an input token in @code{gtroff}.
|
||
As a consequence, it can be used in requests like @code{mc} (which
|
||
expects a single character as an argument) to change the color on
|
||
the fly:
|
||
|
||
@Example
|
||
.mc \m[red]x\m[]
|
||
@endExample
|
||
@endDefesc
|
||
|
||
@DefescList {\\M, , c, }
|
||
@DefescItem {\\M, @lparen{}, co, }
|
||
@DefescListEnd {\\M, @lbrack{}, color, @rbrack}
|
||
Set background color for filled objects drawn with the
|
||
@code{\D'@dots{}'} commands.
|
||
|
||
A red ellipse can be created with the following code:
|
||
|
||
@Example
|
||
\M[red]\h'0.5i'\D'E 2i 1i'\M[]
|
||
@endExample
|
||
|
||
The escape @code{\M[]} returns to the previous fill color.
|
||
|
||
The fill color is associated with the current environment
|
||
(@pxref{Environments}).
|
||
|
||
Note that @code{\M} doesn't produce an input token in @code{gtroff}.
|
||
@endDefesc
|
||
|
||
|
||
@c =====================================================================
|
||
|
||
@node I/O, Postprocessor Access, Colors, gtroff Reference
|
||
@section I/O
|
||
@cindex i/o
|
||
@cindex input and output requests
|
||
@cindex requests for input and output
|
||
@cindex output and input requests
|
||
|
||
@code{gtroff} has several requests for including files:
|
||
|
||
@Defreq {so, file}
|
||
@cindex including a file (@code{so})
|
||
@cindex file, inclusion (@code{so})
|
||
Read in the specified @var{file} and
|
||
includes it in place of the @code{so} request. This is quite useful for
|
||
large documents, e.g.@: keeping each chapter in a separate file.
|
||
@xref{gsoelim}, for more information.
|
||
|
||
Since @code{gtroff} replaces the @code{so} request with the contents
|
||
of @code{file}, it makes a difference whether the data is terminated with
|
||
a newline or not: Assuming that file @file{xxx} contains the word
|
||
@samp{foo} without a final newline, this
|
||
|
||
@Example
|
||
This is
|
||
.so xxx
|
||
bar
|
||
@endExample
|
||
|
||
@noindent
|
||
yields @samp{This is foobar}.
|
||
@endDefreq
|
||
|
||
@Defreq {pso, command}
|
||
Read the standard output from the specified @var{command}
|
||
and includes it in place of the @code{pso} request.
|
||
|
||
@cindex safer mode
|
||
@cindex mode, safer
|
||
@cindex unsafe mode
|
||
@cindex mode, unsafe
|
||
This request causes an error if used in safer mode (which is the default).
|
||
Use @code{groff}'s or @code{troff}'s @option{-U} option to activate unsafe
|
||
mode.
|
||
|
||
The comment regarding a final newline for the @code{so} request is valid
|
||
for @code{pso} also.
|
||
@endDefreq
|
||
|
||
@Defreq {mso, file}
|
||
Identical to the @code{so} request except that @code{gtroff} searches for
|
||
the specified @var{file} in the same directories as macro files for the
|
||
the @option{-m} command line option. If the file name to be included
|
||
has the form @file{@var{name}.tmac} and it isn't found, @code{mso} tries
|
||
to include @file{tmac.@var{name}} and vice versa.
|
||
@endDefreq
|
||
|
||
@DefreqList {trf, file}
|
||
@DefreqListEnd {cf, file}
|
||
@cindex transparent output (@code{cf}, @code{trf})
|
||
@cindex output, transparent (@code{cf}, @code{trf})
|
||
Transparently output the contents of @var{file}. Each line is output
|
||
as if it were preceded by @code{\!}; however, the lines are not subject
|
||
to copy mode interpretation. If the file does not end with a newline,
|
||
then a newline is added (@code{trf} only). For example, to define a
|
||
macro@w{ }@code{x} containing the contents of file@w{ }@file{f}, use
|
||
|
||
@Example
|
||
.di x
|
||
.trf f
|
||
.di
|
||
@endExample
|
||
|
||
Both @code{trf} and @code{cf}, when used in a diversion,
|
||
embeds an object in the diversion which, when reread, causes the
|
||
contents of @var{file} to be transparently copied through to the
|
||
output. In @acronym{UNIX} @code{troff}, the contents of @var{file}
|
||
is immediately copied through to the output regardless of whether there
|
||
is a current diversion; this behaviour is so anomalous that it must be
|
||
considered a bug.
|
||
|
||
@cindex @code{trf} request, and invalid characters
|
||
@cindex characters, invalid for @code{trf} request
|
||
@cindex invalid characters for @code{trf} request
|
||
While @code{cf} copies the contents of @var{file} completely unprocessed,
|
||
@code{trf} disallows characters such as NUL that are not valid
|
||
@code{gtroff} input characters (@pxref{Identifiers}).
|
||
|
||
Both requests cause a line break.
|
||
@endDefreq
|
||
|
||
@Defreq {nx, [@Var{file}]}
|
||
@cindex processing next file (@code{nx})
|
||
@cindex file, processing next (@code{nx})
|
||
@cindex next file, processing (@code{nx})
|
||
Force @code{gtroff} to continue processing of
|
||
the file specified as an argument. If no argument is given, immediately
|
||
jump to the end of file.
|
||
@endDefreq
|
||
|
||
@Defreq {rd, [@Var{prompt} [@Var{arg1} @Var{arg2} @dots{}]]}
|
||
@cindex reading from standard input (@code{rd})
|
||
@cindex standard input, reading from (@code{rd})
|
||
@cindex input, standard, reading from (@code{rd})
|
||
Read from standard input, and include what is read as though it
|
||
were part of the input file. Text is read until a blank line
|
||
is encountered.
|
||
|
||
If standard input is a TTY input device (keyboard), write @var{prompt}
|
||
to standard error, followed by a colon (or send BEL for a beep if no
|
||
argument is given).
|
||
|
||
Arguments after @var{prompt} are available for the input. For example,
|
||
the line
|
||
|
||
@Example
|
||
.rd data foo bar
|
||
@endExample
|
||
|
||
with the input @w{@samp{This is \$2.}} prints
|
||
|
||
@Example
|
||
This is bar.
|
||
@endExample
|
||
@endDefreq
|
||
|
||
@cindex form letters
|
||
@cindex letters, form
|
||
Using the @code{nx} and @code{rd} requests,
|
||
it is easy to set up form letters. The form
|
||
letter template is constructed like this, putting the following lines
|
||
into a file called @file{repeat.let}:
|
||
|
||
@Example
|
||
.ce
|
||
\*(td
|
||
.sp 2
|
||
.nf
|
||
.rd
|
||
.sp
|
||
.rd
|
||
.fi
|
||
Body of letter.
|
||
.bp
|
||
.nx repeat.let
|
||
@endExample
|
||
|
||
@cindex @code{ex} request, used with @code{nx} and @code{rd}
|
||
@noindent
|
||
When this is run, a file containing the following lines should be
|
||
redirected in. Note that requests included in this file are executed
|
||
as though they were part of the form letter. The last block of input
|
||
is the @code{ex} request which tells @code{groff} to stop processing. If
|
||
this was not there, @code{groff} would not know when to stop.
|
||
|
||
@Example
|
||
Trent A. Fisher
|
||
708 NW 19th Av., #202
|
||
Portland, OR 97209
|
||
|
||
Dear Trent,
|
||
|
||
Len Adollar
|
||
4315 Sierra Vista
|
||
San Diego, CA 92103
|
||
|
||
Dear Mr. Adollar,
|
||
|
||
.ex
|
||
@endExample
|
||
|
||
@Defreq {pi, pipe}
|
||
Pipe the output of @code{gtroff} to the shell command(s)
|
||
specified by @var{pipe}. This request must occur before
|
||
@code{gtroff} has a chance to print anything.
|
||
|
||
@cindex safer mode
|
||
@cindex mode, safer
|
||
@cindex unsafe mode
|
||
@cindex mode, unsafe
|
||
@code{pi} causes an error if used in safer mode (which is the default).
|
||
Use @code{groff}'s or @code{troff}'s @option{-U} option to activate unsafe
|
||
mode.
|
||
|
||
Multiple calls to @code{pi} are allowed, acting as a chain. For example,
|
||
|
||
@Example
|
||
.pi foo
|
||
.pi bar
|
||
...
|
||
@endExample
|
||
|
||
is the same as @w{@samp{.pi foo | bar}}.
|
||
|
||
@cindex @code{groff}, and @code{pi} request
|
||
@cindex @code{pi} request, and @code{groff}
|
||
Note that the intermediate output format of @code{gtroff} is piped to
|
||
the specified commands. Consequently, calling @code{groff} without the
|
||
@option{-Z} option normally causes a fatal error.
|
||
@endDefreq
|
||
|
||
@DefreqList {sy, cmds}
|
||
@DefregListEnd {systat}
|
||
Execute the shell command(s) specified by @var{cmds}. The output is not
|
||
saved anyplace, so it is up to the user to do so.
|
||
|
||
@cindex safer mode
|
||
@cindex mode, safer
|
||
@cindex unsafe mode
|
||
@cindex mode, unsafe
|
||
This request causes an error if used in safer mode (which is the default).
|
||
Use @code{groff}'s or @code{troff}'s @option{-U} option to activate unsafe
|
||
mode.
|
||
|
||
For example, the following code fragment introduces the current time into a
|
||
document:
|
||
|
||
@cindex time, current
|
||
@cindex current time
|
||
@pindex perl
|
||
@Example
|
||
.sy perl -e 'printf ".nr H %d\\n.nr M %d\\n.nr S %d\\n",\
|
||
(localtime(time))[2,1,0]' > /tmp/x\n[$$]
|
||
.so /tmp/x\n[$$]
|
||
.sy rm /tmp/x\n[$$]
|
||
\nH:\nM:\nS
|
||
@endExample
|
||
|
||
@noindent
|
||
Note that this works by having the @code{perl} script (run by @code{sy})
|
||
print out the @code{nr} requests which set the number registers
|
||
@code{H}, @code{M}, and @code{S}, and then reads those commands in with
|
||
the @code{so} request.
|
||
|
||
For most practical purposes, the number registers @code{seconds},
|
||
@code{minutes}, and @code{hours} which are initialized at start-up of
|
||
@code{gtroff} should be sufficient. Use the @code{af} request to get a
|
||
formatted output:
|
||
|
||
@Example
|
||
.af hours 00
|
||
.af minutes 00
|
||
.af seconds 00
|
||
\n[hours]:\n[minutes]:\n[seconds]
|
||
@endExample
|
||
|
||
@cindex @code{system()} return value register (@code{systat})
|
||
The @code{systat} read-write number register contains the return value
|
||
of the @code{system()} function executed by the last @code{sy} request.
|
||
@endDefreq
|
||
|
||
@DefreqList {open, stream file}
|
||
@DefreqListEnd {opena, stream file}
|
||
@cindex opening file (@code{open})
|
||
@cindex file, opening (@code{open})
|
||
@cindex appending to a file (@code{opena})
|
||
@cindex file, appending to (@code{opena})
|
||
Open the specified @var{file} for writing and
|
||
associates the specified @var{stream} with it.
|
||
|
||
The @code{opena} request is like @code{open}, but if the file exists,
|
||
append to it instead of truncating it.
|
||
|
||
@cindex safer mode
|
||
@cindex mode, safer
|
||
@cindex unsafe mode
|
||
@cindex mode, unsafe
|
||
Both @code{open} and @code{opena} cause an error if used in safer mode
|
||
(which is the default). Use @code{groff}'s or @code{troff}'s @option{-U}
|
||
option to activate unsafe mode.
|
||
@endDefreq
|
||
|
||
@DefreqList {write, stream data}
|
||
@DefreqListEnd {writec, stream data}
|
||
@cindex copy-in mode, and @code{write} requests
|
||
@cindex mode, copy-in, and @code{write} requests
|
||
@cindex writing to file (@code{write})
|
||
@cindex file, writing to (@code{write})
|
||
Write to the file associated with the specified @var{stream}.
|
||
The stream must previously have
|
||
been the subject of an open request. The remainder of the line is
|
||
interpreted as the @code{ds} request reads its second argument: A
|
||
leading @samp{"} is stripped, and it is read in copy-in mode.
|
||
|
||
The @code{writec} request is like @code{write}, but only
|
||
@code{write} appends a newline to the data.
|
||
@endDefreq
|
||
|
||
@Defreq {writem, stream xx}
|
||
@cindex @code{asciify} request, and @code{writem}
|
||
Write the contents of the macro or string @var{xx}
|
||
to the file associated with the specified @var{stream}.
|
||
|
||
@var{xx} is read in copy mode, i.e., already formatted elements are
|
||
ignored. Consequently, diversions must be unformatted with the
|
||
@code{asciify} request before calling @code{writem}. Usually, this
|
||
means a loss of information.
|
||
@endDefreq
|
||
|
||
@Defreq {close, stream}
|
||
@cindex closing file (@code{close})
|
||
@cindex file, closing (@code{close})
|
||
Close the specified @var{stream};
|
||
the stream is no longer an acceptable argument to the
|
||
@code{write} request.
|
||
|
||
Here a simple macro to write an index entry.
|
||
|
||
@Example
|
||
.open idx test.idx
|
||
.
|
||
.de IX
|
||
. write idx \\n[%] \\$*
|
||
..
|
||
.
|
||
.IX test entry
|
||
.
|
||
.close idx
|
||
@endExample
|
||
@endDefreq
|
||
|
||
@DefescList {\\V, , e, }
|
||
@DefescItem {\\V, @lparen{}, ev, }
|
||
@DefescListEnd {\\V, @lbrack{}, env, @rbrack}
|
||
Interpolate the contents of the specified environment variable
|
||
@var{env} (one-character name@w{ }@var{e}, two-character name @var{ev})
|
||
as returned by the function @code{getenv}. @code{\V} is interpreted
|
||
in copy-in mode.
|
||
@endDefesc
|
||
|
||
|
||
@c =====================================================================
|
||
|
||
@node Postprocessor Access, Miscellaneous, I/O, gtroff Reference
|
||
@section Postprocessor Access
|
||
@cindex postprocessor access
|
||
@cindex access of postprocessor
|
||
|
||
There are two escapes which give information directly to the
|
||
postprocessor. This is particularly useful for embedding
|
||
@sc{PostScript} into the final document.
|
||
|
||
@Defesc {\\X, ', xxx, '}
|
||
Embeds its argument into the @code{gtroff}
|
||
output preceded with @w{@samp{x X}}.
|
||
|
||
@cindex @code{\&}, in @code{\X}
|
||
@cindex @code{\)}, in @code{\X}
|
||
@cindex @code{\%}, in @code{\X}
|
||
@ifnotinfo
|
||
@cindex @code{\:}, in @code{\X}
|
||
@end ifnotinfo
|
||
@ifinfo
|
||
@cindex @code{\@r{<colon>}}, in @code{\X}
|
||
@end ifinfo
|
||
The escapes @code{\&}, @code{\)}, @code{\%}, and @code{\:} are ignored
|
||
within @code{\X}, @w{@samp{\ }} and @code{\~} are converted to single
|
||
space characters. All other escapes (except @code{\\} which produces a
|
||
backslash) cause an error.
|
||
|
||
@kindex use_charnames_in_special
|
||
@pindex DESC@r{, and @code{use_charnames_in_special}}
|
||
@cindex @code{\X}, and special characters
|
||
If the @samp{use_charnames_in_special} keyword is set in the @file{DESC}
|
||
file, special characters no longer cause an error; the name @var{xx} is
|
||
represented as @samp{\(@var{xx})} in the @w{@samp{x X}} output command.
|
||
Additionally, the backslash is represented as @code{\\}.
|
||
|
||
@samp{use_charnames_in_special} is currently used by @code{grohtml} only.
|
||
@endDefesc
|
||
|
||
@DefescList {\\Y, , n, }
|
||
@DefescItem {\\Y, @lparen{}, nm, }
|
||
@DefescListEnd {\\Y, @lbrack{}, name, @rbrack}
|
||
This is approximately equivalent to @samp{\X'\*[@var{name}]'}
|
||
(one-character name@w{ }@var{n}, two-character name @var{nm}).
|
||
However, the contents of the string or macro @var{name} are not
|
||
interpreted; also it is permitted for @var{name} to have been defined
|
||
as a macro and thus contain newlines (it is not permitted for the
|
||
argument to @code{\X} to contain newlines). The inclusion of
|
||
newlines requires an extension to the @acronym{UNIX} @code{troff}
|
||
output format, and confuses drivers that do not know about this
|
||
extension (@pxref{Device Control Commands}).
|
||
@endDefesc
|
||
|
||
@xref{Output Devices}.
|
||
|
||
|
||
@c =====================================================================
|
||
|
||
@node Miscellaneous, Gtroff Internals, Postprocessor Access, gtroff Reference
|
||
@section Miscellaneous
|
||
|
||
This section documents parts of @code{gtroff} which cannot (yet) be
|
||
categorized elsewhere in this manual.
|
||
|
||
@Defreq {nm, [@Var{start} [@Var{inc} [@Var{space} [@Var{indent}]]]]}
|
||
@cindex printing line numbers (@code{nm})
|
||
@cindex line numbers, printing (@code{nm})
|
||
@cindex numbers, line, printing (@code{nm})
|
||
Print line numbers.
|
||
@var{start} is the line number of the @emph{next}
|
||
output line. @var{inc} indicates which line numbers are printed.
|
||
For example, the value@w{ }5 means to emit only line numbers which
|
||
are multiples of@w{ }5; this defaults to@w{ }1. @var{space} is the
|
||
space to be left between the number and the text; this defaults to
|
||
one digit space. The fourth argument is the indentation of the line
|
||
numbers, defaulting to zero. Both @var{space} and @var{indent} are
|
||
given as multiples of digit spaces; they can be negative also.
|
||
Without any arguments, line numbers are turned off.
|
||
|
||
@code{gtroff} reserves three digit spaces for the line number (which is
|
||
printed right-justified) plus the amount given by @var{indent}; the
|
||
output lines are concatenated to the line numbers, separated by
|
||
@var{space}, and @emph{without} reducing the line length. Depending
|
||
on the value of the horizontal page offset (as set with the
|
||
@code{po} request), line numbers which are longer than the reserved
|
||
space stick out to the left, or the whole line is moved to the right.
|
||
|
||
Parameters corresponding to missing arguments are not changed; any
|
||
non-digit argument (to be more precise, any argument starting with a
|
||
character valid as a delimiter for identifiers) is also treated as
|
||
missing.
|
||
|
||
If line numbering has been disabled with a call to @code{nm} without
|
||
an argument, it can be reactivated with @samp{.nm +0}, using the
|
||
previously active line numbering parameters.
|
||
|
||
The parameters of @code{nm} are associated with the current environment
|
||
(@pxref{Environments}). The current output line number is available
|
||
in the number register @code{ln}.
|
||
|
||
@Example
|
||
.po 1m
|
||
.ll 2i
|
||
This test shows how line numbering works with groff.
|
||
.nm 999
|
||
This test shows how line numbering works with groff.
|
||
.br
|
||
.nm xxx 3 2
|
||
.ll -\w'0'u
|
||
This test shows how line numbering works with groff.
|
||
.nn 2
|
||
This test shows how line numbering works with groff.
|
||
@endExample
|
||
|
||
@noindent
|
||
And here the result:
|
||
|
||
@Example
|
||
This test shows how
|
||
line numbering works
|
||
999 with groff. This
|
||
1000 test shows how line
|
||
1001 numbering works with
|
||
1002 groff.
|
||
This test shows how
|
||
line numbering
|
||
works with groff.
|
||
This test shows how
|
||
1005 line numbering
|
||
works with groff.
|
||
@endExample
|
||
@endDefreq
|
||
|
||
@Defreq {nn, [@Var{skip}]}
|
||
Temporarily turn off line numbering. The argument is the number
|
||
of lines not to be numbered; this defaults to@w{ }1.
|
||
@endDefreq
|
||
|
||
@Defreq {mc, glyph [@Var{dist}]}
|
||
@cindex margin glyph (@code{mc})
|
||
@cindex glyph, for margins (@code{mc})
|
||
Print a @dfn{margin character} to the right of the
|
||
text.@footnote{@dfn{Margin character} is a misnomer since it is an
|
||
output glyph.} The first argument is the glyph to be
|
||
printed. The second argument is the distance away from the right
|
||
margin. If missing, the previously set value is used; default is
|
||
10@dmn{pt}). For text lines that are too long (that is, longer than
|
||
the text length plus @var{dist}), the margin character is directly
|
||
appended to the lines.
|
||
|
||
With no arguments the margin character is turned off.
|
||
If this occurs before a break, no margin character is printed.
|
||
|
||
@cindex @code{tl} request, and @code{mc}
|
||
For empty lines and lines produced by the @code{tl} request no margin
|
||
character is emitted.
|
||
|
||
The margin character is associated with the current environment
|
||
(@pxref{Environments}).
|
||
|
||
@pindex nrchbar
|
||
@pindex changebar
|
||
This is quite useful for indicating text that has changed, and, in fact,
|
||
there are programs available for doing this (they are called
|
||
@code{nrchbar} and @code{changebar} and can be found in any
|
||
@samp{comp.sources.unix} archive.
|
||
|
||
@Example
|
||
.ll 3i
|
||
.mc |
|
||
This paragraph is highlighted with a margin
|
||
character.
|
||
.sp
|
||
Note that vertical space isn't marked.
|
||
.br
|
||
\&
|
||
.br
|
||
But we can fake it with `\&'.
|
||
@endExample
|
||
|
||
Result:
|
||
|
||
@Example
|
||
This paragraph is highlighted |
|
||
with a margin character. |
|
||
|
||
Note that vertical space isn't |
|
||
marked. |
|
||
|
|
||
But we can fake it with `\&'. |
|
||
@endExample
|
||
@endDefreq
|
||
|
||
@DefreqList {psbb, filename}
|
||
@DefregItem {llx}
|
||
@DefregItem {lly}
|
||
@DefregItem {urx}
|
||
@DefregListEnd {ury}
|
||
@cindex PostScript, bounding box
|
||
@cindex bounding box
|
||
Retrieve the bounding box of the PostScript image
|
||
found in @var{filename}.
|
||
The file must conform to
|
||
Adobe's @dfn{Document Structuring Conventions} (DSC);
|
||
the command searches for a @code{%%BoundingBox} comment
|
||
and extracts the bounding box values into the number registers
|
||
@code{llx}, @code{lly}, @code{urx}, and @code{ury}.
|
||
If an error occurs (for example, @code{psbb} cannot find
|
||
the @code{%%BoundingBox} comment),
|
||
it sets the four number registers to zero.
|
||
@endDefreq
|
||
|
||
|
||
@c =====================================================================
|
||
|
||
@node Gtroff Internals, Debugging, Miscellaneous, gtroff Reference
|
||
@section @code{gtroff} Internals
|
||
|
||
@cindex input token
|
||
@cindex token, input
|
||
@cindex output node
|
||
@cindex node, output
|
||
@code{gtroff} processes input in three steps. One or more input
|
||
characters are converted to an @dfn{input token}.@footnote{Except the
|
||
escapes @code{\f}, @code{\F}, @code{\H}, @code{\m}, @code{\M}, @code{\R},
|
||
@code{\s}, and @code{\S} which are processed immediately if not in
|
||
copy-in mode.} Then, one or more input tokens are converted to an
|
||
@dfn{output node}. Finally, output nodes are converted to the
|
||
intermediate output language understood by all output devices.
|
||
|
||
Actually, before step one happens, @code{gtroff} converts certain
|
||
escape sequences into reserved input characters (not accessible by
|
||
the user); such reserved characters are used for other internal
|
||
processing also -- this is the very reason why not all characters
|
||
are valid input. @xref{Identifiers}, for more on this topic.
|
||
|
||
For example, the input string @samp{fi\[:u]} is converted into a
|
||
character token @samp{f}, a character token @samp{i}, and a special
|
||
token @samp{:u} (representing u@w{ }umlaut). Later on, the character
|
||
tokens @samp{f} and @samp{i} are merged to a single output node
|
||
representing the ligature glyph @samp{fi} (provided the current font
|
||
has a glyph for this ligature); the same happens with @samp{:u}. All
|
||
output glyph nodes are `processed' which means that they are invariably
|
||
associated with a given font, font size, advance width, etc. During
|
||
the formatting process, @code{gtroff} itself adds various nodes to
|
||
control the data flow.
|
||
|
||
Macros, diversions, and strings collect elements in two chained lists:
|
||
a list of input tokens which have been passed unprocessed, and a list
|
||
of output nodes. Consider the following the diversion.
|
||
|
||
@Example
|
||
.di xxx
|
||
a
|
||
\!b
|
||
c
|
||
.br
|
||
.di
|
||
@endExample
|
||
|
||
@noindent
|
||
It contains these elements.
|
||
|
||
@multitable {@i{vertical size node}} {token list} {element number}
|
||
@item node list @tab token list @tab element number
|
||
|
||
@item @i{line start node} @tab --- @tab 1
|
||
@item @i{glyph node @code{a}} @tab --- @tab 2
|
||
@item @i{word space node} @tab --- @tab 3
|
||
@item --- @tab @code{b} @tab 4
|
||
@item --- @tab @code{\n} @tab 5
|
||
@item @i{glyph node @code{c}} @tab --- @tab 6
|
||
@item @i{vertical size node} @tab --- @tab 7
|
||
@item @i{vertical size node} @tab --- @tab 8
|
||
@item --- @tab @code{\n} @tab 9
|
||
@end multitable
|
||
|
||
@cindex @code{\v}, internal representation
|
||
@noindent
|
||
Elements 1, 7, and@w{ }8 are inserted by @code{gtroff}; the latter two
|
||
(which are always present) specify the vertical extent of the last
|
||
line, possibly modified by @code{\x}. The @code{br} request finishes
|
||
the current partial line, inserting a newline input token which is
|
||
subsequently converted to a space when the diversion is reread. Note
|
||
that the word space node has a fixed width which isn't stretchable
|
||
anymore. To convert horizontal space nodes back to input tokens, use
|
||
the @code{unformat} request.
|
||
|
||
Macros only contain elements in the token list (and the node list is
|
||
empty); diversions and strings can contain elements in both lists.
|
||
|
||
Note that the @code{chop} request simply reduces the number of elements in a
|
||
macro, string, or diversion by one. Exceptions are @dfn{compatibility save}
|
||
and @dfn{compatibility ignore} input tokens which are ignored. The
|
||
@code{substring} request also ignores those input tokens.
|
||
|
||
Some requests like @code{tr} or @code{cflags} work on glyph
|
||
identifiers only; this means that the associated glyph can be changed
|
||
without destroying this association. This can be very helpful for
|
||
substituting glyphs. In the following example, we assume that
|
||
glyph @samp{foo} isn't available by default, so we provide a
|
||
substitution using the @code{fchar} request and map it to input
|
||
character @samp{x}.
|
||
|
||
@Example
|
||
.fchar \[foo] foo
|
||
.tr x \[foo]
|
||
@endExample
|
||
|
||
@noindent
|
||
Now let us assume that we install an additional special font
|
||
@samp{bar} which has glyph @samp{foo}.
|
||
|
||
@Example
|
||
.special bar
|
||
.rchar \[foo]
|
||
@endExample
|
||
|
||
@noindent
|
||
Since glyphs defined with @code{fchar} are searched before glyphs
|
||
in special fonts, we must call @code{rchar} to remove the definition
|
||
of the fallback glyph. Anyway, the translation is still active;
|
||
@samp{x} now maps to the real glyph @samp{foo}.
|
||
|
||
|
||
@c =====================================================================
|
||
|
||
@node Debugging, Implementation Differences, Gtroff Internals, gtroff Reference
|
||
@section Debugging
|
||
@cindex debugging
|
||
|
||
@code{gtroff} is not easy to debug, but there are some useful features
|
||
and strategies for debugging.
|
||
|
||
@Defreq {lf, line filename}
|
||
@pindex soelim
|
||
@cindex multi-file documents
|
||
@cindex documents, multi-file
|
||
@cindex setting input line number (@code{lf})
|
||
@cindex input line number, setting (@code{lf})
|
||
@cindex number, input line, setting (@code{lf})
|
||
Change the line number and the file name @code{gtroff} shall use for
|
||
error and warning messages. @var{line} is the input line number of the
|
||
@emph{next} line.
|
||
|
||
Without argument, the request is ignored.
|
||
|
||
This is a debugging aid for documents which are split into many files,
|
||
then put together with @code{soelim} and other preprocessors. Usually,
|
||
it isn't invoked manually.
|
||
@endDefreq
|
||
|
||
@DefreqList {tm, string}
|
||
@DefreqItem {tm1, string}
|
||
@DefreqListEnd {tmc, string}
|
||
@cindex printing to stderr (@code{tm}, @code{tm1}, @code{tmc})
|
||
@cindex stderr, printing to (@code{tm}, @code{tm1}, @code{tmc})
|
||
Send @var{string} to the standard error output;
|
||
this is very useful for printing debugging messages among other things.
|
||
|
||
@var{string} is read in copy mode.
|
||
|
||
The @code{tm} request ignores leading spaces of @var{string}; @code{tm1}
|
||
handles its argument similar to the @code{ds} request: a leading double
|
||
quote in @var{string} is stripped to allow initial blanks.
|
||
|
||
The @code{tmc} request is similar to @code{tm1} but does
|
||
not append a newline (as is done in @code{tm} and @code{tm1}).
|
||
@endDefreq
|
||
|
||
@Defreq {ab, [@Var{string}]}
|
||
@cindex aborting (@code{ab})
|
||
Similar to the @code{tm} request, except that
|
||
it causes @code{gtroff} to stop processing. With no argument it
|
||
prints @samp{User Abort.} to standard error.
|
||
@endDefreq
|
||
|
||
@Defreq {ex, }
|
||
@cindex @code{ex} request, use in debugging
|
||
@cindex exiting (@code{ex})
|
||
The @code{ex} request also causes @code{gtroff} to stop processing;
|
||
see also @ref{I/O}.
|
||
@endDefreq
|
||
|
||
When doing something involved it is useful to leave the debugging
|
||
statements in the code and have them turned on by a command line flag.
|
||
|
||
@Example
|
||
.if \n(DB .tm debugging output
|
||
@endExample
|
||
|
||
@noindent
|
||
To activate these statements say
|
||
|
||
@Example
|
||
groff -rDB=1 file
|
||
@endExample
|
||
|
||
If it is known in advance that there will be many errors and no useful
|
||
output, @code{gtroff} can be forced to suppress formatted output with
|
||
the @option{-z} flag.
|
||
|
||
@Defreq {pm, }
|
||
@cindex dumping symbol table (@code{pm})
|
||
@cindex symbol table, dumping (@code{pm})
|
||
Print the entire symbol table on @code{stderr}. Names of all defined
|
||
macros, strings, and diversions are print together with their size in
|
||
bytes. Since @code{gtroff} sometimes adds nodes by itself, the
|
||
returned size can be larger than expected.
|
||
|
||
This request differs from @acronym{UNIX} @code{troff}: @code{gtroff}
|
||
reports the sizes of diversions, ignores an additional argument to
|
||
print only the total of the sizes, and the size isn't returned in
|
||
blocks of 128 characters.
|
||
@endDefreq
|
||
|
||
@Defreq {pnr, }
|
||
@cindex dumping number registers (@code{pnr})
|
||
@cindex number registers, dumping (@code{pnr})
|
||
Print the names and contents of all
|
||
currently defined number registers on @code{stderr}.
|
||
@endDefreq
|
||
|
||
@Defreq {ptr, }
|
||
@cindex dumping traps (@code{ptr})
|
||
@cindex traps, dumping (@code{ptr})
|
||
Print the names and positions of all traps
|
||
(not including input line traps and diversion traps) on @code{stderr}.
|
||
Empty slots in the page trap list are printed as well, because they can
|
||
affect the priority of subsequently planted traps.
|
||
@endDefreq
|
||
|
||
@Defreq {fl, }
|
||
@cindex flush output (@code{fl})
|
||
@cindex output, flush (@code{fl})
|
||
@cindex interactive use of @code{gtroff}
|
||
@cindex @code{gtroff}, interactive use
|
||
Instruct @code{gtroff} to flush its output immediately. The intent
|
||
is for interactive use, but this behaviour is currently not
|
||
implemented in @code{gtroff}. Contrary to @acronym{UNIX} @code{troff},
|
||
TTY output is sent to a device driver also (@code{grotty}), making it
|
||
non-trivial to communicate interactively.
|
||
|
||
This request causes a line break.
|
||
@endDefreq
|
||
|
||
@Defreq {backtrace, }
|
||
@cindex backtrace of input stack (@code{backtrace})
|
||
@cindex input stack, backtrace (@code{backtrace})
|
||
Print a backtrace of the input stack to the standard error stream.
|
||
|
||
Consider the following in file @file{test}:
|
||
|
||
@Example
|
||
.de xxx
|
||
. backtrace
|
||
..
|
||
.de yyy
|
||
. xxx
|
||
..
|
||
.
|
||
.yyy
|
||
@endExample
|
||
|
||
@noindent
|
||
On execution, @code{gtroff} prints the following:
|
||
|
||
@Example
|
||
test:2: backtrace: macro `xxx'
|
||
test:5: backtrace: macro `yyy'
|
||
test:8: backtrace: file `test'
|
||
@endExample
|
||
|
||
The option @option{-b} of @code{gtroff} internally calls a variant of
|
||
this request on each error and warning.
|
||
@endDefreq
|
||
|
||
@Defreg {slimit}
|
||
@cindex input stack, setting limit
|
||
Use the @code{slimit} number register
|
||
to set the maximum number of objects on the input stack.
|
||
If @code{slimit} is less than or equal to@w{ }0,
|
||
there is no limit set.
|
||
With no limit, a buggy recursive macro can exhaust virtual memory.
|
||
|
||
The default value is 1000; this is a compile-time constant.
|
||
@endDefreg
|
||
|
||
@Defreq {warnscale, si}
|
||
Set the scaling indicator used in warnings to @var{si}. Valid values for
|
||
@var{si} are @samp{u}, @samp{i}, @samp{c}, @samp{p}, and @samp{P}. At
|
||
startup, it is set to @samp{i}.
|
||
@endDefreq
|
||
|
||
@Defreq {spreadwarn, [@Var{limit}]}
|
||
Make @code{gtroff} emit a warning if the additional space inserted for
|
||
each space between words in an output line is larger or equal to
|
||
@var{limit}. A negative value is changed to zero; no argument toggles the
|
||
warning on and off without changing @var{limit}. The default scaling
|
||
indicator is @samp{m}. At startup, @code{spreadwarn} is deactivated, and
|
||
@var{limit} is set to 3@dmn{m}.
|
||
|
||
For example,
|
||
|
||
@Example
|
||
.spreadwarn 0.2m
|
||
@endExample
|
||
|
||
@noindent
|
||
will cause a warning if @code{gtroff} must add 0.2@dmn{m} or more for each
|
||
interword space in a line.
|
||
|
||
This request is active only if text is justified to both margins (using
|
||
@w{@samp{.ad b}}).
|
||
@endDefreq
|
||
|
||
@cindex warnings
|
||
@code{gtroff} has command line options for printing out more warnings
|
||
(@option{-w}) and for printing backtraces (@option{-b}) when a warning
|
||
or an error occurs. The most verbose level of warnings is @option{-ww}.
|
||
|
||
@DefreqList {warn, [@Var{flags}]}
|
||
@DefregListEnd {.warn}
|
||
@cindex level of warnings (@code{warn})
|
||
@cindex warnings, level (@code{warn})
|
||
Control the level of warnings checked for. The @var{flags} are the sum
|
||
of the numbers associated with each warning that is to be enabled; all
|
||
other warnings are disabled. The number associated with each warning is
|
||
listed below. For example, @w{@code{.warn 0}} disables all warnings,
|
||
and @w{@code{.warn 1}} disables all warnings except that about missing
|
||
glyphs. If no argument is given, all warnings are enabled.
|
||
|
||
The read-only number register @code{.warn} contains the current warning
|
||
level.
|
||
@endDefreq
|
||
|
||
@menu
|
||
* Warnings::
|
||
@end menu
|
||
|
||
@c ---------------------------------------------------------------------
|
||
|
||
@node Warnings, , Debugging, Debugging
|
||
@subsection Warnings
|
||
@cindex warnings
|
||
|
||
The warnings that can be given to @code{gtroff} are divided into the
|
||
following categories. The name associated with each warning is used by
|
||
the @option{-w} and @option{-W} options; the number is used by the
|
||
@code{warn} request and by the @code{.warn} register.
|
||
|
||
@table @samp
|
||
@item char
|
||
@itemx 1
|
||
Non-existent glyphs.@footnote{@code{char} is a misnomer since it reports
|
||
missing glyphs -- there aren't missing input characters, only invalid
|
||
ones.} This is enabled by default.
|
||
|
||
@item number
|
||
@itemx 2
|
||
Invalid numeric expressions. This is enabled by default.
|
||
@xref{Expressions}.
|
||
|
||
@item break
|
||
@itemx 4
|
||
@cindex fill mode
|
||
@cindex mode, fill
|
||
In fill mode, lines which could not be broken so that their length was
|
||
less than the line length. This is enabled by default.
|
||
|
||
@item delim
|
||
@itemx 8
|
||
Missing or mismatched closing delimiters.
|
||
|
||
@item el
|
||
@itemx 16
|
||
@cindex @code{ie} request, and warnings
|
||
@cindex @code{el} request, and warnings
|
||
Use of the @code{el} request with no matching @code{ie} request.
|
||
@xref{if-else}.
|
||
|
||
@item scale
|
||
@itemx 32
|
||
Meaningless scaling indicators.
|
||
|
||
@item range
|
||
@itemx 64
|
||
Out of range arguments.
|
||
|
||
@item syntax
|
||
@itemx 128
|
||
Dubious syntax in numeric expressions.
|
||
|
||
@item di
|
||
@itemx 256
|
||
@cindex @code{di} request, and warnings
|
||
@cindex @code{da} request, and warnings
|
||
Use of @code{di} or @code{da} without an argument when there is no
|
||
current diversion.
|
||
|
||
@item mac
|
||
@itemx 512
|
||
@cindex @code{de}, @code{de1}, @code{dei} requests, and warnings
|
||
@cindex @code{am}, @code{am1}, @code{ami} requests, and warnings
|
||
@cindex @code{ds}, @code{ds1} requests, and warnings
|
||
@cindex @code{as}, @code{as1} requests, and warnings
|
||
@cindex @code{di} request, and warnings
|
||
@cindex @code{da} request, and warnings
|
||
@cindex @code{box}, @code{boxa} requests, and warnings
|
||
@cindex @code{\*}, and warnings
|
||
Use of undefined strings, macros and diversions. When an undefined
|
||
string, macro, or diversion is used, that string is automatically
|
||
defined as empty. So, in most cases, at most one warning is given
|
||
for each name.
|
||
|
||
@item reg
|
||
@itemx 1024
|
||
@cindex @code{nr} request, and warnings
|
||
@cindex @code{\R}, and warnings
|
||
@cindex @code{\n}, and warnings
|
||
Use of undefined number registers. When an undefined number register is
|
||
used, that register is automatically defined to have a value of@w{ }0.
|
||
So, in most cases, at most one warning is given for use of a particular
|
||
name.
|
||
|
||
@item tab
|
||
@itemx 2048
|
||
@cindex @code{\t}, and warnings
|
||
Use of a tab character where a number was expected.
|
||
|
||
@item right-brace
|
||
@itemx 4096
|
||
@cindex @code{\@}}, and warnings
|
||
Use of @code{\@}} where a number was expected.
|
||
|
||
@item missing
|
||
@itemx 8192
|
||
Requests that are missing non-optional arguments.
|
||
|
||
@item input
|
||
@itemx 16384
|
||
Invalid input characters.
|
||
|
||
@item escape
|
||
@itemx 32768
|
||
Unrecognized escape sequences. When an unrecognized escape sequence
|
||
@code{\@var{X}} is encountered, the escape character is ignored, and
|
||
@var{X} is printed.
|
||
|
||
@item space
|
||
@itemx 65536
|
||
@cindex compatibility mode
|
||
Missing space between a request or macro and its argument. This warning
|
||
is given when an undefined name longer than two characters is
|
||
encountered, and the first two characters of the name make a defined
|
||
name. The request or macro is not invoked. When this warning is
|
||
given, no macro is automatically defined. This is enabled by default.
|
||
This warning never occurs in compatibility mode.
|
||
|
||
@item font
|
||
@itemx 131072
|
||
Non-existent fonts. This is enabled by default.
|
||
|
||
@item ig
|
||
@itemx 262144
|
||
Invalid escapes in text ignored with the @code{ig} request. These are
|
||
conditions that are errors when they do not occur in ignored text.
|
||
|
||
@item color
|
||
@itemx 524288
|
||
Color related warnings.
|
||
|
||
@item all
|
||
All warnings except @samp{di}, @samp{mac} and @samp{reg}. It is
|
||
intended that this covers all warnings that are useful with traditional
|
||
macro packages.
|
||
|
||
@item w
|
||
All warnings.
|
||
@end table
|
||
|
||
|
||
@c =====================================================================
|
||
|
||
@node Implementation Differences, , Debugging, gtroff Reference
|
||
@section Implementation Differences
|
||
@cindex implementation differences
|
||
@cindex differences in implementation
|
||
@cindex incompatibilities with @acronym{AT&T} @code{troff}
|
||
@cindex compatibility mode
|
||
@cindex mode, compatibility
|
||
|
||
GNU @code{troff} has a number of features which cause incompatibilities
|
||
with documents written with old versions of @code{troff}.
|
||
|
||
@cindex long names
|
||
@cindex names, long
|
||
Long names cause some incompatibilities. @acronym{UNIX} @code{troff}
|
||
interprets
|
||
|
||
@Example
|
||
.dsabcd
|
||
@endExample
|
||
|
||
@cindex @code{\*}, incompatibilities with @acronym{AT&T} @code{troff}
|
||
@cindex @code{\n}, incompatibilities with @acronym{AT&T} @code{troff}
|
||
@noindent
|
||
as defining a string @samp{ab} with contents @samp{cd}. Normally, GNU
|
||
@code{troff} interprets this as a call of a macro named
|
||
@code{dsabcd}. Also @acronym{UNIX} @code{troff} interprets
|
||
@code{\*[} or @code{\n[} as references to a string or number register
|
||
called @samp{[}. In GNU @code{troff}, however, this is normally
|
||
interpreted as the start of a long name. In compatibility mode GNU
|
||
@code{troff} interprets long names in the traditional way
|
||
(which means that they are not recognized as names).
|
||
|
||
@DefreqList {cp, [@Var{n}]}
|
||
@DefreqItem {do, cmd}
|
||
@DefregListEnd {.C}
|
||
If @var{n} is missing or non-zero, turn on compatibility mode;
|
||
otherwise, turn it off.
|
||
|
||
The read-only number register @code{.C} is@w{ }1 if compatibility mode is
|
||
on, 0@w{ }otherwise.
|
||
|
||
Compatibility mode can be also turned on with the @option{-C} command line
|
||
option.
|
||
|
||
The @code{do} request turns off compatibility mode
|
||
while executing its arguments as a @code{gtroff} command.
|
||
|
||
@Example
|
||
.do fam T
|
||
@endExample
|
||
|
||
@noindent
|
||
executes the @code{fam} request when compatibility mode
|
||
is enabled.
|
||
|
||
@code{gtroff} restores the previous compatibility setting
|
||
before interpreting any files sourced by the @var{cmd}.
|
||
@endDefreq
|
||
|
||
@cindex input level in delimited arguments
|
||
@cindex delimited arguments, incompatibilities with @acronym{AT&T} @code{troff}
|
||
Two other features are controlled by @option{-C}. If not in
|
||
compatibility mode, GNU @code{troff} preserves the input level in
|
||
delimited arguments:
|
||
|
||
@Example
|
||
.ds xx '
|
||
\w'abc\*(xxdef'
|
||
@endExample
|
||
|
||
@noindent
|
||
In compatibility mode, the string @samp{72def'} is returned; without
|
||
@option{-C} the resulting string is @samp{168} (assuming a TTY output
|
||
device).
|
||
|
||
@cindex @code{\f}, incompatibilities with @acronym{AT&T} @code{troff}
|
||
@cindex @code{\H}, incompatibilities with @acronym{AT&T} @code{troff}
|
||
@cindex @code{\s}, incompatibilities with @acronym{AT&T} @code{troff}
|
||
@cindex @code{\S}, incompatibilities with @acronym{AT&T} @code{troff}
|
||
Finally, the escapes @code{\f}, @code{\H}, @code{\m}, @code{\M},
|
||
@code{\R}, @code{\s}, and @code{\S} are transparent for recognizing the
|
||
beginning of a line only in compatibility mode (this is a rather obscure
|
||
feature). For example, the code
|
||
|
||
@Example
|
||
.de xx
|
||
Hallo!
|
||
..
|
||
\fB.xx\fP
|
||
@endExample
|
||
|
||
prints @samp{Hallo!} in bold face if in compatibility mode, and
|
||
@samp{.xx} in bold face otherwise.
|
||
|
||
@cindex @code{\A}, incompatibilities with @acronym{AT&T} @code{troff}
|
||
@cindex @code{\|}, incompatibilities with @acronym{AT&T} @code{troff}
|
||
@cindex @code{\^}, incompatibilities with @acronym{AT&T} @code{troff}
|
||
@cindex @code{\&}, incompatibilities with @acronym{AT&T} @code{troff}
|
||
@cindex @code{\@{}, incompatibilities with @acronym{AT&T} @code{troff}
|
||
@cindex @code{\@}}, incompatibilities with @acronym{AT&T} @code{troff}
|
||
@cindex @code{\@key{SP}}, incompatibilities with @acronym{AT&T} @code{troff}
|
||
@cindex @code{\'}, incompatibilities with @acronym{AT&T} @code{troff}
|
||
@cindex @code{\`}, incompatibilities with @acronym{AT&T} @code{troff}
|
||
@cindex @code{\-}, incompatibilities with @acronym{AT&T} @code{troff}
|
||
@cindex @code{\_}, incompatibilities with @acronym{AT&T} @code{troff}
|
||
@cindex @code{\!}, incompatibilities with @acronym{AT&T} @code{troff}
|
||
@cindex @code{\%}, incompatibilities with @acronym{AT&T} @code{troff}
|
||
@cindex @code{\c}, incompatibilities with @acronym{AT&T} @code{troff}
|
||
GNU @code{troff} does not allow the use of the escape sequences
|
||
@code{\|}, @code{\^}, @code{\&}, @code{\@{}, @code{\@}},
|
||
@code{\@key{SP}}, @code{\'}, @code{\`}, @code{\-}, @code{\_}, @code{\!},
|
||
@code{\%}, and @code{\c} in names of strings, macros, diversions, number
|
||
registers, fonts or environments; @acronym{UNIX} @code{troff} does. The
|
||
@code{\A} escape sequence (@pxref{Identifiers}) may be helpful in
|
||
avoiding use of these escape sequences in names.
|
||
|
||
@cindex fractional point sizes
|
||
@cindex fractional type sizes
|
||
@cindex point sizes, fractional
|
||
@cindex type sizes, fractional
|
||
@cindex sizes, fractional
|
||
@cindex @code{ps} request, incompatibilities with @acronym{AT&T} @code{troff}
|
||
Fractional point sizes cause one noteworthy incompatibility. In
|
||
@acronym{UNIX} @code{troff} the @code{ps} request ignores scale
|
||
indicators and thus
|
||
|
||
@Example
|
||
.ps 10u
|
||
@endExample
|
||
|
||
@noindent
|
||
sets the point size to 10@w{ }points, whereas in GNU @code{troff} it
|
||
sets the point size to 10@w{ }scaled points. @xref{Fractional Type
|
||
Sizes}, for more information.
|
||
|
||
@cindex @code{bd} request, incompatibilities with @acronym{AT&T} @code{troff}
|
||
@cindex @code{cs} request, incompatibilities with @acronym{AT&T} @code{troff}
|
||
@cindex @code{tr} request, incompatibilities with @acronym{AT&T} @code{troff}
|
||
@cindex @code{fp} request, incompatibilities with @acronym{AT&T} @code{troff}
|
||
@cindex input characters and output glyphs, compatibility with @acronym{AT&T} @code{troff}
|
||
@cindex output glyphs, and input characters,compatibility with @acronym{AT&T} @code{troff}
|
||
@cindex characters, input, and output glyphs, compatibility with @acronym{AT&T} @code{troff}
|
||
@cindex glyphs, output, and input characters, compatibility with @acronym{AT&T} @code{troff}
|
||
In GNU @code{troff} there is a fundamental difference between
|
||
(unformatted) input characters and (formatted) output glyphs.
|
||
Everything that affects how a glyph is output is stored
|
||
with the glyph node; once a glyph node has been constructed it is
|
||
unaffected by any subsequent requests that are executed, including
|
||
@code{bd}, @code{cs}, @code{tkf}, @code{tr}, or @code{fp} requests.
|
||
Normally glyphs are constructed from input characters at the
|
||
moment immediately before the glyph is added to the current output
|
||
line. Macros, diversions and strings are all, in fact, the same type of
|
||
object; they contain lists of input characters and glyph nodes in
|
||
any combination. A glyph node does not behave like an input
|
||
character for the purposes of macro processing; it does not inherit any
|
||
of the special properties that the input character from which it was
|
||
constructed might have had. For example,
|
||
|
||
@Example
|
||
.di x
|
||
\\\\
|
||
.br
|
||
.di
|
||
.x
|
||
@endExample
|
||
|
||
@cindex printing backslash (@code{\\}, @code{\e}, @code{\E}, @code{\[rs]})
|
||
@cindex backslash, printing (@code{\\}, @code{\e}, @code{\E}, @code{\[rs]})
|
||
@cindex @code{\e}, incompatibilities with @acronym{AT&T} @code{troff}
|
||
@cindex @code{\!}, incompatibilities with @acronym{AT&T} @code{troff}
|
||
@cindex @code{\?}, incompatibilities with @acronym{AT&T} @code{troff}
|
||
@cindex transparent output, incompatibilities with @acronym{AT&T} @code{troff}
|
||
@cindex output, transparent, incompatibilities with @acronym{AT&T} @code{troff}
|
||
@noindent
|
||
prints @samp{\\} in GNU @code{troff}; each pair of input backslashes
|
||
is turned into one output backslash and the resulting output backslashes
|
||
are not interpreted as escape characters when they are reread.
|
||
@acronym{UNIX} @code{troff} would interpret them as escape characters
|
||
when they were reread and would end up printing one @samp{\}. The
|
||
correct way to obtain a printable backslash is to use the @code{\e}
|
||
escape sequence: This always prints a single instance of the current
|
||
escape character, regardless of whether or not it is used in a
|
||
diversion; it also works in both GNU @code{troff} and @acronym{UNIX}
|
||
@code{troff}.@footnote{To be completely independent of the current
|
||
escape character, use @code{\(rs} which represents a reverse solidus
|
||
(backslash) glyph.} To store, for some reason, an escape sequence in a
|
||
diversion that will be interpreted when the diversion is reread, either
|
||
use the traditional @code{\!} transparent output facility, or, if this
|
||
is unsuitable, the new @code{\?} escape sequence.
|
||
|
||
@xref{Diversions}, and @ref{Gtroff Internals}, for more information.
|
||
|
||
|
||
|
||
@c =====================================================================
|
||
@c =====================================================================
|
||
|
||
@node Preprocessors, Output Devices, gtroff Reference, Top
|
||
@chapter Preprocessors
|
||
@cindex preprocessors
|
||
|
||
This chapter describes all preprocessors that come with @code{groff} or
|
||
which are freely available.
|
||
|
||
@menu
|
||
* geqn::
|
||
* gtbl::
|
||
* gpic::
|
||
* ggrn::
|
||
* grap::
|
||
* grefer::
|
||
* gsoelim::
|
||
@end menu
|
||
|
||
|
||
@c =====================================================================
|
||
|
||
@node geqn, gtbl, Preprocessors, Preprocessors
|
||
@section @code{geqn}
|
||
@cindex @code{eqn}, the program
|
||
@cindex @code{geqn}, the program
|
||
|
||
@c XXX
|
||
|
||
@menu
|
||
* Invoking geqn::
|
||
@end menu
|
||
|
||
@c ---------------------------------------------------------------------
|
||
|
||
@node Invoking geqn, , geqn, geqn
|
||
@subsection Invoking @code{geqn}
|
||
@cindex invoking @code{geqn}
|
||
@cindex @code{geqn}, invoking
|
||
|
||
@c XXX
|
||
|
||
|
||
@c =====================================================================
|
||
|
||
@node gtbl, gpic, geqn, Preprocessors
|
||
@section @code{gtbl}
|
||
@cindex @code{tbl}, the program
|
||
@cindex @code{gtbl}, the program
|
||
|
||
@c XXX
|
||
|
||
@menu
|
||
* Invoking gtbl::
|
||
@end menu
|
||
|
||
@c ---------------------------------------------------------------------
|
||
|
||
@node Invoking gtbl, , gtbl, gtbl
|
||
@subsection Invoking @code{gtbl}
|
||
@cindex invoking @code{gtbl}
|
||
@cindex @code{gtbl}, invoking
|
||
|
||
@c XXX
|
||
|
||
|
||
@c =====================================================================
|
||
|
||
@node gpic, ggrn, gtbl, Preprocessors
|
||
@section @code{gpic}
|
||
@cindex @code{pic}, the program
|
||
@cindex @code{gpic}, the program
|
||
|
||
@c XXX
|
||
|
||
@menu
|
||
* Invoking gpic::
|
||
@end menu
|
||
|
||
@c ---------------------------------------------------------------------
|
||
|
||
@node Invoking gpic, , gpic, gpic
|
||
@subsection Invoking @code{gpic}
|
||
@cindex invoking @code{gpic}
|
||
@cindex @code{gpic}, invoking
|
||
|
||
@c XXX
|
||
|
||
|
||
@c =====================================================================
|
||
|
||
@node ggrn, grap, gpic, Preprocessors
|
||
@section @code{ggrn}
|
||
@cindex @code{grn}, the program
|
||
@cindex @code{ggrn}, the program
|
||
|
||
@c XXX
|
||
|
||
@menu
|
||
* Invoking ggrn::
|
||
@end menu
|
||
|
||
@c ---------------------------------------------------------------------
|
||
|
||
@node Invoking ggrn, , ggrn, ggrn
|
||
@subsection Invoking @code{ggrn}
|
||
@cindex invoking @code{ggrn}
|
||
@cindex @code{ggrn}, invoking
|
||
|
||
@c XXX
|
||
|
||
|
||
@c =====================================================================
|
||
|
||
@node grap, grefer, ggrn, Preprocessors
|
||
@section @code{grap}
|
||
@cindex @code{grap}, the program
|
||
|
||
A free implementation of @code{grap}, written by Ted Faber,
|
||
is available as an extra package from the following address:
|
||
|
||
@display
|
||
@url{http://www.lunabase.org/~faber/Vault/software/grap/}
|
||
@end display
|
||
|
||
|
||
@c =====================================================================
|
||
|
||
@node grefer, gsoelim, grap, Preprocessors
|
||
@section @code{grefer}
|
||
@cindex @code{refer}, the program
|
||
@cindex @code{grefer}, the program
|
||
|
||
@c XXX
|
||
|
||
@menu
|
||
* Invoking grefer::
|
||
@end menu
|
||
|
||
@c ---------------------------------------------------------------------
|
||
|
||
@node Invoking grefer, , grefer, grefer
|
||
@subsection Invoking @code{grefer}
|
||
@cindex invoking @code{grefer}
|
||
@cindex @code{grefer}, invoking
|
||
|
||
@c XXX
|
||
|
||
|
||
@c =====================================================================
|
||
|
||
@node gsoelim, , grefer, Preprocessors
|
||
@section @code{gsoelim}
|
||
@cindex @code{soelim}, the program
|
||
@cindex @code{gsoelim}, the program
|
||
|
||
@c XXX
|
||
|
||
@menu
|
||
* Invoking gsoelim::
|
||
@end menu
|
||
|
||
@c ---------------------------------------------------------------------
|
||
|
||
@node Invoking gsoelim, , gsoelim, gsoelim
|
||
@subsection Invoking @code{gsoelim}
|
||
@cindex invoking @code{gsoelim}
|
||
@cindex @code{gsoelim}, invoking
|
||
|
||
@c XXX
|
||
|
||
|
||
|
||
@c =====================================================================
|
||
@c =====================================================================
|
||
|
||
@node Output Devices, File formats, Preprocessors, Top
|
||
@chapter Output Devices
|
||
@cindex output devices
|
||
@cindex devices for output
|
||
|
||
@c XXX
|
||
|
||
@menu
|
||
* Special Characters::
|
||
* grotty::
|
||
* grops::
|
||
* grodvi::
|
||
* grolj4::
|
||
* grolbp::
|
||
* grohtml::
|
||
* gxditview::
|
||
@end menu
|
||
|
||
|
||
@c =====================================================================
|
||
|
||
@node Special Characters, grotty, Output Devices, Output Devices
|
||
@section Special Characters
|
||
@cindex special characters
|
||
@cindex characters, special
|
||
|
||
@c XXX
|
||
|
||
@xref{Font Files}.
|
||
|
||
|
||
@c =====================================================================
|
||
|
||
@node grotty, grops, Special Characters, Output Devices
|
||
@section @code{grotty}
|
||
@cindex @code{grotty}, the program
|
||
|
||
@c XXX
|
||
|
||
@menu
|
||
* Invoking grotty::
|
||
@end menu
|
||
|
||
@c ---------------------------------------------------------------------
|
||
|
||
@node Invoking grotty, , grotty, grotty
|
||
@subsection Invoking @code{grotty}
|
||
@cindex invoking @code{grotty}
|
||
@cindex @code{grotty}, invoking
|
||
|
||
@c XXX
|
||
|
||
@c The following is no longer true; fix and extend it.
|
||
|
||
@c @pindex less
|
||
@c @cindex Teletype
|
||
@c @cindex ISO 6249 SGR
|
||
@c @cindex terminal control sequences
|
||
@c @cindex control sequences, for terminals
|
||
@c For TTY output devices, underlining is done by emitting sequences of
|
||
@c @samp{_} and @samp{\b} (the backspace character) before the actual
|
||
@c character. Literally, this is printing an underline character, then
|
||
@c moving back one character position, and printing the actual character
|
||
@c at the same position as the underline character (similar to a
|
||
@c typewriter). Usually, a modern terminal can't interpret this (and the
|
||
@c original Teletype machines for which this sequence was appropriate are
|
||
@c no longer in use). You need a pager program like @code{less} which
|
||
@c translates this into ISO 6429 SGR sequences to control terminals.
|
||
|
||
|
||
@c =====================================================================
|
||
|
||
@node grops, grodvi, grotty, Output Devices
|
||
@section @code{grops}
|
||
@cindex @code{grops}, the program
|
||
|
||
@c XXX
|
||
|
||
@menu
|
||
* Invoking grops::
|
||
* Embedding PostScript::
|
||
@end menu
|
||
|
||
@c ---------------------------------------------------------------------
|
||
|
||
@node Invoking grops, Embedding PostScript, grops, grops
|
||
@subsection Invoking @code{grops}
|
||
@cindex invoking @code{grops}
|
||
@cindex @code{grops}, invoking
|
||
|
||
@c XXX
|
||
|
||
@c ---------------------------------------------------------------------
|
||
|
||
@node Embedding PostScript, , Invoking grops, grops
|
||
@subsection Embedding @sc{PostScript}
|
||
@cindex embedding PostScript
|
||
@cindex PostScript, embedding
|
||
|
||
@c XXX
|
||
|
||
|
||
@c =====================================================================
|
||
|
||
@node grodvi, grolj4, grops, Output Devices
|
||
@section @code{grodvi}
|
||
@cindex @code{grodvi}, the program
|
||
|
||
@c XXX
|
||
|
||
@menu
|
||
* Invoking grodvi::
|
||
@end menu
|
||
|
||
@c ---------------------------------------------------------------------
|
||
|
||
@node Invoking grodvi, , grodvi, grodvi
|
||
@subsection Invoking @code{grodvi}
|
||
@cindex invoking @code{grodvi}
|
||
@cindex @code{grodvi}, invoking
|
||
|
||
@c XXX
|
||
|
||
|
||
@c =====================================================================
|
||
|
||
@node grolj4, grolbp, grodvi, Output Devices
|
||
@section @code{grolj4}
|
||
@cindex @code{grolj4}, the program
|
||
|
||
@c XXX
|
||
|
||
@menu
|
||
* Invoking grolj4::
|
||
@end menu
|
||
|
||
@c ---------------------------------------------------------------------
|
||
|
||
@node Invoking grolj4, , grolj4, grolj4
|
||
@subsection Invoking @code{grolj4}
|
||
@cindex invoking @code{grolj4}
|
||
@cindex @code{grolj4}, invoking
|
||
|
||
@c XXX
|
||
|
||
|
||
@c =====================================================================
|
||
|
||
@node grolbp, grohtml, grolj4, Output Devices
|
||
@section @code{grolbp}
|
||
@cindex @code{grolbp}, the program
|
||
|
||
@c XXX
|
||
|
||
@menu
|
||
* Invoking grolbp::
|
||
@end menu
|
||
|
||
@c ---------------------------------------------------------------------
|
||
|
||
@node Invoking grolbp, , grolbp, grolbp
|
||
@subsection Invoking @code{grolbp}
|
||
@cindex invoking @code{grolbp}
|
||
@cindex @code{grolbp}, invoking
|
||
|
||
@c XXX
|
||
|
||
|
||
@c =====================================================================
|
||
|
||
@node grohtml, gxditview, grolbp, Output Devices
|
||
@section @code{grohtml}
|
||
@cindex @code{grohtml}, the program
|
||
|
||
@c XXX
|
||
|
||
@menu
|
||
* Invoking grohtml::
|
||
* grohtml specific registers and strings::
|
||
@end menu
|
||
|
||
@c ---------------------------------------------------------------------
|
||
|
||
@node Invoking grohtml, grohtml specific registers and strings, grohtml, grohtml
|
||
@subsection Invoking @code{grohtml}
|
||
@cindex invoking @code{grohtml}
|
||
@cindex @code{grohtml}, invoking
|
||
|
||
@c XXX
|
||
|
||
@c ---------------------------------------------------------------------
|
||
|
||
@node grohtml specific registers and strings, , Invoking grohtml, grohtml
|
||
@subsection @code{grohtml} specific registers and strings
|
||
@cindex registers specific to @code{grohtml}
|
||
@cindex strings specific to @code{grohtml}
|
||
@cindex @code{grohtml}, registers and strings
|
||
|
||
@DefmpregList {ps4html, grohtml}
|
||
@DefstrListEnd {www-image-template, grohtml}
|
||
The registers @code{ps4html} and @code{www-image-template} are defined
|
||
by the @code{pre-grohtml} preprocessor. @code{pre-grohtml} reads in
|
||
the @code{troff} input, marks up the inline equations and passes the
|
||
result firstly to
|
||
|
||
@Example
|
||
troff -Tps -rps4html=1 -dwww-image-template=@var{template}
|
||
@endExample
|
||
|
||
@noindent
|
||
and secondly to
|
||
|
||
@Example
|
||
troff -Thtml
|
||
@endExample
|
||
|
||
The PostScript device is used to create all the image files, and the
|
||
register @code{ps4html} enables the macro sets to ignore floating
|
||
keeps, footers, and headings.
|
||
|
||
The register @code{www-image-template} is set to the user specified
|
||
template name or the default name.
|
||
@endDefmpreg
|
||
|
||
|
||
@c =====================================================================
|
||
|
||
@node gxditview, , grohtml, Output Devices
|
||
@section @code{gxditview}
|
||
@cindex @code{gxditview}, the program
|
||
|
||
@c XXX
|
||
|
||
@menu
|
||
* Invoking gxditview::
|
||
@end menu
|
||
|
||
@c ---------------------------------------------------------------------
|
||
|
||
@node Invoking gxditview, , gxditview, gxditview
|
||
@subsection Invoking @code{gxditview}
|
||
@cindex invoking @code{gxditview}
|
||
@cindex @code{gxditview}, invoking
|
||
|
||
@c XXX
|
||
@c X11's xditview
|
||
|
||
|
||
|
||
@c =====================================================================
|
||
@c =====================================================================
|
||
|
||
@node File formats, Installation, Output Devices, Top
|
||
@chapter File formats
|
||
@cindex file formats
|
||
@cindex formats, file
|
||
|
||
All files read and written by @code{gtroff} are text files. The
|
||
following two sections describe their format.
|
||
|
||
@menu
|
||
* gtroff Output::
|
||
* Font Files::
|
||
@end menu
|
||
|
||
|
||
@c =====================================================================
|
||
|
||
@node gtroff Output, Font Files, File formats, File formats
|
||
@section @code{gtroff} Output
|
||
@cindex @code{gtroff}, output
|
||
@cindex output, @code{gtroff}
|
||
|
||
This section describes the intermediate output format of GNU
|
||
@code{troff}. This output is produced by a run of @code{gtroff}
|
||
before it is fed into a device postprocessor program.
|
||
|
||
As @code{groff} is a wrapper program around @code{gtroff} that
|
||
automatically calls a postprocessor, this output does not show up
|
||
normally. This is why it is called @dfn{intermediate}.
|
||
@code{groff} provides the option @option{-Z} to inhibit postprocessing,
|
||
such that the produced intermediate output is sent to standard output
|
||
just like calling @code{gtroff} manually.
|
||
|
||
@cindex troff output
|
||
@cindex output, troff
|
||
@cindex intermediate output
|
||
@cindex output, intermediate
|
||
Here, the term @dfn{troff output} describes what is output by
|
||
@code{gtroff}, while @dfn{intermediate output} refers to the language
|
||
that is accepted by the parser that prepares this output for the
|
||
postprocessors. This parser is smarter on whitespace and implements
|
||
obsolete elements for compatibility, otherwise both formats are the
|
||
same.@footnote{The parser and postprocessor for intermediate output
|
||
can be found in the file@*
|
||
@file{@var{groff-source-dir}/src/libs/libdriver/input.cc}.}
|
||
|
||
The main purpose of the intermediate output concept is to facilitate
|
||
the development of postprocessors by providing a common programming
|
||
interface for all devices. It has a language of its own that is
|
||
completely different from the @code{gtroff} language. While the
|
||
@code{gtroff} language is a high-level programming language for text
|
||
processing, the intermediate output language is a kind of low-level
|
||
assembler language by specifying all positions on the page for writing
|
||
and drawing.
|
||
|
||
The intermediate output produced by @code{gtroff} is fairly readable,
|
||
while output from @acronym{AT&T} @code{troff} is rather hard to
|
||
understand because of strange habits that are still supported, but not
|
||
used any longer by @code{gtroff}.
|
||
|
||
@menu
|
||
* Language Concepts::
|
||
* Command Reference::
|
||
* Intermediate Output Examples::
|
||
* Output Language Compatibility::
|
||
@end menu
|
||
|
||
@c ---------------------------------------------------------------------
|
||
|
||
@node Language Concepts, Command Reference, gtroff Output, gtroff Output
|
||
@subsection Language Concepts
|
||
|
||
During the run of @code{gtroff}, the input data is cracked down to the
|
||
information on what has to be printed at what position on the intended
|
||
device. So the language of the intermediate output format can be quite
|
||
small. Its only elements are commands with and without arguments.
|
||
In this section, the term @dfn{command} always refers to the intermediate
|
||
output language, and never to the @code{gtroff} language used for document
|
||
formatting. There are commands for positioning and text writing, for drawing, and
|
||
for device controlling.
|
||
|
||
@menu
|
||
* Separation::
|
||
* Argument Units::
|
||
* Document Parts::
|
||
@end menu
|
||
|
||
@node Separation, Argument Units, Language Concepts, Language Concepts
|
||
@subsubsection Separation
|
||
|
||
@acronym{AT&T} @code{troff} output has strange requirements on whitespace.
|
||
The @code{gtroff} output parser, however, is smart about whitespace by
|
||
making it maximally optional. The whitespace characters, i.e., the
|
||
tab, space, and newline characters, always have a syntactical meaning.
|
||
They are never printable because spacing within the output is always
|
||
done by positioning commands.
|
||
|
||
Any sequence of space or tab characters is treated as a single
|
||
@dfn{syntactical space}. It separates commands and arguments, but is
|
||
only required when there would occur a clashing between the command code
|
||
and the arguments without the space. Most often, this happens when
|
||
variable-length command names, arguments, argument lists, or command
|
||
clusters meet. Commands and arguments with a known, fixed length need
|
||
not be separated by syntactical space.
|
||
|
||
A line break is a syntactical element, too. Every command argument can be
|
||
followed by whitespace, a comment, or a newline character. Thus a
|
||
@dfn{syntactical line break} is defined to consist of optional
|
||
syntactical space that is optionally followed by a comment, and a
|
||
newline character.
|
||
|
||
The normal commands, those for positioning and text, consist of a
|
||
single letter taking a fixed number of arguments. For historical reasons,
|
||
the parser allows to stack such commands on the same line, but
|
||
fortunately, in @code{gtroff}'s intermediate output, every command with
|
||
at least one argument is followed by a line break, thus providing
|
||
excellent readability.
|
||
|
||
The other commands -- those for drawing and device controlling --
|
||
have a more complicated structure; some recognize long command names,
|
||
and some take a variable number of arguments. So all @samp{D} and
|
||
@samp{x} commands were designed to request a syntactical line break
|
||
after their last argument. Only one command, @w{@samp{x X}},
|
||
has an argument that can stretch over several lines; all other
|
||
commands must have all of their arguments on the same line as the
|
||
command, i.e., the arguments may not be splitted by a line break.
|
||
|
||
Empty lines (these are lines containing only space and/or a comment), can
|
||
occur everywhere. They are just ignored.
|
||
|
||
@node Argument Units, Document Parts, Separation, Language Concepts
|
||
@subsubsection Argument Units
|
||
|
||
Some commands take integer arguments that are assumed to represent
|
||
values in a measurement unit, but the letter for the corresponding
|
||
scale indicator is not written with the output command arguments.
|
||
Most commands assume the scale indicator @samp{u}, the basic unit of
|
||
the device, some use @samp{z}, the scaled point unit of the device,
|
||
while others, such as the color commands, expect plain integers.
|
||
|
||
Note that single characters can have the eighth bit set, as can the
|
||
names of fonts and special characters. The names of characters and
|
||
fonts can be of arbitrary length. A character that is to be printed
|
||
will always be in the current font.
|
||
|
||
A string argument is always terminated by the next whitespace
|
||
character (space, tab, or newline); an embedded @samp{#} character is
|
||
regarded as part of the argument, not as the beginning of a comment
|
||
command. An integer argument is already terminated by the next
|
||
non-digit character, which then is regarded as the first character of
|
||
the next argument or command.
|
||
|
||
@node Document Parts, , Argument Units, Language Concepts
|
||
@subsubsection Document Parts
|
||
|
||
A correct intermediate output document consists of two parts, the
|
||
@dfn{prologue} and the @dfn{body}.
|
||
|
||
The task of the prologue is to set the general device parameters
|
||
using three exactly specified commands. @code{gtroff}'s prologue
|
||
is guaranteed to consist of the following three lines (in that order):
|
||
|
||
@Example
|
||
x T @var{device}
|
||
x res @var{n} @var{h} @var{v}
|
||
x init
|
||
@endExample
|
||
|
||
@noindent
|
||
with the arguments set as outlined in @ref{Device Control Commands}.
|
||
Note that the parser for the intermediate output format is able to
|
||
swallow additional whitespace and comments as well even in the
|
||
prologue.
|
||
|
||
The body is the main section for processing the document data.
|
||
Syntactically, it is a sequence of any commands different from the
|
||
ones used in the prologue. Processing is terminated as soon as the
|
||
first @w{@samp{x stop}} command is encountered; the last line of any
|
||
@code{gtroff} intermediate output always contains such a command.
|
||
|
||
Semantically, the body is page oriented. A new page is started by a
|
||
@samp{p} command. Positioning, writing, and drawing commands are
|
||
always done within the current page, so they cannot occur before the
|
||
first @samp{p} command. Absolute positioning (by the @samp{H} and
|
||
@samp{V} commands) is done relative to the current page; all other
|
||
positioning is done relative to the current location within this page.
|
||
|
||
@c ---------------------------------------------------------------------
|
||
|
||
@node Command Reference, Intermediate Output Examples, Language Concepts, gtroff Output
|
||
@subsection Command Reference
|
||
|
||
This section describes all intermediate output commands, both from
|
||
@acronym{AT&T} @code{troff} as well as the @code{gtroff} extensions.
|
||
|
||
@menu
|
||
* Comment Command::
|
||
* Simple Commands::
|
||
* Graphics Commands::
|
||
* Device Control Commands::
|
||
* Obsolete Command::
|
||
@end menu
|
||
|
||
@node Comment Command, Simple Commands, Command Reference, Command Reference
|
||
@subsubsection Comment Command
|
||
|
||
@table @code
|
||
@item #@var{anything}@angles{end of line}
|
||
A comment. Ignore any characters from the @samp{#} character up to
|
||
the next newline character.
|
||
|
||
This command is the only possibility for commenting in the intermediate
|
||
output. Each comment can be preceded by arbitrary syntactical space;
|
||
every command can be terminated by a comment.
|
||
@end table
|
||
|
||
@node Simple Commands, Graphics Commands, Comment Command, Command Reference
|
||
@subsubsection Simple Commands
|
||
|
||
The commands in this subsection have a command code consisting of a
|
||
single character, taking a fixed number of arguments. Most of them
|
||
are commands for positioning and text writing. These commands are
|
||
smart about whitespace. Optionally, syntactical space can be inserted
|
||
before, after, and between the command letter and its arguments.
|
||
All of these commands are stackable, i.e., they can be preceded by
|
||
other simple commands or followed by arbitrary other commands on the
|
||
same line. A separating syntactical space is only necessary when two
|
||
integer arguments would clash or if the preceding argument ends with a
|
||
string argument.
|
||
|
||
@table @code
|
||
@ignore
|
||
.if (\n[@USE_ENV_STACK] == 1) \{\
|
||
.command {
|
||
Open a new environment by copying the actual device configuration data
|
||
to the environment stack.
|
||
.
|
||
The current environment is setup by the device specification and
|
||
manipulated by the setting commands.
|
||
.
|
||
.
|
||
.command }
|
||
Close the actual environment (opened by a preceding
|
||
.BR { \~command)
|
||
and restore the previous environment from the environment
|
||
stack as the actual device configuration data.
|
||
.
|
||
\} \" endif @USE_ENV_STACK
|
||
@end ignore
|
||
|
||
@item C @var{xxx}@angles{whitespace}
|
||
Print a special character named @var{xxx}. The trailing
|
||
syntactical space or line break is necessary to allow glyph names
|
||
of arbitrary length. The glyph is printed at the current print
|
||
position; the glyph's size is read from the font file. The print
|
||
position is not changed.
|
||
|
||
@item c @var{g}
|
||
Print glyph@w{ }@var{g} at the current print position;@footnote{@samp{c}
|
||
is actually a misnomer since it outputs a glyph.} the glyph's size is
|
||
read from the font file. The print position is not changed.
|
||
|
||
@item f @var{n}
|
||
Set font to font number@w{ }@var{n} (a non-negative integer).
|
||
|
||
@item H @var{n}
|
||
Move right to the absolute vertical position@w{ }@var{n} (a
|
||
non-negative integer in basic units @samp{u} relative to left edge
|
||
of current page.
|
||
|
||
@item h @var{n}
|
||
Move @var{n} (a non-negative integer) basic units @samp{u} horizontally
|
||
to the right. The original @acronym{UNIX} troff manual allows negative
|
||
values for @var{n} also, but @code{gtroff} doesn't use this.
|
||
|
||
@item m @var{color-scheme} @r{[}@var{component} @dots{}@r{]}
|
||
Set the color for text (glyphs), line drawing, and the outline of
|
||
graphic objects using different color schemes; the analoguous command
|
||
for the filling color of graphic objects is @samp{DF}. The color
|
||
components are specified as integer arguments between 0 and 65536.
|
||
The number of color components and their meaning vary for the
|
||
different color schemes. These commands are generated by
|
||
@code{gtroff}'s escape sequence @code{\m}. No position changing.
|
||
These commands are a @code{gtroff} extension.
|
||
|
||
@table @code
|
||
@item mc @var{cyan} @var{magenta} @var{yellow}
|
||
Set color using the CMY color scheme, having the 3@w{ }color components
|
||
@var{cyan}, @var{magenta}, and @var{yellow}.
|
||
|
||
@item md
|
||
Set color to the default color value (black in most cases).
|
||
No component arguments.
|
||
|
||
@item mg @var{gray}
|
||
Set color to the shade of gray given by the argument, an integer
|
||
between 0 (black) and 65536 (white).
|
||
|
||
@item mk @var{cyan} @var{magenta} @var{yellow} @var{black}
|
||
Set color using the CMYK color scheme, having the 4@w{ }color components
|
||
@var{cyan}, @var{magenta}, @var{yellow}, and @var{black}.
|
||
|
||
@item mr @var{red} @var{green} @var{blue}
|
||
Set color using the RGB color scheme, having the 3@w{ }color components
|
||
@var{red}, @var{green}, and @var{blue}.
|
||
|
||
@end table
|
||
|
||
@item N @var{n}
|
||
Print glyph with index@w{ }@var{n} (a non-negative integer) of the
|
||
current font. This command is a @code{gtroff} extension.
|
||
|
||
@item n @var{b} @var{a}
|
||
Inform the device about a line break, but no positioning is done by
|
||
this command. In @acronym{AT&T} @code{troff}, the integer arguments
|
||
@var{b} and@w{ }@var{a} informed about the space before and after the
|
||
current line to make the intermediate output more human readable
|
||
without performing any action. In @code{groff}, they are just ignored, but
|
||
they must be provided for compatibility reasons.
|
||
|
||
@item p @var{n}
|
||
Begin a new page in the outprint. The page number is set
|
||
to@w{ }@var{n}. This page is completely independent of pages formerly
|
||
processed even if those have the same page number. The vertical
|
||
position on the outprint is automatically set to@w{ }0. All
|
||
positioning, writing, and drawing is always done relative to a page,
|
||
so a @samp{p} command must be issued before any of these commands.
|
||
|
||
@item s @var{n}
|
||
Set point size to @var{n}@w{ }scaled points (this is unit @samp{z}).
|
||
@acronym{AT&T} @code{troff} used the unit points (@samp{p}) instead.
|
||
@xref{Output Language Compatibility}.
|
||
|
||
@item t @var{xxx}@angles{whitespace}
|
||
@itemx t @var{xxx} @var{dummy-arg}@angles{whitespace}
|
||
Print a word, i.e., a sequence of characters @var{xxx} representing
|
||
output glyphs which names are single characters, terminated by
|
||
a space character or a line break; an optional second integer argument
|
||
is ignored (this allows the formatter to generate an even number of
|
||
arguments). The first glyph should be printed at the current
|
||
position, the current horizontal position should then be increased by
|
||
the width of the first glyph, and so on for each glyph.
|
||
The widths of the glyphs are read from the font file, scaled for the
|
||
current point size, and rounded to a multiple of the horizontal
|
||
resolution. Special characters cannot be printed using this command
|
||
(use the @samp{C} command for special characters). This command is a
|
||
@code{gtroff} extension; it is only used for devices whose @file{DESC}
|
||
file contains the @code{tcommand} keyword (@pxref{DESC File Format}).
|
||
|
||
@item u @var{n} @var{xxx}@angles{whitespace}
|
||
Print word with track kerning. This is the same as the @samp{t}
|
||
command except that after printing each glyph, the current
|
||
horizontal position is increased by the sum of the width of that
|
||
glyph and@w{ }@var{n} (an integer in basic units @samp{u}).
|
||
This command is a @code{gtroff} extension; it is only used for devices
|
||
whose @file{DESC} file contains the @code{tcommand} keyword
|
||
(@pxref{DESC File Format}).
|
||
|
||
@item V @var{n}
|
||
Move down to the absolute vertical position@w{ }@var{n} (a
|
||
non-negative integer in basic units @samp{u}) relative to upper edge
|
||
of current page.
|
||
|
||
@item v @var{n}
|
||
Move @var{n}@w{ }basic units @samp{u} down (@var{n} is a non-negative
|
||
integer). The original @acronym{UNIX} troff manual allows negative
|
||
values for @var{n} also, but @code{gtroff} doesn't use this.
|
||
|
||
@item w
|
||
Informs about a paddable white space to increase readability.
|
||
The spacing itself must be performed explicitly by a move command.
|
||
|
||
@end table
|
||
|
||
@node Graphics Commands, Device Control Commands, Simple Commands, Command Reference
|
||
@subsubsection Graphics Commands
|
||
|
||
Each graphics or drawing command in the intermediate output starts
|
||
with the letter @samp{D}, followed by one or two characters that
|
||
specify a subcommand; this is followed by a fixed or variable number
|
||
of integer arguments that are separated by a single space character.
|
||
A @samp{D} command may not be followed by another command on the same line
|
||
(apart from a comment), so each @samp{D} command is terminated by a
|
||
syntactical line break.
|
||
|
||
@code{gtroff} output follows the classical spacing rules (no space
|
||
between command and subcommand, all arguments are preceded by a
|
||
single space character), but the parser allows optional space between
|
||
the command letters and makes the space before the first argument
|
||
optional. As usual, each space can be any sequence of tab and space
|
||
characters.
|
||
|
||
Some graphics commands can take a variable number of arguments.
|
||
In this case, they are integers representing a size measured in basic
|
||
units @samp{u}. The arguments called @var{h1}, @var{h2}, @dots{},
|
||
@var{hn} stand for horizontal distances where positive means right,
|
||
negative left. The arguments called @var{v1}, @var{v2}, @dots{},
|
||
@var{vn} stand for vertical distances where positive means down,
|
||
negative up. All these distances are offsets relative to the current
|
||
location.
|
||
|
||
Unless indicated otherwise, each graphics command directly corresponds
|
||
to a similar @code{gtroff} @code{\D} escape sequence. @xref{Drawing
|
||
Requests}.
|
||
|
||
Unknown @samp{D} commands are assumed to be device-specific.
|
||
Its arguments are parsed as strings; the whole information is then
|
||
sent to the postprocessor.
|
||
|
||
In the following command reference, the syntax element
|
||
@angles{line break} means a syntactical line break as defined above.
|
||
|
||
@table @code
|
||
@item D~ @var{h1} @var{v1} @var{h2} @var{v2} @dots{} @var{hn} @var{vn}@angles{line break}
|
||
Draw B-spline from current position to offset (@var{h1},@var{v1}),
|
||
then to offset (@var{h2},@var{v2}), if given, etc.@: up to
|
||
(@var{hn},@var{vn}). This command takes a variable number of argument
|
||
pairs; the current position is moved to the terminal point of the drawn
|
||
curve.
|
||
|
||
@item Da @var{h1} @var{v1} @var{h2} @var{v2}@angles{line break}
|
||
Draw arc from current position to
|
||
(@var{h1},@var{v1})@math{+}(@var{h2},@var{v2}) with center at
|
||
(@var{h1},@var{v1}); then move the current position to the final point
|
||
of the arc.
|
||
|
||
@item DC @var{d}@angles{line break}
|
||
@itemx DC @var{d} @var{dummy-arg}@angles{line break}
|
||
Draw a solid circle using the current fill color with
|
||
diameter@w{ }@var{d} (integer in basic units @samp{u}) with leftmost
|
||
point at the current position; then move the current position to the
|
||
rightmost point of the circle. An optional second integer argument is
|
||
ignored (this allows the formatter to generate an even number of
|
||
arguments). This command is a @code{gtroff} extension.
|
||
|
||
@item Dc @var{d}@angles{line break}
|
||
Draw circle line with diameter@w{ }@var{d} (integer in basic units
|
||
@samp{u}) with leftmost point at the current position; then move the
|
||
current position to the rightmost point of the circle.
|
||
|
||
@item DE @var{h} @var{v}@angles{line break}
|
||
Draw a solid ellipse in the current fill color with a horizontal
|
||
diameter of@w{ }@var{h} and a vertical diameter of@w{ }@var{v} (both
|
||
integers in basic units @samp{u}) with the leftmost point at the
|
||
current position; then move to the rightmost point of the ellipse.
|
||
This command is a @code{gtroff} extension.
|
||
|
||
@item De @var{h} @var{v}@angles{line break}
|
||
Draw an outlined ellipse with a horizontal diameter of@w{ }@var{h}
|
||
and a vertical diameter of@w{ }@var{v} (both integers in basic units
|
||
@samp{u}) with the leftmost point at current position; then move to
|
||
the rightmost point of the ellipse.
|
||
|
||
@item DF @var{color-scheme} @r{[}@var{component} @dots{}@r{]}@angles{line break}
|
||
Set fill color for solid drawing objects using different color
|
||
schemes; the analoguous command for setting the color of text, line
|
||
graphics, and the outline of graphic objects is @samp{m}.
|
||
The color components are specified as integer arguments between 0 and
|
||
65536. The number of color components and their meaning vary for the
|
||
different color schemes. These commands are generated by @code{gtroff}'s
|
||
escape sequences @w{@code{\D'F @dots{}'}} and @code{\M} (with no other
|
||
corresponding graphics commands). No position changing. This command
|
||
is a @code{gtroff} extension.
|
||
|
||
@table @code
|
||
@item DFc @var{cyan} @var{magenta} @var{yellow}@angles{line break}
|
||
Set fill color for solid drawing objects using the CMY color scheme,
|
||
having the 3@w{ }color components @var{cyan}, @var{magenta}, and
|
||
@var{yellow}.
|
||
|
||
@item DFd@angles{line break}
|
||
Set fill color for solid drawing objects to the default fill color value
|
||
(black in most cases). No component arguments.
|
||
|
||
@item DFg @var{gray}@angles{line break}
|
||
Set fill color for solid drawing objects to the shade of gray given by
|
||
the argument, an integer between 0 (black) and 65536 (white).
|
||
|
||
@item DFk @var{cyan} @var{magenta} @var{yellow} @var{black}@angles{line break}
|
||
Set fill color for solid drawing objects using the CMYK color scheme,
|
||
having the 4@w{ }color components @var{cyan}, @var{magenta}, @var{yellow},
|
||
and @var{black}.
|
||
|
||
@item DFr @var{red} @var{green} @var{blue}@angles{line break}
|
||
Set fill color for solid drawing objects using the RGB color scheme,
|
||
having the 3@w{ }color components @var{red}, @var{green}, and @var{blue}.
|
||
|
||
@end table
|
||
|
||
@item Df @var{n}@angles{line break}
|
||
The argument@w{ }@var{n} must be an integer in the range @math{-32767}
|
||
to 32767.
|
||
|
||
@table @asis
|
||
@item @math{0 @LE @var{n} @LE 1000}
|
||
Set the color for filling solid drawing objects to a shade of gray,
|
||
where 0 corresponds to solid white, 1000 (the default) to solid black,
|
||
and values in between to intermediate shades of gray; this is
|
||
obsoleted by command @samp{DFg}.
|
||
|
||
@item @math{@var{n} @LT 0} or @math{@var{n} @LT 1000}
|
||
Set the filling color to the color that is currently being used for
|
||
the text and the outline, see command @samp{m}. For example, the
|
||
command sequence
|
||
|
||
@Example
|
||
mg 0 0 65536
|
||
Df -1
|
||
@endExample
|
||
|
||
@noindent
|
||
sets all colors to blue.
|
||
|
||
@end table
|
||
|
||
@noindent
|
||
No position changing. This command is a @code{gtroff} extension.
|
||
|
||
@item Dl @var{h} @var{v}@angles{line break}
|
||
Draw line from current position to offset (@var{h},@var{v}) (integers
|
||
in basic units @samp{u}); then set current position to the end of the
|
||
drawn line.
|
||
|
||
@item Dp @var{h1} @var{v1} @var{h2} @var{v2} @dots{} @var{hn} @var{vn}@angles{line break}
|
||
Draw a polygon line from current position to offset (@var{h1},@var{v1}),
|
||
from there to offset (@var{h2},@var{v2}), etc.@: up to offset
|
||
(@var{hn},@var{vn}), and from there back to the starting position.
|
||
For historical reasons, the position is changed by adding the sum of
|
||
all arguments with odd index to the actual horizontal position and the
|
||
even ones to the vertical position. Although this doesn't make sense
|
||
it is kept for compatibility.
|
||
@ignore
|
||
As the polygon is closed, the end of drawing is the starting point, so
|
||
the position doesn't change.
|
||
@end ignore
|
||
This command is a @code{gtroff} extension.
|
||
|
||
@item Dp @var{h1} @var{v1} @var{h2} @var{v2} @dots{} @var{hn} @var{vn}@angles{line break}
|
||
Draw a solid polygon in the current fill color rather than an outlined
|
||
polygon, using the same arguments and positioning as the corresponding
|
||
@samp{Dp} command.
|
||
@ignore
|
||
No position changing.
|
||
@end ignore
|
||
This command is a @code{gtroff} extension.
|
||
|
||
@item Dt @var{n}@angles{line break}
|
||
Set the current line thickness to@w{ }@var{n} (an integer in basic
|
||
units @samp{u}) if @math{@var{n}>0}; if @math{@var{n}=0} select the
|
||
smallest available line thickness; if @math{@var{n}<0} set the line
|
||
thickness proportional to the point size (this is the default before
|
||
the first @samp{Dt} command was specified). For historical reasons,
|
||
the horizontal position is changed by adding the argument to the actual
|
||
horizontal position, while the vertical position is not changed.
|
||
Although this doesn't make sense it is kept for compatibility.
|
||
@ignore
|
||
No position changing.
|
||
@end ignore
|
||
This command is a @code{gtroff} extension.
|
||
|
||
@end table
|
||
|
||
@node Device Control Commands, Obsolete Command, Graphics Commands, Command Reference
|
||
@subsubsection Device Control Commands
|
||
|
||
Each device control command starts with the letter @samp{x},
|
||
followed by a space character (optional or arbitrary space or tab in
|
||
@code{gtroff}) and a subcommand letter or word; each argument (if any)
|
||
must be preceded by a syntactical space. All @samp{x} commands are
|
||
terminated by a syntactical line break; no device control command can
|
||
be followed by another command on the same line (except a comment).
|
||
|
||
The subcommand is basically a single letter, but to increase
|
||
readability, it can be written as a word, i.e., an arbitrary sequence
|
||
of characters terminated by the next tab, space, or newline character.
|
||
All characters of the subcommand word but the first are simply ignored.
|
||
For example, @code{gtroff} outputs the initialization command
|
||
@w{@samp{x i}} as @w{@samp{x init}} and the resolution command
|
||
@w{@samp{x r}} as @w{@samp{x res}}.
|
||
|
||
In the following, the syntax element @angles{line break} means a
|
||
syntactical line break (@pxref{Separation}).
|
||
|
||
@table @code
|
||
@item xF @var{name}@angles{line break}
|
||
The @samp{F} stands for @var{Filename}.
|
||
|
||
Use @var{name} as the intended name for the current file in error
|
||
reports. This is useful for remembering the original file name when
|
||
@code{gtroff} uses an internal piping mechanism. The input file is
|
||
not changed by this command. This command is a @code{gtroff} extension.
|
||
|
||
@item xf @var{n} @var{s}@angles{line break}
|
||
The @samp{f} stands for @var{font}.
|
||
|
||
Mount font position@w{ }@var{n} (a non-negative integer) with font
|
||
named@w{ }@var{s} (a text word). @xref{Font Positions}.
|
||
|
||
@item xH @var{n}@angles{line break}
|
||
The @samp{H} stands for @var{Height}.
|
||
|
||
Set glyph height to@w{ }@var{n} (a positive integer in scaled
|
||
points @samp{z}). @acronym{AT&T} @code{troff} uses the unit points
|
||
(@samp{p}) instead. @xref{Output Language Compatibility}.
|
||
|
||
@item xi@angles{line break}
|
||
The @samp{i} stands for @var{init}.
|
||
|
||
Initialize device. This is the third command of the prologue.
|
||
|
||
@item xp@angles{line break}
|
||
The @samp{p} stands for @var{pause}.
|
||
|
||
Parsed but ignored. The original @acronym{UNIX} troff manual writes
|
||
|
||
@display
|
||
pause device, can be restarted
|
||
@end display
|
||
|
||
@item xr @var{n} @var{h} @var{v}@angles{line break}
|
||
The @samp{r} stands for @var{resolution}.
|
||
|
||
Resolution is@w{ }@var{n}, while @var{h} is the minimal horizontal
|
||
motion, and @var{v} the minimal vertical motion possible with this
|
||
device; all arguments are positive integers in basic units @samp{u}
|
||
per inch. This is the second command of the prologue.
|
||
|
||
@item xS @var{n}@angles{line break}
|
||
The @samp{S} stands for @var{Slant}.
|
||
|
||
Set slant to@w{ }@var{n} (an integer in basic units @samp{u}).
|
||
|
||
@item xs@angles{line break}
|
||
The @samp{s} stands for @var{stop}.
|
||
|
||
Terminates the processing of the current file; issued as the last
|
||
command of any intermediate troff output.
|
||
|
||
@item xt@angles{line break}
|
||
The @samp{t} stands for @var{trailer}.
|
||
|
||
Generate trailer information, if any. In @var{gtroff}, this is
|
||
actually just ignored.
|
||
|
||
@item xT @var{xxx}@angles{line break}
|
||
The @samp{T} stands for @var{Typesetter}.
|
||
|
||
Set name of device to word @var{xxx}, a sequence of characters ended
|
||
by the next white space character. The possible device names coincide
|
||
with those from the @code{groff} @option{-T} option. This is the first
|
||
command of the prologue.
|
||
|
||
@item xu @var{n}@angles{line break}
|
||
The @samp{u} stands for @var{underline}.
|
||
|
||
Configure underlining of spaces. If @var{n} is@w{ }1, start
|
||
underlining of spaces; if @var{n} is@w{ }0, stop underlining of spaces.
|
||
This is needed for the @code{cu} request in nroff mode and is ignored
|
||
otherwise. This command is a @code{gtroff} extension.
|
||
|
||
@item xX @var{anything}@angles{line break}
|
||
The @samp{x} stands for @var{X-escape}.
|
||
|
||
Send string @var{anything} uninterpreted to the device. If the line
|
||
following this command starts with a @samp{+} character this line is
|
||
interpreted as a continuation line in the following sense. The
|
||
@samp{+} is ignored, but a newline character is sent instead to the
|
||
device, the rest of the line is sent uninterpreted. The same applies
|
||
to all following lines until the first character of a line is not a
|
||
@samp{+} character. This command is generated by the @code{gtroff}
|
||
escape sequence @code{\X}. The line-continuing feature is a
|
||
@code{gtroff} extension.
|
||
|
||
@end table
|
||
|
||
@node Obsolete Command, , Device Control Commands, Command Reference
|
||
@subsubsection Obsolete Command
|
||
In @acronym{AT&T} @code{troff} output, the writing of a single
|
||
glyph is mostly done by a very strange command that combines a
|
||
horizontal move and a single character giving the glyph name. It
|
||
doesn't have a command code, but is represented by a 3-character
|
||
argument consisting of exactly 2@w{ }digits and a character.
|
||
|
||
@table @asis
|
||
@item @var{dd}@var{g}
|
||
Move right @var{dd} (exactly two decimal digits) basic units @samp{u},
|
||
then print glyph@w{ }@var{g} (represented as a single character).
|
||
|
||
In @code{gtroff}, arbitrary syntactical space around and within this
|
||
command is allowed to be added. Only when a preceding command on the
|
||
same line ends with an argument of variable length a separating space
|
||
is obligatory. In @acronym{AT&T} @code{troff}, large clusters of these
|
||
and other commands are used, mostly without spaces; this made such output
|
||
almost unreadable.
|
||
|
||
@end table
|
||
|
||
For modern high-resolution devices, this command does not make sense
|
||
because the width of the glyphs can become much larger than two
|
||
decimal digits. In @code{gtroff}, this is only used for the devices
|
||
@code{X75}, @code{X75-12}, @code{X100}, and @code{X100-12}. For other
|
||
devices, the commands @samp{t} and @samp{u} provide a better
|
||
functionality.
|
||
|
||
@c ---------------------------------------------------------------------
|
||
|
||
@node Intermediate Output Examples, Output Language Compatibility, Command Reference, gtroff Output
|
||
@subsection Intermediate Output Examples
|
||
|
||
This section presents the intermediate output generated from the same
|
||
input for three different devices. The input is the sentence
|
||
@samp{hell world} fed into @code{gtroff} on the command line.
|
||
|
||
@table @asis
|
||
@item High-resolution device @code{ps}
|
||
|
||
This is the standard output of @code{gtroff} if no @option{-T} option
|
||
is given.
|
||
|
||
@example
|
||
@group
|
||
shell> echo "hell world" | groff -Z -T ps
|
||
|
||
x T ps
|
||
x res 72000 1 1
|
||
x init
|
||
@end group
|
||
p1
|
||
x font 5 TR
|
||
f5
|
||
s10000
|
||
V12000
|
||
H72000
|
||
thell
|
||
wh2500
|
||
tw
|
||
H96620
|
||
torld
|
||
n12000 0
|
||
@group
|
||
x trailer
|
||
V792000
|
||
x stop
|
||
@end group
|
||
@end example
|
||
|
||
@noindent
|
||
This output can be fed into @code{grops} to get its representation as
|
||
a PostScript file.
|
||
|
||
@item Low-resolution device @code{latin1}
|
||
|
||
This is similar to the high-resolution device except that the
|
||
positioning is done at a minor scale. Some comments (lines starting
|
||
with @samp{#}) were added for clarification; they were not generated
|
||
by the formatter.
|
||
|
||
@example
|
||
@group
|
||
shell> echo "hell world" | groff -Z -T latin1
|
||
|
||
# prologue
|
||
x T latin1
|
||
x res 240 24 40
|
||
x init
|
||
@end group
|
||
# begin a new page
|
||
p1
|
||
# font setup
|
||
x font 1 R
|
||
f1
|
||
s10
|
||
# initial positioning on the page
|
||
V40
|
||
H0
|
||
# write text `hell'
|
||
thell
|
||
# inform about space, and issue a horizontal jump
|
||
wh24
|
||
# write text `world'
|
||
tworld
|
||
# announce line break, but do nothing because ...
|
||
n40 0
|
||
@group
|
||
# ... the end of the document has been reached
|
||
x trailer
|
||
V2640
|
||
x stop
|
||
@end group
|
||
@end example
|
||
|
||
@noindent
|
||
This output can be fed into @code{grotty} to get a formatted text
|
||
document.
|
||
|
||
@item @acronym{AT&T} @code{troff} output
|
||
Since a computer monitor has a very low resolution compared to modern
|
||
printers the intermediate output for the X@w{ }Window devices can use
|
||
the jump-and-write command with its 2-digit displacements.
|
||
|
||
@example
|
||
@group
|
||
shell> echo "hell world" | groff -Z -T X100
|
||
|
||
x T X100
|
||
x res 100 1 1
|
||
x init
|
||
@end group
|
||
p1
|
||
x font 5 TR
|
||
f5
|
||
s10
|
||
V16
|
||
H100
|
||
# write text with jump-and-write commands
|
||
ch07e07l03lw06w11o07r05l03dh7
|
||
n16 0
|
||
@group
|
||
x trailer
|
||
V1100
|
||
x stop
|
||
@end group
|
||
@end example
|
||
|
||
@noindent
|
||
This output can be fed into @code{xditview} or @code{gxditview}
|
||
for displaying in@w{ }X.
|
||
|
||
Due to the obsolete jump-and-write command, the text clusters in the
|
||
@acronym{AT&T} @code{troff} output are almost unreadable.
|
||
|
||
@end table
|
||
|
||
@c ---------------------------------------------------------------------
|
||
|
||
@node Output Language Compatibility, , Intermediate Output Examples, gtroff Output
|
||
@subsection Output Language Compatibility
|
||
|
||
The intermediate output language of @acronym{AT&T} @code{troff}
|
||
was first documented in the @acronym{UNIX} troff manual, with later
|
||
additions documented in @cite{A Typesetter-indenpendent TROFF},
|
||
written by Brian Kernighan.
|
||
|
||
The @code{gtroff} intermediate output format is compatible with this
|
||
specification except for the following features.
|
||
|
||
@itemize @bullet
|
||
@item
|
||
The classical quasi device independence is not yet implemented.
|
||
|
||
@item
|
||
The old hardware was very different from what we use today. So the
|
||
@code{groff} devices are also fundamentally different from the ones in
|
||
@acronym{AT&T} @code{troff}. For example, the @acronym{AT&T}
|
||
PostScript device is called @code{post} and has a resolution of only
|
||
720 units per inch, suitable for printers 20 years ago, while
|
||
@code{groff}'s @code{ps} device has a resolution of
|
||
72000 units per inch. Maybe, by implementing some rescaling
|
||
mechanism similar to the classical quasi device independence,
|
||
@code{groff} could emulate @acronym{AT&T}'s @code{post} device.
|
||
|
||
@item
|
||
The B-spline command @samp{D~} is correctly handled by the
|
||
intermediate output parser, but the drawing routines aren't
|
||
implemented in some of the postprocessor programs.
|
||
|
||
@item
|
||
The argument of the commands @samp{s} and @w{@samp{x H}} has the
|
||
implicit unit scaled point @samp{z} in @code{gtroff}, while
|
||
@acronym{AT&T} @code{troff} has point (@samp{p}). This isn't an
|
||
incompatibility but a compatible extension, for both units coincide
|
||
for all devices without a @code{sizescale} parameter in the @file{DESC}
|
||
file, including all postprocessors from @acronym{AT&T} and
|
||
@code{groff}'s text devices. The few @code{groff} devices with
|
||
a @code{sizescale} parameter either do not exist for @acronym{AT&T}
|
||
@code{troff}, have a different name, or seem to have a different
|
||
resolution. So conflicts are very unlikely.
|
||
|
||
@item
|
||
The position changing after the commands @samp{Dp}, @samp{DP}, and
|
||
@samp{Dt} is illogical, but as old versions of @code{gtroff} used this
|
||
feature it is kept for compatibility reasons.
|
||
|
||
@ignore
|
||
Temporarily, there existed some confusion on the positioning after the
|
||
@samp{D} commands that are groff extensions. This has been clarified
|
||
by establishing the classical rule for all @code{groff} drawing commands:
|
||
|
||
@itemize
|
||
@item
|
||
The position after a graphic object has been drawn is at its end;
|
||
for circles and ellipses, the `end' is at the right side.
|
||
|
||
@item
|
||
From this, the positionings specified for the drawing commands above
|
||
follow quite naturally.
|
||
@end itemize
|
||
@end ignore
|
||
|
||
@end itemize
|
||
|
||
|
||
@c =====================================================================
|
||
|
||
@node Font Files, , gtroff Output, File formats
|
||
@section Font Files
|
||
@cindex font files
|
||
@cindex files, font
|
||
|
||
The @code{gtroff} font format is roughly a superset of the
|
||
@code{ditroff} font format (as used in later versions of @acronym{AT&T}
|
||
@code{troff} and its descendants). Unlike the @code{ditroff} font
|
||
format, there is no associated binary format; all files are text
|
||
files.@footnote{Plan@w{ }9 @code{troff} has also abandoned the binary
|
||
format.} The font files for device @var{name} are stored in a directory
|
||
@file{dev@var{name}}. There are two types of file: a device description
|
||
file called @file{DESC} and for each font@w{ }@var{f} a font file
|
||
called@w{ }@file{@var{f}}.
|
||
|
||
@menu
|
||
* DESC File Format::
|
||
* Font File Format::
|
||
@end menu
|
||
|
||
@c ---------------------------------------------------------------------
|
||
|
||
@node DESC File Format, Font File Format, Font Files, Font Files
|
||
@subsection @file{DESC} File Format
|
||
@cindex @file{DESC} file, format
|
||
@cindex font description file, format
|
||
@cindex format of font description file
|
||
@pindex DESC@r{ file format}
|
||
|
||
The @file{DESC} file can contain the following types of line. Except
|
||
for the @code{charset} keyword which must comes last (if at all), the
|
||
order of the lines is not important.
|
||
|
||
@table @code
|
||
@item res @var{n}
|
||
@kindex res
|
||
There are @var{n}@w{ }machine units per inch.
|
||
|
||
@item hor @var{n}
|
||
@kindex hor
|
||
The horizontal resolution is @var{n}@w{ }machine units.
|
||
|
||
@item vert @var{n}
|
||
@kindex vert
|
||
The vertical resolution is @var{n}@w{ }machine units.
|
||
|
||
@item sizescale @var{n}
|
||
@kindex sizescale
|
||
The scale factor for point sizes. By default this has a value of@w{ }1.
|
||
One scaled point is equal to one point/@var{n}. The arguments to the
|
||
@code{unitwidth} and @code{sizes} commands are given in scaled points.
|
||
@xref{Fractional Type Sizes}, for more information.
|
||
|
||
@item unitwidth @var{n}
|
||
@kindex unitwidth
|
||
Quantities in the font files are given in machine units for fonts whose
|
||
point size is @var{n}@w{ }scaled points.
|
||
|
||
@item prepro @var{program}
|
||
@kindex prepro
|
||
Call @var{program} as a preprocessor. Currently, this keyword is used
|
||
by @code{groff} with option @option{-Thtml} only.
|
||
|
||
@item postpro @var{program}
|
||
@kindex postpro
|
||
Call @var{program} as a postprocessor. For example, the line
|
||
|
||
@Example
|
||
postpro grodvi
|
||
@endExample
|
||
|
||
@noindent
|
||
in the file @file{devdvi/DESC} makes @code{groff} call @code{grodvi}
|
||
if option @option{-Tdvi} is given (and @option{-Z} isn't used).
|
||
|
||
@item tcommand
|
||
@kindex tcommand
|
||
This means that the postprocessor can handle the @samp{t} and @samp{u}
|
||
intermediate output commands.
|
||
|
||
@item sizes @var{s1} @var{s2} @dots{} @var{sn} 0
|
||
@kindex sizes
|
||
This means that the device has fonts at @var{s1}, @var{s2}, @dots{}
|
||
@var{sn} scaled points. The list of sizes must be terminated by@w{ }0
|
||
(this is digit zero). Each @var{si} can also be a range of sizes
|
||
@var{m}-@var{n}. The list can extend over more than one line.
|
||
|
||
@item styles @var{S1} @var{S2} @dots{} @var{Sm}
|
||
@kindex styles
|
||
The first @var{m}@w{ }font positions are associated with styles
|
||
@var{S1} @dots{} @var{Sm}.
|
||
|
||
@item fonts @var{n} @var{F1} @var{F2} @var{F3} @dots{} @var{Fn}
|
||
@kindex fonts
|
||
Fonts @var{F1} @dots{} @var{Fn} are mounted in the font positions
|
||
@var{m}+1, @dots{}, @var{m}+@var{n} where @var{m} is the number of
|
||
styles. This command may extend over more than one line. A font name
|
||
of@w{ }0 means no font is mounted on the corresponding font position.
|
||
|
||
@item family @var{fam}
|
||
@kindex family
|
||
The default font family is @var{fam}.
|
||
|
||
@item use_charnames_in_special
|
||
@kindex use_charnames_in_special
|
||
This command indicates that @code{gtroff} should encode special
|
||
characters inside special commands. Currently, this is only used
|
||
by the @acronym{HTML} output device. @xref{Postprocessor Access}.
|
||
|
||
@item papersize @var{string} @dots{}
|
||
@kindex papersize
|
||
Select a paper size. Valid values for @var{string} are the ISO paper
|
||
types @code{A0}-@code{A7}, @code{B0}-@code{B7}, @code{C0}-@code{C7},
|
||
@code{D0}-@code{D7}, @code{DL}, and the US paper types @code{letter},
|
||
@code{legal}, @code{tabloid}, @code{ledger}, @code{statement},
|
||
@code{executive}, @code{com10}, and @code{monarch}. Case is not significant
|
||
for @var{string} if it holds predefined paper types. Alternatively,
|
||
@var{string} can be a file name (e.g.@: @file{/etc/papersize}); if the file
|
||
can be opened, @code{groff} reads the first line and tests for the above
|
||
paper sizes. Finally, @var{string} can be a custom paper size in the format
|
||
@code{@var{length},@var{width}} (no spaces before and after the comma).
|
||
Both @var{length} and @var{width} must have a unit appended; valid values
|
||
are @samp{i} for inches, @samp{C} for centimeters, @samp{p} for points, and
|
||
@samp{P} for picas. Example: @code{12c,235p}. An argument which starts
|
||
with a digit is always treated as a custom paper format. @code{papersize}
|
||
sets both the vertical and horizontal dimension of the output medium.
|
||
|
||
More than one argument can be specified; @code{groff} scans from left to
|
||
right and uses the first valid paper specification.
|
||
|
||
@item pass_filenames
|
||
@kindex pass_filenames
|
||
Tell @code{gtroff} to emit the name of the source file currently
|
||
being processed. This is achieved by the intermediate output command
|
||
@samp{F}. Currently, this is only used by the @acronym{HTML} output
|
||
device.
|
||
|
||
@item print @var{program}
|
||
@kindex print
|
||
Use @var{program} as a spooler program for printing. If omitted,
|
||
the @option{-l} and @option{-L} options of @code{groff} are ignored.
|
||
|
||
@item charset
|
||
@kindex charset
|
||
This line and everything following in the file are ignored. It is
|
||
allowed for the sake of backwards compatibility.
|
||
@end table
|
||
|
||
The @code{res}, @code{unitwidth}, @code{fonts}, and @code{sizes} lines
|
||
are mandatory. Other commands are ignored by @code{gtroff} but may be
|
||
used by postprocessors to store arbitrary information about the device
|
||
in the @file{DESC} file.
|
||
|
||
@kindex spare1
|
||
@kindex spare2
|
||
@kindex biggestfont
|
||
Here a list of obsolete keywords which are recognized by @code{groff}
|
||
but completely ignored: @code{spare1}, @code{spare2},
|
||
@code{biggestfont}.
|
||
|
||
|
||
@c ---------------------------------------------------------------------
|
||
|
||
@node Font File Format, , DESC File Format, Font Files
|
||
@subsection Font File Format
|
||
@cindex font file, format
|
||
@cindex font description file, format
|
||
@cindex format of font files
|
||
@cindex format of font description files
|
||
|
||
A @dfn{font file}, also (and probably better) called a @dfn{font
|
||
description file}, has two sections. The first section is a sequence
|
||
of lines each containing a sequence of blank delimited words; the first
|
||
word in the line is a key, and subsequent words give a value for that
|
||
key.
|
||
|
||
@table @code
|
||
@item name @var{f}
|
||
@kindex name
|
||
The name of the font is@w{ }@var{f}.
|
||
|
||
@item spacewidth @var{n}
|
||
@kindex spacewidth
|
||
The normal width of a space is@w{ }@var{n}.
|
||
|
||
@item slant @var{n}
|
||
@kindex slant
|
||
The glyphs of the font have a slant of @var{n}@w{ }degrees.
|
||
(Positive means forward.)
|
||
|
||
@item ligatures @var{lig1} @var{lig2} @dots{} @var{lign} [0]
|
||
@kindex ligatures
|
||
Glyphs @var{lig1}, @var{lig2}, @dots{}, @var{lign} are ligatures;
|
||
possible ligatures are @samp{ff}, @samp{fi}, @samp{fl}, @samp{ffi} and
|
||
@samp{ffl}. For backwards compatibility, the list of ligatures may be
|
||
terminated with a@w{ }0. The list of ligatures may not extend over more
|
||
than one line.
|
||
|
||
@item special
|
||
@cindex special fonts
|
||
@kindex special
|
||
The font is @dfn{special}; this means that when a glyph is requested
|
||
that is not present in the current font, it is searched for in any
|
||
special fonts that are mounted.
|
||
@end table
|
||
|
||
Other commands are ignored by @code{gtroff} but may be used by
|
||
postprocessors to store arbitrary information about the font in the font
|
||
file.
|
||
|
||
@cindex comments in font files
|
||
@cindex font files, comments
|
||
@kindex #
|
||
The first section can contain comments which start with the @samp{#}
|
||
character and extend to the end of a line.
|
||
|
||
The second section contains one or two subsections. It must contain a
|
||
@code{charset} subsection and it may also contain a @code{kernpairs}
|
||
subsection. These subsections can appear in any order. Each
|
||
subsection starts with a word on a line by itself.
|
||
|
||
@kindex charset
|
||
The word @code{charset} starts the character set
|
||
subsection.@footnote{This keyword is misnamed since it starts a list
|
||
of ordered glyphs, not characters.} The @code{charset} line is
|
||
followed by a sequence of lines. Each line gives information for one
|
||
glyph. A line comprises a number of fields separated by blanks or
|
||
tabs. The format is
|
||
|
||
@quotation
|
||
@var{name} @var{metrics} @var{type} @var{code}
|
||
[@var{entity-name}] [@code{--} @var{comment}]
|
||
@end quotation
|
||
|
||
@cindex 8-bit input
|
||
@cindex input, 8-bit
|
||
@cindex accessing unnamed glyphs with @code{\N}
|
||
@cindex unnamed glyphs, accessing with @code{\N}
|
||
@cindex characters, unnamed, accessing with @code{\N}
|
||
@cindex glyphs, unnamed, accessing with @code{\N}
|
||
@kindex ---
|
||
@noindent
|
||
@var{name} identifies the glyph name@footnote{The distinction between
|
||
input, characters, and output, glyphs, is not clearly separated in the
|
||
terminology of @code{groff}; for example, the @code{char} request
|
||
should be called @code{glyph} since it defines an output entity.}:
|
||
If @var{name} is a single character@w{ }@var{c} then it corresponds
|
||
to the @code{gtroff} input character@w{ }@var{c}; if it is of the form
|
||
@samp{\@var{c}} where @var{c} is a single character, then it
|
||
corresponds to the special character @code{\[@var{c}]}; otherwise it
|
||
corresponds to the special character @samp{\[@var{name}]}. If it
|
||
is exactly two characters @var{xx} it can be entered as
|
||
@samp{\(@var{xx}}. Note that single-letter special characters can't
|
||
be accessed as @samp{\@var{c}}; the only exception is @samp{\-} which
|
||
is identical to @code{\[-]}.
|
||
|
||
@code{gtroff} supports 8-bit input characters; however some utilities
|
||
have difficulties with eight-bit characters. For this reason, there is
|
||
a convention that the entity name @samp{char@var{n}} is equivalent to
|
||
the single input character whose code is@w{ }@var{n}. For example,
|
||
@samp{char163} would be equivalent to the character with code@w{ }163
|
||
which is the pounds sterling sign in the @w{ISO Latin-1} character set.
|
||
You shouldn't use @samp{char@var{n}} entities in font description files
|
||
since they are related to input, not output. Otherwise, you get
|
||
hard-coded connections between input and output encoding which
|
||
prevents use of different (input) character sets.
|
||
|
||
The name @samp{---} is special and indicates that the glyph is
|
||
unnamed; such glyphs can only be used by means of the @code{\N}
|
||
escape sequence in @code{gtroff}.
|
||
|
||
The @var{type} field gives the glyph type:
|
||
|
||
@table @code
|
||
@item 1
|
||
the glyph has a descender, for example, @samp{p};
|
||
|
||
@item 2
|
||
the glyph has an ascender, for example, @samp{b};
|
||
|
||
@item 3
|
||
the glyph has both an ascender and a descender, for example, @samp{(}.
|
||
@end table
|
||
|
||
The @var{code} field gives the code which the postprocessor uses to
|
||
print the glyph. The glyph can also be input to @code{gtroff}
|
||
using this code by means of the @code{\N} escape sequence. @var{code}
|
||
can be any integer. If it starts with @samp{0} it is interpreted as
|
||
octal; if it starts with @samp{0x} or @samp{0X} it is interpreted as
|
||
hexadecimal. Note, however, that the @code{\N} escape sequence only
|
||
accepts a decimal integer.
|
||
|
||
The @var{entity-name} field gives an @acronym{ASCII} string
|
||
identifying the glyph which the postprocessor uses to print the
|
||
@code{gtroff} glyph @var{name}. This field is optional and has been
|
||
introduced so that the @acronym{HTML} device driver can encode its
|
||
character set. For example, the glyph @samp{\[Po]} is
|
||
represented as @samp{£} in @acronym{HTML} 4.0.
|
||
|
||
Anything on the line after the @var{entity-name} field resp.@: after
|
||
@samp{--} will be ignored.
|
||
|
||
The @var{metrics} field has the form:
|
||
|
||
@display
|
||
@group
|
||
@var{width}[@code{,}@var{height}[@code{,}@var{depth}[@code{,}@var{italic-correction}
|
||
[@code{,}@var{left-italic-correction}[@code{,}@var{subscript-correction}]]]]]
|
||
@end group
|
||
@end display
|
||
|
||
@noindent
|
||
There must not be any spaces between these subfields (it has been split
|
||
here into two lines for better legibility only). Missing subfields are
|
||
assumed to be@w{ }0. The subfields are all decimal integers. Since
|
||
there is no associated binary format, these values are not required to
|
||
fit into a variable of type @samp{char} as they are in @code{ditroff}.
|
||
The @var{width} subfield gives the width of the glyph. The @var{height}
|
||
subfield gives the height of the glyph (upwards is positive); if a
|
||
glyph does not extend above the baseline, it should be given a zero
|
||
height, rather than a negative height. The @var{depth} subfield gives
|
||
the depth of the glyph, that is, the distance from the baseline to the
|
||
lowest point below the baseline to which the glyph extends (downwards is
|
||
positive); if a glyph does not extend below the baseline, it should be
|
||
given a zero depth, rather than a negative depth. The
|
||
@var{italic-correction} subfield gives the amount of space that should
|
||
be added after the glyph when it is immediately to be followed by a
|
||
glyph from a roman font. The @var{left-italic-correction} subfield
|
||
gives the amount of space that should be added before the glyph when it
|
||
is immediately to be preceded by a glyph from a roman font. The
|
||
@var{subscript-correction} gives the amount of space that should be
|
||
added after a glyph before adding a subscript. This should be less
|
||
than the italic correction.
|
||
|
||
A line in the @code{charset} section can also have the format
|
||
|
||
@Example
|
||
@var{name} "
|
||
@endExample
|
||
|
||
@noindent
|
||
This indicates that @var{name} is just another name for the glyph
|
||
mentioned in the preceding line.
|
||
|
||
@kindex kernpairs
|
||
The word @code{kernpairs} starts the kernpairs section. This contains a
|
||
sequence of lines of the form:
|
||
|
||
@Example
|
||
@var{c1} @var{c2} @var{n}
|
||
@endExample
|
||
|
||
@noindent
|
||
This means that when glyph @var{c1} appears next to glyph @var{c2}
|
||
the space between them should be increased by@w{ }@var{n}. Most
|
||
entries in the kernpairs section have a negative value for@w{ }@var{n}.
|
||
|
||
|
||
|
||
@c =====================================================================
|
||
@c =====================================================================
|
||
|
||
@node Installation, Copying This Manual, File formats, Top
|
||
@chapter Installation
|
||
@cindex installation
|
||
|
||
@c XXX
|
||
|
||
|
||
|
||
@c =====================================================================
|
||
@c =====================================================================
|
||
|
||
@node Copying This Manual, Request Index, Installation, Top
|
||
@appendix Copying This Manual
|
||
|
||
@menu
|
||
* GNU Free Documentation License:: License for copying this manual.
|
||
@end menu
|
||
|
||
@include fdl.texi
|
||
|
||
|
||
|
||
@c =====================================================================
|
||
@c =====================================================================
|
||
|
||
@node Request Index, Escape Index, Copying This Manual, Top
|
||
@appendix Request Index
|
||
|
||
Requests appear without the leading control character (normally either
|
||
@samp{.} or @samp{'}).
|
||
|
||
@printindex rq
|
||
|
||
|
||
|
||
@c =====================================================================
|
||
@c =====================================================================
|
||
|
||
@node Escape Index, Operator Index, Request Index, Top
|
||
@appendix Escape Index
|
||
|
||
Any escape sequence @code{\@var{X}} with @var{X} not in the list below
|
||
emits a warning, printing glyph @var{X}.
|
||
|
||
@printindex es
|
||
|
||
|
||
|
||
@c =====================================================================
|
||
@c =====================================================================
|
||
|
||
@node Operator Index, Register Index, Escape Index, Top
|
||
@appendix Operator Index
|
||
|
||
@printindex op
|
||
|
||
|
||
|
||
@c =====================================================================
|
||
@c =====================================================================
|
||
|
||
@node Register Index, Macro Index, Operator Index, Top
|
||
@appendix Register Index
|
||
|
||
The macro package or program a specific register belongs to is appended in
|
||
brackets.
|
||
|
||
A register name@w{ }@code{x} consisting of exactly one character can be
|
||
accessed as @samp{\nx}. A register name @code{xx} consisting of exactly
|
||
two characters can be accessed as @samp{\n(xx}. Register names @code{xxx}
|
||
of any length can be accessed as @samp{\n[xxx]}.
|
||
|
||
@printindex vr
|
||
|
||
|
||
|
||
@c =====================================================================
|
||
@c =====================================================================
|
||
|
||
@node Macro Index, String Index, Register Index, Top
|
||
@appendix Macro Index
|
||
|
||
The macro package a specific macro belongs to is appended in brackets.
|
||
They appear without the leading control character (normally @samp{.}).
|
||
|
||
@printindex ma
|
||
|
||
|
||
|
||
@c =====================================================================
|
||
@c =====================================================================
|
||
|
||
@node String Index, Glyph Name Index, Macro Index, Top
|
||
@appendix String Index
|
||
|
||
The macro package or program a specific string belongs to is appended in
|
||
brackets.
|
||
|
||
A string name@w{ }@code{x} consisting of exactly one character can be
|
||
accessed as @samp{\*x}. A string name @code{xx} consisting of exactly
|
||
two characters can be accessed as @samp{\*(xx}. String names @code{xxx}
|
||
of any length can be accessed as @samp{\*[xxx]}.
|
||
|
||
|
||
@printindex st
|
||
|
||
|
||
|
||
@c =====================================================================
|
||
@c =====================================================================
|
||
|
||
@node Glyph Name Index, Font File Keyword Index, String Index, Top
|
||
@appendix Glyph Name Index
|
||
|
||
A glyph name @code{xx} consisting of exactly two characters can be
|
||
accessed as @samp{\(xx}. Glyph names @code{xxx} of any length can be
|
||
accessed as @samp{\[xxx]}.
|
||
|
||
@c XXX
|
||
|
||
|
||
|
||
@c =====================================================================
|
||
@c =====================================================================
|
||
|
||
@node Font File Keyword Index, Program and File Index, Glyph Name Index, Top
|
||
@appendix Font File Keyword Index
|
||
|
||
@printindex ky
|
||
|
||
|
||
|
||
@c =====================================================================
|
||
@c =====================================================================
|
||
|
||
@node Program and File Index, Concept Index, Font File Keyword Index, Top
|
||
@appendix Program and File Index
|
||
|
||
@printindex pg
|
||
|
||
|
||
|
||
@c =====================================================================
|
||
@c =====================================================================
|
||
|
||
@node Concept Index, , Program and File Index, Top
|
||
@appendix Concept Index
|
||
|
||
@printindex cp
|
||
|
||
|
||
@bye
|