15798 lines
500 KiB
Plaintext
15798 lines
500 KiB
Plaintext
\input texinfo @c -*-texinfo-*-
|
|
|
|
@c
|
|
@c Please convert this manual with `texi2dvi -e groff.texinfo' due to
|
|
@c problems in texinfo regarding expansion of user-defined macros.
|
|
@c
|
|
@c You need texinfo 4.6 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.)
|
|
|
|
@documentlanguage en
|
|
@documentencoding ISO-8859-1
|
|
|
|
|
|
@smallbook
|
|
|
|
@finalout
|
|
|
|
|
|
@copying
|
|
This manual documents GNU @code{troff} version 1.19.2.
|
|
|
|
Copyright @copyright{} 1994-2000, 2001, 2002, 2003, 2004, 2005
|
|
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{}.
|
|
|
|
@macro Var{arg}
|
|
@r{@slanted{\arg\}}
|
|
@end macro
|
|
|
|
|
|
@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 and above.
|
|
|
|
|
|
@c a dummy macro to assure the `@def...'
|
|
|
|
@macro defdummy
|
|
@c
|
|
@end macro
|
|
|
|
|
|
@c definition of requests
|
|
|
|
@macro Defreq{name, arg}
|
|
@deffn Request @t{.\name\} \arg\
|
|
@rqindex \name\
|
|
@c
|
|
@end macro
|
|
|
|
@macro DefreqList{name, arg}
|
|
@deffn Request @t{.\name\} \arg\
|
|
@defdummy
|
|
@rqindex \name\
|
|
@c
|
|
@end macro
|
|
|
|
@macro DefreqItem{name, arg}
|
|
@deffnx Request @t{.\name\} \arg\
|
|
@defdummy
|
|
@rqindex \name\
|
|
@c
|
|
@end macro
|
|
|
|
@macro DefreqListEnd{name, arg}
|
|
@deffnx Request @t{.\name\} \arg\
|
|
@rqindex \name\
|
|
@c
|
|
@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\
|
|
@c
|
|
@end macro
|
|
|
|
@macro DefescList{name, delimI, arg, delimII}
|
|
@deffn Escape @t{\name\\delimI\}@Var{\arg\}@t{\delimII\}
|
|
@defdummy
|
|
@esindex \name\
|
|
@c
|
|
@end macro
|
|
|
|
@macro DefescItem{name, delimI, arg, delimII}
|
|
@deffnx Escape @t{\name\\delimI\}@Var{\arg\}@t{\delimII\}
|
|
@defdummy
|
|
@esindex \name\
|
|
@c
|
|
@end macro
|
|
|
|
@macro DefescListEnd{name, delimI, arg, delimII}
|
|
@deffnx Escape @t{\name\\delimI\}@Var{\arg\}@t{\delimII\}
|
|
@esindex \name\
|
|
@c
|
|
@end macro
|
|
|
|
@macro endDefesc
|
|
@end deffn
|
|
@end macro
|
|
|
|
|
|
@c definition of registers
|
|
|
|
@macro Defreg{name}
|
|
@deffn Register @t{\\n[\name\]}
|
|
@vindex \name\
|
|
@c
|
|
@end macro
|
|
|
|
@macro DefregList{name}
|
|
@deffn Register @t{\\n[\name\]}
|
|
@defdummy
|
|
@vindex \name\
|
|
@c
|
|
@end macro
|
|
|
|
@macro DefregItem{name}
|
|
@deffnx Register @t{\\n[\name\]}
|
|
@defdummy
|
|
@vindex \name\
|
|
@c
|
|
@end macro
|
|
|
|
@macro DefregListEnd{name}
|
|
@deffnx Register @t{\\n[\name\]}
|
|
@vindex \name\
|
|
@c
|
|
@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{]}
|
|
@c
|
|
@end macro
|
|
|
|
@macro DefmpregList{name, package}
|
|
@deffn Register @t{\\n[\name\]}
|
|
@defdummy
|
|
@vindex \name\ @r{[}\package\@r{]}
|
|
@c
|
|
@end macro
|
|
|
|
@macro DefmpregItem{name, package}
|
|
@deffnx Register @t{\\n[\name\]}
|
|
@defdummy
|
|
@vindex \name\ @r{[}\package\@r{]}
|
|
@c
|
|
@end macro
|
|
|
|
@macro DefmpregListEnd{name, package}
|
|
@deffnx Register @t{\\n[\name\]}
|
|
@vindex \name\ @r{[}\package\@r{]}
|
|
@c
|
|
@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{]}
|
|
@c
|
|
@end macro
|
|
|
|
@macro DefmacList{name, arg, package}
|
|
@defmac @t{.\name\} \arg\
|
|
@defdummy
|
|
@maindex \name\ @r{[}\package\@r{]}
|
|
@c
|
|
@end macro
|
|
|
|
@macro DefmacItem{name, arg, package}
|
|
@defmacx @t{.\name\} \arg\
|
|
@defdummy
|
|
@maindex \name\ @r{[}\package\@r{]}
|
|
@c
|
|
@end macro
|
|
|
|
@macro DefmacListEnd{name, arg, package}
|
|
@defmacx @t{.\name\} \arg\
|
|
@maindex \name\ @r{[}\package\@r{]}
|
|
@c
|
|
@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{]}
|
|
@c
|
|
@end macro
|
|
|
|
@macro DefstrList{name, package}
|
|
@deffn String @t{\\*[\name\]}
|
|
@defdummy
|
|
@stindex \name\ @r{[}\package\@r{]}
|
|
@c
|
|
@end macro
|
|
|
|
@macro DefstrItem{name, package}
|
|
@deffnx String @t{\\*[\name\]}
|
|
@defdummy
|
|
@stindex \name\ @r{[}\package\@r{]}
|
|
@c
|
|
@end macro
|
|
|
|
@macro DefstrListEnd{name, package}
|
|
@deffnx String @t{\\*[\name\]}
|
|
@stindex \name\ @r{[}\package\@r{]}
|
|
@c
|
|
@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\Langlemacro{\angleleft}
|
|
\gdef\Ranglemacro{\angleright}
|
|
@end tex
|
|
|
|
@iftex
|
|
@set Langlemacro @Langlemacro
|
|
@set Ranglemacro @Ranglemacro
|
|
@end iftex
|
|
|
|
@ifnottex
|
|
@set Langlemacro <
|
|
@set Ranglemacro >
|
|
@end ifnottex
|
|
|
|
@macro angles{text}
|
|
@value{Langlemacro}@r{\text\}@value{Ranglemacro}
|
|
@end macro
|
|
|
|
|
|
@c a <= sign
|
|
@c
|
|
@c A value defined with @set is embedded into three group levels if
|
|
@c called with @value, so we need seven \aftergroup to put \le outside
|
|
@c of the groups -- this is necessary to get proper mathematical spacing.
|
|
|
|
@tex
|
|
\gdef\LEmacro{\aftergroup\aftergroup\aftergroup\aftergroup
|
|
\aftergroup\aftergroup\aftergroup\le}
|
|
@end tex
|
|
|
|
@iftex
|
|
@set LEmacro @LEmacro
|
|
@end iftex
|
|
|
|
@ifnottex
|
|
@set LEmacro <=
|
|
@end ifnottex
|
|
|
|
@macro LE
|
|
@value{LEmacro}
|
|
@end macro
|
|
|
|
|
|
@c We need special parentheses, brackets, and braces:
|
|
@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 . @{ and @} fail with info if used in a macro.
|
|
@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 and above.
|
|
|
|
@iftex
|
|
@set Lparenmacro @lparen
|
|
@set Rparenmacro @rparen
|
|
@set Lbrackmacro @lbrack
|
|
@set Rbrackmacro @rbrack
|
|
@set Lbracemacro @{
|
|
@set Rbracemacro @}
|
|
@end iftex
|
|
|
|
@ifnottex
|
|
@set Lparenmacro (
|
|
@set Rparenmacro )
|
|
@set Lbrackmacro [
|
|
@set Rbrackmacro ]
|
|
@set Lbracemacro @{
|
|
@set Rbracemacro @}
|
|
@end ifnottex
|
|
|
|
@macro Lparen{}
|
|
@value{Lparenmacro}
|
|
@end macro
|
|
@macro Rparen{}
|
|
@value{Rparenmacro}
|
|
@end macro
|
|
@macro Lbrack{}
|
|
@value{Lbrackmacro}
|
|
@end macro
|
|
@macro Rbrack{}
|
|
@value{Rbrackmacro}
|
|
@end macro
|
|
@macro Lbrace{}
|
|
@value{Lbracemacro}
|
|
@end macro
|
|
@macro Rbrace{}
|
|
@value{Rbracemacro}
|
|
@end macro
|
|
|
|
|
|
@c This suppresses the word `Appendix' in the appendix headers.
|
|
|
|
@tex
|
|
\gdef\gobblefirst#1#2{#2}
|
|
\gdef\putwordAppendix{\gobblefirst}
|
|
@end tex
|
|
|
|
|
|
@c We map some latin-1 characters to corresponding texinfo macros.
|
|
|
|
@tex
|
|
\global\catcode`^^e4\active % ä
|
|
\gdef^^e4{\"a}
|
|
\global\catcode`^^c4\active % Ä
|
|
\gdef^^c4{\"A}
|
|
\global\catcode`^^e9\active % é
|
|
\gdef^^e9{\'e}
|
|
\global\catcode`^^c9\active % É
|
|
\gdef^^c9{\'E}
|
|
\global\catcode`^^f6\active % ö
|
|
\gdef^^f6{\"o}
|
|
\global\catcode`^^d6\active % Ö
|
|
\gdef^^d6{\"O}
|
|
\global\catcode`^^fc\active % ü
|
|
\gdef^^fc{\"u}
|
|
\global\catcode`^^dc\active % Ü
|
|
\gdef^^dc{\"U}
|
|
\global\catcode`^^e6\active % æ
|
|
\gdef^^e6{\ae}
|
|
\global\catcode`^^c6\active % Æ
|
|
\gdef^^c6{\AE}
|
|
\global\catcode`^^df\active % ß
|
|
\gdef^^df{\ss}
|
|
@end tex
|
|
|
|
|
|
@c Note: We say `Roman numerals' but `roman font'.
|
|
|
|
|
|
@dircategory Typesetting
|
|
@direntry
|
|
* Groff: (groff). The GNU troff document formatting system.
|
|
@end direntry
|
|
|
|
|
|
@titlepage
|
|
@title groff
|
|
@subtitle The GNU implementation of @code{troff}
|
|
@subtitle Edition 1.19.2
|
|
@subtitle Summer 2005
|
|
@author by Trent A.@tie{}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
|
|
@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
|
|
|
|
@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@tie{}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.@tie{}E.@tie{}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.@tie{}F.@tie{}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æ 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@tie{}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@tie{}1989. The first version, @code{groff}@tie{}0.3.1, was released
|
|
June@tie{}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@tie{}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@tie{}1.04 around November@tie{}1991.
|
|
|
|
Beginning in@tie{}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.@tie{}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@tie{}Windows (for previewing), @TeX{}
|
|
DVI format, HP LaserJet@tie{}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@tie{}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::
|
|
* Paper Size::
|
|
* 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@tie{}@option{-}.
|
|
A filename of@tie{}@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. If specified
|
|
more than once, print the pipeline on @code{stderr} and execute 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, output, @acronym{ASCII}
|
|
@cindex @acronym{ASCII}, output encoding
|
|
@cindex output encoding, @acronym{ASCII}
|
|
For typewriter-like devices using the (7-bit) @acronym{ASCII}
|
|
character set.
|
|
|
|
@item latin1
|
|
@cindex encoding, output, @w{latin-1} (ISO @w{8859-1})
|
|
@cindex @w{latin-1} (ISO @w{8859-1}), output encoding
|
|
@cindex ISO @w{8859-1} (@w{latin-1}), output encoding
|
|
@cindex output encoding, @w{latin-1} (ISO @w{8859-1})
|
|
For typewriter-like devices that support the @w{Latin-1}
|
|
(ISO@tie{}@w{8859-1}) character set.
|
|
|
|
@item utf8
|
|
@cindex encoding, output, @w{utf-8}
|
|
@cindex @w{utf-8}, output encoding
|
|
@cindex output encoding, @w{utf-8}
|
|
For typewriter-like devices which use the Unicode (ISO@tie{}10646)
|
|
character set with @w{UTF-8} encoding.
|
|
|
|
@item cp1047
|
|
@cindex encoding, output, @acronym{EBCDIC}
|
|
@cindex @acronym{EBCDIC}, output encoding
|
|
@cindex output encoding, @acronym{EBCDIC}
|
|
@cindex encoding, output, cp1047
|
|
@cindex cp1047, output encoding
|
|
@cindex output encoding, cp1047
|
|
@cindex IBM cp1047 output encoding
|
|
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@tie{}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@tie{}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@tie{}@var{s}. @var{c}@tie{}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@tie{}@var{n}, @samp{@var{m}-@var{n}}
|
|
means print every page between @var{m} and@tie{}@var{n}, @samp{-@var{n}}
|
|
means print every page up to@tie{}@var{n}, @samp{@var{n}-} means print every
|
|
page beginning with@tie{}@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@tie{}@var{c} or @var{name} to the value@tie{}@var{n}.
|
|
@var{c}@tie{}must be a one-letter name; @var{name} can be of arbitrary
|
|
length. @var{n}@tie{}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 may be used to specify a directory to search for files.
|
|
It is passed to the following programs:
|
|
|
|
@itemize
|
|
@item
|
|
@code{gsoelim} (see @ref{gsoelim} for more details);
|
|
it also implies @code{groff}'s @option{-s} option.
|
|
|
|
@item
|
|
@code{gtroff}; it is used to search files named in the @code{psbb} and
|
|
@code{so} requests.
|
|
|
|
@item
|
|
@code{grops}; it is used to search files named in the
|
|
@w{@code{\X'ps: import}} and @w{@code{\X'ps: file}} escapes.
|
|
@end itemize
|
|
|
|
The current directory is always searched first. This option may be specified
|
|
more than once; the directories will be searched in the order specified. No
|
|
directory search is performed for files specified using an absolute path.
|
|
@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@tie{}@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.2/tmac
|
|
@endExample
|
|
|
|
@noindent
|
|
assuming that the version of @code{groff} is 1.18.2, 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, Paper Size, 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.2/font
|
|
@endExample
|
|
|
|
@noindent
|
|
assuming that the version of @code{groff} is 1.18.2, and the installation
|
|
prefix was @file{/usr/local}. It is possible to fine-tune those
|
|
directories during the installation process.
|
|
@end itemize
|
|
|
|
|
|
@c =====================================================================
|
|
|
|
@node Paper Size, Invocation Examples, Font Directories, Invoking groff
|
|
@section Paper Size
|
|
@cindex paper size
|
|
@cindex size, paper
|
|
@cindex landscape page orientation
|
|
@cindex orientation, landscape
|
|
@cindex page orientation, landscape
|
|
|
|
In groff, the page size for @code{gtroff} and for output devices are
|
|
handled separately. @xref{Page Layout}, for vertical manipulation of
|
|
the page size. @xref{Line Layout}, for horizontal changes.
|
|
|
|
A default paper size can be set in the device's @file{DESC} file. Most
|
|
output devices also have a command line option @option{-p} to override
|
|
the default paper size and option @option{-l} to use landscape
|
|
orientation. @xref{DESC File Format}, for a description of the
|
|
@code{papersize} keyword which takes the same argument as @option{-p}.
|
|
|
|
@pindex papersize.tmac
|
|
@pindex troffrc
|
|
A convenient shorthand to set a particular paper size for @code{gtroff}
|
|
is command line option @option{-dpaper=@var{size}}. This defines string
|
|
@code{paper} which is processed in file @file{papersize.tmac} (loaded in
|
|
the start-up file @file{troffrc} by default). Possible values for
|
|
@var{size} are the same as the predefined values for the
|
|
@code{papersize} keyword (but only in lowercase) except
|
|
@code{a7}-@code{d7}. An appended @samp{l} (ell) character denotes
|
|
landscape orientation.
|
|
|
|
For example, use the following for PS output on A4 paper in landscape
|
|
orientation:
|
|
|
|
@Example
|
|
groff -Tps -dpaper=a4l -P-pa4 -P-l -ms foo.ms > foo.ps
|
|
@endExample
|
|
|
|
Note that it is up to the particular macro package to respect default
|
|
page dimensions set in this way (most do).
|
|
|
|
|
|
@c =====================================================================
|
|
|
|
@node Invocation Examples, , Paper Size, 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@tie{}@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.@tie{}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@tie{}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 and Macro
|
|
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}@tie{}lines of blank
|
|
space. @var{N}@tie{}can be omitted (meaning skip a single line) or can
|
|
be of the form @var{N}i (for @var{N}@tie{}inches) or @var{N}c (for
|
|
@var{N}@tie{}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}@tie{}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@tie{}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@tie{}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}.
|
|
|
|
Different main macro packages can't be used at the same time; for example
|
|
|
|
@Example
|
|
groff -m man foo.man -m ms bar.doc
|
|
@endExample
|
|
|
|
@noindent
|
|
doesn't work. Note that option arguments are processed before non-option
|
|
arguments; the above (failing) sample is thus reordered to
|
|
|
|
@Example
|
|
groff -m man -m ms foo.man bar.doc
|
|
@endExample
|
|
|
|
@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::
|
|
* Optional man extensions::
|
|
@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} ] [ -rFT=@var{dist} ]
|
|
[ -rcR=1 ] [ -rC1 ] [ -rD1 ] [-rHY=@var{flags} ]
|
|
[ -rP@var{nnn} ] [ -rS@var{xx} ] [ -rX@var{nnn} ]
|
|
[ -rIN=@var{length} ] [ -rSN=@var{length} ] [ @var{files}@dots{} ]
|
|
@endExample
|
|
|
|
@noindent
|
|
It is possible to use @samp{-man} instead of @w{@samp{-m man}}.
|
|
|
|
@table @code
|
|
@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@tie{}1.
|
|
|
|
@item -rD1
|
|
Double-sided printing. Footers for even and odd pages are formatted
|
|
differently.
|
|
|
|
@item -rFT=@var{dist}
|
|
Set the position of the footer text to @var{dist}. If positive, the
|
|
distance is measured relative to the top of the page, otherwise it is
|
|
relative to the bottom. The default is @minus{}0.5@dmn{i}.
|
|
|
|
@item -rHY=@var{flags}
|
|
Set hyphenation flags. Possible values are 1@tie{}to hyphenate without
|
|
restrictions, 2@tie{} to not hyphenate the last word on a page,
|
|
4@tie{}to not hyphenate the last two characters of a word, and
|
|
8@tie{}to not hyphenate the first two characters of a word. These
|
|
values are additive; the default is@tie{}14.
|
|
|
|
@item -rIN=@var{length}
|
|
Set the body text indentation to @var{length}.
|
|
If not specified, the indentation defaults to 7@dmn{n}
|
|
(7@tie{}characters) in nroff mode and 7.2@dmn{n} otherwise.
|
|
For nroff, this value should always be an integer multiple of unit @samp{n}
|
|
to get consistent indentation.
|
|
|
|
@item -rLL=@var{length}
|
|
Set line length to @var{length}. If not specified, the line length
|
|
is set to respect any value set by a prior @samp{ll} request (which
|
|
@emph{must} be in effect when the @samp{TH} macro is invoked), if
|
|
this differs from the built-in default for the formatter; otherwise it
|
|
defaults to 78@dmn{n} in nroff mode (this is 78 characters per
|
|
line) and 6.5@dmn{i} in troff mode.@footnote{Note that the use of
|
|
a @samp{.ll @var{length}} request to initialize the line length, prior
|
|
to use of the @samp{TH} macro, is supported for backward compatibility
|
|
with some versions of the @code{man} program. @emph{Always} use the
|
|
@option{-rLL=@var{length}} option, or an equivalent @samp{.nr LL @var{length}}
|
|
request, in preference to such a @samp{.ll @var{length}} request.
|
|
In particular, note that in nroff mode, the request @samp{.ll 65n},
|
|
(with any @var{length} expression which evaluates equal to 65@dmn{n},
|
|
i.e., the formatter's default line length in nroff mode), will @emph{not}
|
|
set the line length to 65@dmn{n} (it will be adjusted to the @code{man}
|
|
macro package's default setting of 78@dmn{n}), whereas the use of the
|
|
@option{-rLL=65n} option, or the @samp{.nr LL 65n}
|
|
request @emph{will} establish a line length of 65@dmn{n}.}
|
|
|
|
@item -rLT=@var{length}
|
|
Set title length to @var{length}. If not specified, the title length
|
|
defaults to the line length.
|
|
|
|
@item -rP@var{nnn}
|
|
Page numbering starts with @var{nnn} rather than with@tie{}1.
|
|
|
|
@item -rS@var{xx}
|
|
Use @var{xx} (which can be 10, 11, or@tie{}12@dmn{pt}) as the base
|
|
document font size instead of the default value of@tie{}10@dmn{pt}.
|
|
|
|
@item -rSN=@var{length}
|
|
Set the indentation for sub-subheadings to @var{length}.
|
|
If not specified, the indentation defaults to 3@dmn{n}.
|
|
|
|
@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@tie{}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@tie{}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 (or the font specified by the string @code{HF}), one size larger than
|
|
the base document size. Additionally, the left margin and the indentation
|
|
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 (or the font
|
|
specified by the string @code{HF}), at the same size as the base document
|
|
size. Additionally, the left margin and the indentation 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 previous indentation value
|
|
specified with @code{TP}, @code{IP}, or @code{HP} (or to the default
|
|
value if none of them have been used yet).
|
|
|
|
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 the paragraph starts
|
|
at the same line (but indented), continuing on the following lines.
|
|
If the label is wider than the indentation 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 and the
|
|
indentation 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 it is set to the
|
|
previous indentation value specified with @code{TP}, @code{IP}, or
|
|
@code{HP} (or the default value if none of them have been used yet).
|
|
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@tie{}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 it is set to the previous indentation value
|
|
specified with @code{TP}, @code{IP}, or @code{HP} (or the default
|
|
value if non of them have been used yet). 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 it is set to the previous
|
|
indentation value specified with @code{TP}, @code{IP}, or @code{HP}
|
|
(or to the default value if none of them have been used yet). The
|
|
indentation value is then set to the default.
|
|
|
|
Calls to the @code{RS} macro can be nested.
|
|
@endDefmac
|
|
|
|
@Defmac {RE, [@Var{nnn}], man}
|
|
Move the left margin back to level @var{nnn}, restoring the previous left
|
|
margin. If no argument is given, it moves one level back. The first
|
|
level (i.e., no call to @code{RS} yet) has number@tie{}1, and each call
|
|
to @code{RS} increases the level by@tie{}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@tie{}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, without a space
|
|
between the arguments. Thus,
|
|
|
|
@Example
|
|
.BI this "word and" that
|
|
@endExample
|
|
|
|
@noindent
|
|
produces ``thisword andthat'' with ``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, without a space
|
|
between the arguments.
|
|
@endDefmac
|
|
|
|
@Defmac {RI, text, man}
|
|
Set its arguments alternately in roman and italic, without a space between
|
|
the arguments.
|
|
@endDefmac
|
|
|
|
@Defmac {IR, text, man}
|
|
Set its arguments alternately in italic and roman, without a space between
|
|
the arguments.
|
|
@endDefmac
|
|
|
|
@Defmac {BR, text, man}
|
|
Set its arguments alternately in bold face and roman, without a space
|
|
between the arguments.
|
|
@endDefmac
|
|
|
|
@Defmac {RB, text, man}
|
|
Set its arguments alternately in roman and bold face, without a space
|
|
between the arguments.
|
|
@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@dmn{n} in troff mode and 7@dmn{n} in
|
|
nroff mode 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@tie{}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@tie{}line in nroff mode, 0.4@dmn{v}@tie{}otherwise).
|
|
|
|
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}.
|
|
@endDefmac
|
|
|
|
The following two macros are included for
|
|
BSD compatibility.
|
|
|
|
@Defmac {AT, [@Var{system} [@Var{release}]], man}
|
|
@cindex @code{man}macros, BSD compatibility
|
|
Alter the footer for use with @acronym{AT&T} manpages.
|
|
This command exists only for compatibility; don't use it.
|
|
The first argument @var{system} can be:
|
|
|
|
@table @code
|
|
@item 3
|
|
7th Edition (the default)
|
|
|
|
@item 4
|
|
System III
|
|
|
|
@item 5
|
|
System V
|
|
@end table
|
|
|
|
An optional second argument @var{release} to @code{AT} specifies the
|
|
release number (such as ``System V Release 3'').
|
|
@endDefmac
|
|
|
|
@Defmac {UC, [@Var{version}], man}
|
|
@cindex @code{man}macros, BSD compatibility
|
|
Alters the footer for use with @acronym{BSD} manpages.
|
|
This command exists only for compatibility; don't use it.
|
|
The argument can be:
|
|
|
|
@table @code
|
|
@item 3
|
|
3rd Berkeley Distribution (the default)
|
|
|
|
@item 4
|
|
4th Berkeley Distribution
|
|
|
|
@item 5
|
|
4.2 Berkeley Distribution
|
|
|
|
@item 6
|
|
4.3 Berkeley Distribution
|
|
|
|
@item 7
|
|
4.4 Berkeley Distribution
|
|
@end table
|
|
@endDefmac
|
|
|
|
@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 {HF, man}
|
|
The typeface used for headings.
|
|
The default is @samp{B}.
|
|
@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, Optional man extensions, 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 Optional man extensions, , Preprocessors in man pages, man
|
|
@subsection Optional @file{man} extensions
|
|
|
|
@pindex man.local
|
|
Use the file @file{man.local} for local extensions
|
|
to the @code{man} macros or for style changes.
|
|
|
|
@unnumberedsubsubsec Custom headers and footers
|
|
@cindex @code{man} macros, custom headers and footers
|
|
|
|
In groff versions 1.18.2 and later, you can specify custom
|
|
headers and footers by redefining the following macros in
|
|
@file{man.local}.
|
|
|
|
@Defmac {PT, , man}
|
|
Control the content of the headers.
|
|
Normally, the header prints the command name
|
|
and section number on either side, and the
|
|
optional fifth argument to @code{TH} in the center.
|
|
@endDefmac
|
|
|
|
@Defmac {BT, , man}
|
|
Control the content of the footers.
|
|
Normally, the footer prints the page number
|
|
and the third and fourth arguments to @code{TH}.
|
|
|
|
Use the @code{FT} number register to specify the
|
|
footer position.
|
|
The default is @minus{}0.5@dmn{i}.
|
|
@endDefmac
|
|
|
|
@unnumberedsubsubsec Ultrix-specific man macros
|
|
@cindex Ultrix-specific @code{man} macros
|
|
@cindex @code{man} macros, Ultrix-specific
|
|
|
|
@pindex man.ultrix
|
|
The @code{groff} source distribution includes
|
|
a file named @file{man.ultrix}, containing
|
|
macros compatible with the Ultrix variant of
|
|
@code{man}.
|
|
Copy this file into @file{man.local} (or use the @code{mso} request to
|
|
load it) to enable the following macros.
|
|
|
|
@Defmac {CT, @Var{key}, man}
|
|
Print @samp{<CTRL/@var{key}>}.
|
|
@endDefmac
|
|
|
|
@Defmac {CW, , man}
|
|
Print subsequent text using the constant width (Courier) typeface.
|
|
@endDefmac
|
|
|
|
@Defmac {Ds, , man}
|
|
Begin a non-filled display.
|
|
@endDefmac
|
|
|
|
@Defmac {De, , man}
|
|
End a non-filled display started with @code{Ds}.
|
|
@endDefmac
|
|
|
|
@Defmac {EX, [@Var{indent}], man}
|
|
Begins a non-filled display
|
|
using the constant width (Courier) typeface.
|
|
Use the optional @var{indent} argument to
|
|
indent the display.
|
|
@endDefmac
|
|
|
|
@Defmac {EE, , man}
|
|
End a non-filled display started with @code{EX}.
|
|
@endDefmac
|
|
|
|
@Defmac {G, [@Var{text}], man}
|
|
Sets @var{text} in Helvetica.
|
|
If no text is present on the line where
|
|
the macro is called, then the text of the
|
|
next line appears in Helvetica.
|
|
@endDefmac
|
|
|
|
@Defmac {GL, [@Var{text}], man}
|
|
Sets @var{text} in Helvetica Oblique.
|
|
If no text is present on the line where
|
|
the macro is called, then the text of the
|
|
next line appears in Helvetica Oblique.
|
|
@endDefmac
|
|
|
|
@Defmac {HB, [@Var{text}], man}
|
|
Sets @var{text} in Helvetica Bold.
|
|
If no text is present on the line where
|
|
the macro is called, then all text up to
|
|
the next @code{HB} appears in Helvetica Bold.
|
|
@endDefmac
|
|
|
|
@Defmac {TB, [@Var{text}], man}
|
|
Identical to @code{HB}.
|
|
@endDefmac
|
|
|
|
@Defmac {MS, @Var{title} @Var{sect} [@Var{punct}], man}
|
|
Set a manpage reference in Ultrix format.
|
|
The @var{title} is in Courier instead of italic.
|
|
Optional punctuation follows the section number without
|
|
an intervening space.
|
|
@endDefmac
|
|
|
|
@Defmac {NT, [@code{C}] [@Var{title}], man}
|
|
Begin a note.
|
|
Print the optional @Var{title}, or the word ``Note'',
|
|
centered on the page.
|
|
Text following the macro makes up the body of the note,
|
|
and is indented on both sides.
|
|
If the first argument is @code{C}, the body of the
|
|
note is printed centered (the second argument replaces
|
|
the word ``Note'' if specified).
|
|
@endDefmac
|
|
|
|
@Defmac {NE, , man}
|
|
End a note begun with @code{NT}.
|
|
@endDefmac
|
|
|
|
@Defmac {PN, @Var{path} [@Var{punct}], man}
|
|
Set the path name in constant width (Courier),
|
|
followed by optional punctuation.
|
|
@endDefmac
|
|
|
|
@Defmac {Pn, [@Var{punct}] @Var{path} [@Var{punct}], man}
|
|
When called with two arguments, identical to @code{PN}.
|
|
When called with three arguments,
|
|
set the second argument in constant width (Courier),
|
|
bracketed by the first and third arguments in the current font.
|
|
@endDefmac
|
|
|
|
@Defmac {R, , man}
|
|
Switch to roman font and turn off any underlining in effect.
|
|
@endDefmac
|
|
|
|
@Defmac {RN, , man}
|
|
Print the string @samp{<RETURN>}.
|
|
@endDefmac
|
|
|
|
@Defmac {VS, [@code{4}], man}
|
|
Start printing a change bar in the margin if
|
|
the number @code{4} is specified.
|
|
Otherwise, this macro does nothing.
|
|
@endDefmac
|
|
|
|
@Defmac {VE, , man}
|
|
End printing the change bar begun by @code{VS}.
|
|
@endDefmac
|
|
|
|
@unnumberedsubsubsec Simple example
|
|
|
|
The following example @file{man.local} file
|
|
alters the @code{SH} macro to add some extra
|
|
vertical space before printing the heading.
|
|
Headings are printed in Helvetica Bold.
|
|
|
|
@Example
|
|
.\" Make the heading fonts Helvetica
|
|
.ds HF HB
|
|
.
|
|
.\" Put more whitespace in front of headings.
|
|
.rn SH SH-orig
|
|
.de SH
|
|
. if t .sp (u;\\n[PD]*2)
|
|
. SH-orig \\$*
|
|
..
|
|
@endExample
|
|
|
|
@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::
|
|
* Naming Conventions::
|
|
@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. If the value is larger than
|
|
or equal to 1000, divide it by 1000 to get a fractional point size.
|
|
For example, @samp{.nr PS 10250} sets the document's point size to
|
|
10.25@dmn{p}.
|
|
|
|
Effective: next paragraph.
|
|
|
|
Default: 10@dmn{p}.
|
|
@endDefmpreg
|
|
|
|
@Defmpreg {VS, ms}
|
|
Defines the space between lines (line height plus leading). If the
|
|
value is larger than or equal to 1000, divide it by 1000 to get a
|
|
fractional point size. Due to backwards compatibility, @code{VS} must
|
|
be smaller than 40000 (this is 40.0@dmn{p}).
|
|
|
|
Effective: next paragraph.
|
|
|
|
Default: 12@dmn{p}.
|
|
@endDefmpreg
|
|
|
|
@Defmpreg {PSINCR, ms}
|
|
Defines an increment in point size, which will be applied to section
|
|
headings at nesting levels below the value specified in @code{GROWPS}.
|
|
The value of @code{PSINCR} should be specified in points, with the
|
|
@dmn{p} scaling factor, and may include a fractional component; for
|
|
example, @w{@samp{.nr PSINCR 1.5p}} sets a point size increment of
|
|
1.5@dmn{p}.
|
|
|
|
Effective: next section heading.
|
|
|
|
Default: 1@dmn{p}.
|
|
@endDefmpreg
|
|
|
|
@Defmpreg {GROWPS, ms}
|
|
Defines the heading level below which the point size increment set by
|
|
@code{PSINCR} becomes effective. Section headings at and above the
|
|
level specified by @code{GROWPS} will be printed at the point size set
|
|
by @code{PS}; for each level below the value of @code{GROWPS}, the
|
|
point size will be increased in steps equal to the value of
|
|
@code{PSINCR}. Setting @code{GROWPS} to any value less than@tie{}2
|
|
disables the incremental heading size feature.
|
|
|
|
Effective: next section heading.
|
|
|
|
Default: 0.
|
|
@endDefmpreg
|
|
|
|
@Defmpreg {HY, ms}
|
|
Defines the hyphenation level. @code{HY} sets safely the value of the
|
|
low-level @code{hy} register. Setting the value of @code{HY}
|
|
to@tie{}0 is equivalent to using the @code{nh} request.
|
|
|
|
Effective: next paragraph.
|
|
|
|
Default: 14.
|
|
@endDefmpreg
|
|
|
|
@Defmpreg {FAM, ms}
|
|
Defines the font family used to typeset the document.
|
|
|
|
Effective: next paragraph.
|
|
|
|
Default: as defined in the output device.
|
|
@endDefmpreg
|
|
|
|
@unnumberedsubsubsec Paragraph Settings
|
|
|
|
@Defmpreg {PI, ms}
|
|
Defines the initial indentation of a (@code{PP} macro) 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 indentation on both sides of a quoted (@code{QP} macro)
|
|
paragraph.
|
|
|
|
Effective: next paragraph.
|
|
|
|
Default: 5@dmn{n}.
|
|
@endDefmpreg
|
|
|
|
@Defmpreg {PORPHANS, ms}
|
|
Defines the minimum number of initial lines of any paragraph which
|
|
should be kept together, to avoid orphan lines at the bottom of a
|
|
page. If a new paragraph is started close to the bottom of a page,
|
|
and there is insufficient space to accommodate @code{PORPHANS} lines
|
|
before an automatic page break, then the page break will be forced,
|
|
before the start of the paragraph.
|
|
|
|
Effective: next paragraph.
|
|
|
|
Default: 1.
|
|
@endDefmpreg
|
|
|
|
@Defmpreg {HORPHANS, ms}
|
|
Defines the minimum number of lines of the following paragraph which
|
|
should be kept together with any section heading introduced by the
|
|
@code{NH} or @code{SH} macros. If a section heading is placed close
|
|
to the bottom of a page, and there is insufficient space to
|
|
accommodate both the heading and at least @code{HORPHANS} lines of the
|
|
following paragraph, before an automatic page break, then the page
|
|
break will be forced before the heading.
|
|
|
|
Effective: next paragraph.
|
|
|
|
Default: 1.
|
|
@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 indentation.
|
|
|
|
Effective: next footnote.
|
|
|
|
Default: 2@dmn{n}.
|
|
@endDefmpreg
|
|
|
|
@Defmpreg {FF, ms}
|
|
The footnote format:
|
|
@table @code
|
|
@item 0
|
|
Print the footnote number as a superscript; indent the footnote
|
|
(default).
|
|
|
|
@item 1
|
|
Print the number followed by a period (like 1.@:) and indent the
|
|
footnote.
|
|
|
|
@item 2
|
|
Like 1, without an indentation.
|
|
|
|
@item 3
|
|
Like 1, but print the footnote number as a hanging paragraph.
|
|
@end table
|
|
|
|
Effective: next footnote.
|
|
|
|
Default: 0.
|
|
@endDefmpreg
|
|
|
|
@Defmpreg {FPS, ms}
|
|
Defines the footnote point size. If the value is larger than or equal
|
|
to 1000, divide it by 1000 to get a fractional point size.
|
|
|
|
Effective: next footnote.
|
|
|
|
Default: @math{@code{@\n[PS]} - 2}.
|
|
@endDefmpreg
|
|
|
|
@Defmpreg {FVS, ms}
|
|
Defines the footnote vertical spacing. If the value is larger than or
|
|
equal to 1000, divide it by 1000 to get a fractional point size.
|
|
|
|
Effective: next footnote.
|
|
|
|
Default: @math{@code{@\n[FPS]} + 2}.
|
|
@endDefmpreg
|
|
|
|
@Defmpreg {FPD, ms}
|
|
Defines the footnote paragraph spacing.
|
|
|
|
Effective: next footnote.
|
|
|
|
Default: @math{@code{@\n[PD]} / 2}.
|
|
@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@tie{}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@tie{}1 of the
|
|
document.
|
|
@endDefmac
|
|
|
|
@Defmac {P1, , ms}
|
|
(P-one) Prints the header on page@tie{}1. The default is to suppress
|
|
the header.
|
|
@endDefmac
|
|
|
|
@Defmac {DA, [@dots{}], ms}
|
|
(optional) Prints 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) Prints 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}
|
|
Ends 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::
|
|
* Indentation values 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.
|
|
|
|
@DefmacList {PP, , ms}
|
|
@DefmacListEnd {LP, , ms}
|
|
Sets a paragraph with an initial indentation.
|
|
@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
|
|
|
|
The @code{PORPHANS} register (@pxref{ms Document Control Registers})
|
|
operates in conjunction with each of these macros, to inhibit the
|
|
printing of orphan lines at the bottom of any page.
|
|
|
|
@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@tie{}@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
|
|
|
|
@DefstrList {SN, ms}
|
|
@DefstrItem {SN-DOT, ms}
|
|
@DefstrListEnd {SN-NO-DOT, ms}
|
|
After invocation of @code{NH}, the assigned section number is made
|
|
available in the strings @code{SN-DOT} (exactly as it appears in the
|
|
printed section heading) and @code{SN-NO-DOT} (with the final period
|
|
omitted). The string @code{SN} is also defined, as an alias for
|
|
@code{SN-DOT}; if preferred, you may redefine it as an alias for
|
|
@code{SN-NO-DOT}, by including the initialization
|
|
|
|
@Example
|
|
.ds SN-NO-DOT
|
|
.als SN SN-NO-DOT
|
|
@endExample
|
|
|
|
@noindent
|
|
@strong{before} your first use of @code{NH}, or simply
|
|
|
|
@Example
|
|
.als SN SN-NO-DOT
|
|
@endExample
|
|
|
|
@noindent
|
|
@strong{after} your first use of @code{NH}.
|
|
@endDefstr
|
|
|
|
@Defmac {SH, [@Var{match-level}], ms}
|
|
Unnumbered subheading.
|
|
|
|
The optional @var{match-level} argument is a GNU extension. It is a
|
|
number indicating the level of the heading, in a manner analogous to
|
|
the @var{curr-level} argument to @code{.NH}. Its purpose is to match
|
|
the point size, at which the heading is printed, to the size of a
|
|
numbered heading at the same level, when the @code{GROWPS} and
|
|
@code{PSINCR} heading size adjustment mechanism is in effect.
|
|
@xref{ms Document Control Registers}.
|
|
@endDefmac
|
|
|
|
The @code{HORPHANS} register (@pxref{ms Document Control Registers})
|
|
operates in conjunction with the @code{NH} and @code{SH} macros, to
|
|
inhibit the printing of orphaned section headings at the bottom of any
|
|
page.
|
|
|
|
@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}@tie{}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}@tie{}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}@tie{}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}@tie{}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
|
|
|
|
@DefstrList {@Lbrace{}, ms}
|
|
@DefstrListEnd {@Rbrace{}, ms}
|
|
Text enclosed with @code{\*@{} and @code{\*@}} is printed as a
|
|
superscript.
|
|
@endDefstr
|
|
|
|
@c ---------------------------------------------------------------------
|
|
|
|
@node Lists in ms, Indentation values 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 indentation for the body of each list
|
|
item; its default unit is @samp{n}. Once specified, the indentation
|
|
remains the same for all list items in the document until specified
|
|
again.
|
|
|
|
The @code{PORPHANS} register (@pxref{ms Document Control Registers})
|
|
operates in conjunction with the @code{IP} macro, to inhibit the
|
|
printing of orphaned list markers at the bottom of any page.
|
|
@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
|
|
|
|
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.
|
|
|
|
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
|
|
|
|
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
|
|
|
|
To set nested lists, use the @code{RS} and @code{RE} macros.
|
|
@xref{Indentation values 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 Indentation values in ms, Tabstops in ms, Lists in ms, ms Body Text
|
|
@subsubsection Indentation values
|
|
|
|
In many situations, you may need to indentation 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 indentation, allowing the indented
|
|
text to line up under hanging and indented paragraphs.
|
|
@endDefmac
|
|
|
|
@xref{ms Displays and Keeps}, for macros to indentation and turn off
|
|
filling.
|
|
|
|
@c ---------------------------------------------------------------------
|
|
|
|
@node Tabstops in ms, ms Displays and Keeps, Indentation values 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
|
|
|
|
@DefmacList {Ds, , ms}
|
|
@DefmacListEnd {De, , ms}
|
|
These two macros were formerly provided as aliases for @code{DS} and
|
|
@code{DE}, respectively. They have been removed, and should no longer
|
|
be used. The original implementations of @code{DS} and @code{DE} are
|
|
retained, and should be used instead. X11 documents which actually
|
|
use @code{Ds} and @code{De} always load a specific macro file from the
|
|
X11 distribution (@file{macros.t}) which provides proper definitions
|
|
for the two macros.
|
|
@endDefmac
|
|
|
|
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.
|
|
|
|
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@tie{}@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@tie{}@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}.
|
|
|
|
@cindex footnotes, and keeps [@code{ms}]
|
|
@cindex keeps, and footnotes [@code{ms}]
|
|
@cindex footnotes, and displays [@code{ms}]
|
|
@cindex displays, and footnotes [@code{ms}]
|
|
Footnotes can be safely used within keeps and displays, but you should
|
|
avoid using numbered footnotes within floating keeps. You can set a
|
|
second @code{\**} marker between a @code{\**} and its corresponding
|
|
@code{.FS} entry; as long as each @code{FS} macro occurs @emph{after}
|
|
the corresponding @code{\**} and the occurrences of @code{.FS} are in
|
|
the same order as the corresponding occurrences of @code{\**}.
|
|
|
|
@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
|
|
|
|
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 @emph{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@tie{}@strong{i} (Roman lowercase 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, and 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.
|
|
|
|
Note that groff's native support for accents is superior to the
|
|
following definitions.
|
|
@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 ß 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 æ ligature.
|
|
@endDefstr
|
|
|
|
@Defstr {Ae, ms}
|
|
Uppercase Æ ligature.
|
|
@endDefstr
|
|
|
|
@c ---------------------------------------------------------------------
|
|
|
|
@node Differences from AT&T ms, Naming Conventions, 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.
|
|
|
|
@itemize @bullet
|
|
@item
|
|
The internals of @code{groff -ms} differ from the internals of
|
|
@acronym{AT&T} @code{troff -ms}. Documents that depend upon
|
|
implementation details of @acronym{AT&T} @code{troff -ms} may not
|
|
format properly with @code{groff -ms}.
|
|
|
|
@item
|
|
The general error-handling policy of @code{groff -ms} is to detect and
|
|
report errors, rather than silently to ignore them.
|
|
|
|
@item
|
|
@code{groff -ms} does not work in compatibility mode (this is, with
|
|
the @option{-C} option).
|
|
|
|
@item
|
|
There is no special support for typewriter-like devices.
|
|
|
|
@item
|
|
@code{groff -ms} does not provide cut marks.
|
|
|
|
@item
|
|
Multiple line spacing is not supported. Use a larger vertical spacing
|
|
instead.
|
|
|
|
@item
|
|
Some @acronym{UNIX} @code{ms} documentation says that the @code{CW}
|
|
and @code{GW} number registers can be used to control the column width
|
|
and gutter width, respectively. These number registers are not used in
|
|
@code{groff -ms}.
|
|
|
|
@item
|
|
Macros that cause a reset (paragraphs, headings, etc.@:) may change
|
|
the indentation. Macros that change the indentation do not increment
|
|
or decrement the indentation, but rather set it absolutely. This can
|
|
cause problems for documents that define additional macros of their
|
|
own. The solution is to use not the @code{in} request but instead the
|
|
@code{RS} and @code{RE} macros.
|
|
|
|
@item
|
|
To make @code{groff -ms} use the default page offset (which also
|
|
specifies the left margin), the @code{PO} register must stay undefined
|
|
until the first @file{-ms} macro is evaluated. This implies that
|
|
@code{PO} should not be used early in the document, unless it is
|
|
changed also: Remember that accessing an undefined register
|
|
automatically defines it.
|
|
@end itemize
|
|
|
|
@Defmpreg {GS, ms}
|
|
This number register is set to@tie{}1 by the @code{groff -ms} macros,
|
|
but it is not used by the @code{AT&T} @code{troff -ms} macros.
|
|
Documents that need to determine whether they are being formatted with
|
|
@code{AT&T} @code{troff -ms} or @code{groff -ms} should use this
|
|
number register.
|
|
@endDefmpreg
|
|
|
|
@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 and Berkeley. 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
|
|
|
|
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
|
|
|
|
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 Naming Conventions, , Differences from AT&T ms, ms
|
|
@subsection Naming Conventions
|
|
@cindex @code{ms} macros, naming conventions
|
|
@cindex naming conventions, @code{ms} macros
|
|
|
|
The following conventions are used for names of macros, strings and
|
|
number registers. External names available to documents that use the
|
|
@code{groff -ms} macros contain only uppercase letters and digits.
|
|
|
|
Internally the macros are divided into modules; naming conventions are
|
|
as follows:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
Names used only within one module are of the form
|
|
@var{module}@code{*}@var{name}.
|
|
|
|
@item
|
|
Names used outside the module in which they are defined are of the
|
|
form @var{module}@code{@@}@var{name}.
|
|
|
|
@item
|
|
Names associated with a particular environment are of the form
|
|
@var{environment}@code{:}@var{name}; these are used only within the
|
|
@code{par} module.
|
|
|
|
@item
|
|
@var{name} does not have a module prefix.
|
|
|
|
@item
|
|
Constructed names used to implement arrays are of the form
|
|
@var{array}@code{!}@var{index}.
|
|
@end itemize
|
|
|
|
Thus the groff ms macros reserve the following names:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
Names containing the characters @code{*}, @code{@@},
|
|
and@tie{}@code{:}.
|
|
|
|
@item
|
|
Names containing only uppercase letters and digits.
|
|
@end itemize
|
|
|
|
|
|
@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::
|
|
* 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 and Symbols::
|
|
* 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, Measurements, 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::
|
|
* Input Conventions::
|
|
* Input Encodings::
|
|
@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, Input Conventions, 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, Input Encodings, Implicit Line Breaks, Text
|
|
@subsection 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@tie{}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 Input Encodings, , Input Conventions, Text
|
|
@subsection Input Encodings
|
|
|
|
Currently, the following input encodings are available.
|
|
|
|
@table @asis
|
|
@item cp1047
|
|
@cindex encoding, input, @acronym{EBCDIC}
|
|
@cindex @acronym{EBCDIC}, input encoding
|
|
@cindex input encoding, @acronym{EBCDIC}
|
|
@cindex encoding, input, cp1047
|
|
@cindex cp1047, input encoding
|
|
@cindex input encoding, cp1047
|
|
@cindex IBM cp1047 input encoding
|
|
@pindex cp1047.tmac
|
|
This input encoding works only on @acronym{EBCDIC} platforms (and vice
|
|
versa, the other input encodings don't work with @acronym{EBCDIC}); the
|
|
file @file{cp1047.tmac} is by default loaded at start-up.
|
|
|
|
@item latin-1
|
|
@cindex encoding, input, @w{latin-1} (ISO @w{8859-1})
|
|
@cindex @w{latin-1} (ISO @w{8859-1}), input encoding
|
|
@cindex ISO @w{8859-1} (@w{latin-1}), input encoding
|
|
@cindex input encoding, @w{latin-1} (ISO @w{8859-1})
|
|
@pindex latin1.tmac
|
|
This is the default input encoding on non-@acronym{EBCDIC} platforms;
|
|
the file @file{latin1.tmac} is loaded at start-up.
|
|
|
|
@item latin-2
|
|
@cindex encoding, input, @w{latin-2} (ISO @w{8859-2})
|
|
@cindex @w{latin-2} (ISO @w{8859-2}), input encoding
|
|
@cindex ISO @w{8859-2} (@w{latin-2}), input encoding
|
|
@cindex input encoding, @w{latin-2} (ISO @w{8859-2})
|
|
@pindex latin2.tmac
|
|
To use this encoding, either say @w{@samp{.mso latin2.tmac}} at the very
|
|
beginning of your document or use @samp{-mlatin2} as a command line
|
|
argument for @code{groff}.
|
|
|
|
@item latin-9 (latin-0)
|
|
@cindex encoding, input, @w{latin-9} (@w{latin-0}, ISO @w{8859-15})
|
|
@cindex @w{latin-9} (@w{latin-0}, ISO @w{8859-15}), input encoding
|
|
@cindex ISO @w{8859-15} (@w{latin-9}, @w{latin-0}), input encoding
|
|
@cindex input encoding, @w{latin-9} (@w{latin-9}, ISO @w{8859-15})
|
|
@pindex latin9.tmac
|
|
This encoding is intended (at least in Europe) to replace @w{latin-1}
|
|
encoding. The main difference to @w{latin-1} is that @w{latin-9}
|
|
contains the Euro character. To use this encoding, either say
|
|
@w{@samp{.mso latin9.tmac}} at the very beginning of your document or
|
|
use @samp{-mlatin9} as a command line argument for @code{groff}.
|
|
@end table
|
|
|
|
Note that it can happen that some input encoding characters are not
|
|
available for a particular output device. For example, saying
|
|
|
|
@Example
|
|
groff -Tlatin1 -mlatin9 ...
|
|
@endExample
|
|
|
|
@noindent
|
|
will fail if you use the Euro character in the input. Usually, this
|
|
limitation is present only for devices which have a limited set of
|
|
output glyphs (e.g.@: @option{-Tascii} and @option{-Tlatin1}); for other
|
|
devices it is usually sufficient to install proper fonts which contain
|
|
the necessary glyphs.
|
|
|
|
@pindex freeeuro.pfa
|
|
@pindex ec.tmac
|
|
Due to the importance of the Euro glyph in Europe, the groff package now
|
|
comes with a @sc{PostScript} font called @file{freeeuro.pfa} which
|
|
provides various glyph shapes for the Euro. With other words,
|
|
@w{latin-9} encoding is supported for the @option{-Tps} device out of
|
|
the box (@w{latin-2} isn't).
|
|
|
|
By its very nature, @option{-Tutf8} supports all input encodings;
|
|
@option{-Tdvi} has support for both @w{latin-2} and @w{latin-9} if the
|
|
command line @option{-mec} is used also to load the file @file{ec.tmac}
|
|
(which flips to the EC fonts).
|
|
|
|
|
|
@c =====================================================================
|
|
|
|
@node Measurements, Expressions, Text, 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@tie{}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@tie{}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@tie{}points to an inch.
|
|
|
|
@item P
|
|
@cindex pica unit (@code{P})
|
|
@cindex @code{P} unit
|
|
@cindex unit, @code{P}
|
|
Pica. Another typesetting measurement. 6@tie{}Picas to an inch (and
|
|
12@tie{}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@tie{}@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@tie{}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@tie{}240@dmn{u}, and 1@dmn{m}
|
|
equals@tie{}10@dmn{p} (thus 1@dmn{m} equals@tie{}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@tie{}@code{z} now contains@tie{}5.
|
|
|
|
@item
|
|
@cindex scaling operator
|
|
@cindex operator, scaling
|
|
Scaling: @code{(@var{c};@var{e})}. Evaluate@tie{}@var{e} using@tie{}@var{c}
|
|
as the default scaling indicator. If @var{c} is missing, ignore scaling
|
|
indicators in the evaluation of@tie{}@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@tie{}@code{-}
|
|
@cindex @code{in} request, using @code{+} and@tie{}@code{-}
|
|
@cindex @code{ll} request, using @code{+} and@tie{}@code{-}
|
|
@cindex @code{lt} request, using @code{+} and@tie{}@code{-}
|
|
@cindex @code{nm} request, using @code{+} and@tie{}@code{-}
|
|
@cindex @code{nr} request, using @code{+} and@tie{}@code{-}
|
|
@cindex @code{pl} request, using @code{+} and@tie{}@code{-}
|
|
@cindex @code{pn} request, using @code{+} and@tie{}@code{-}
|
|
@cindex @code{po} request, using @code{+} and@tie{}@code{-}
|
|
@cindex @code{ps} request, using @code{+} and@tie{}@code{-}
|
|
@cindex @code{pvs} request, using @code{+} and@tie{}@code{-}
|
|
@cindex @code{rt} request, using @code{+} and@tie{}@code{-}
|
|
@cindex @code{ti} request, using @code{+} and@tie{}@code{-}
|
|
@cindex @code{\H}, using @code{+} and@tie{}@code{-}
|
|
@cindex @code{\R}, using @code{+} and@tie{}@code{-}
|
|
@cindex @code{\s}, using @code{+} and@tie{}@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@tie{}1 if @var{anything} is a valid numeric expression;
|
|
or@tie{}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 and Macro 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}@tie{}@code{0x08} or
|
|
@acronym{EBCDIC}@tie{}@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@tie{}1 or@tie{}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@tie{}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@tie{}@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@tie{}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 and Macro Arguments::
|
|
@end menu
|
|
|
|
@node Request and Macro Arguments, , Requests, Requests
|
|
@subsubsection Request and Macro Arguments
|
|
@cindex request arguments
|
|
@cindex macro arguments
|
|
@cindex arguments to requests and macros
|
|
|
|
Arguments to requests and macros are processed much like the shell:
|
|
The line is split into arguments according to
|
|
spaces.@footnote{Plan@tie{}9's @code{troff} implementation also allows
|
|
tabs for argument separation -- @code{gtroff} intentionally doesn't
|
|
support this.}
|
|
|
|
@cindex spaces, in a macro argument
|
|
An argument to a macro which is intended to contain spaces can either be
|
|
enclosed in double quotes, or have the spaces @dfn{escaped} with
|
|
backslashes. This is @emph{not} true for requests.
|
|
|
|
Here are a few examples for a hypothetical macro @code{uh}:
|
|
|
|
@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 basically in the same manner.
|
|
|
|
@xref{Writing Macros}, and @ref{Request and Macro 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é 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, [@Var{end}]}
|
|
Ignore all input until @code{gtroff} encounters the macro named
|
|
@code{.}@var{end} on a line by itself (or @code{..} if @var{end} 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{+}value, '}
|
|
@DefescListEnd {\\R, ', ident @t{-}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@tie{}@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@tie{}@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,@tie{}@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,@tie{}@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,@tie{}@enddots{}
|
|
|
|
@item i
|
|
Lower-case Roman numerals: 0, i, ii, iii, iv,@tie{}@enddots{}
|
|
|
|
@item A
|
|
Upper-case letters: 0, A, B, C, @dots{},@tie{}Z, AA, AB,@tie{}@enddots{}
|
|
|
|
@item a
|
|
Lower-case letters: 0, a, b, c, @dots{},@tie{}z, aa, ab,@tie{}@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@tie{}@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
|
|
@ref{Register Index}.
|
|
|
|
@table @code
|
|
@item \n[.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 \n[.H]
|
|
@cindex horizontal resolution register (@code{.H})
|
|
@cindex resolution, horizontal, register (@code{.H})
|
|
@vindex .H
|
|
Horizontal resolution in basic units.
|
|
|
|
@item \n[.U]
|
|
@cindex safer mode
|
|
@cindex mode, safer
|
|
@cindex unsafe mode
|
|
@cindex mode, unsafe
|
|
If @code{gtroff} is called with the @option{-U} command line option, the
|
|
number register @code{.U} is set to@tie{}1, and zero otherwise.
|
|
@xref{Groff Options}.
|
|
|
|
@item \n[.V]
|
|
@cindex vertical resolution register (@code{.V})
|
|
@cindex resolution, vertical, register (@code{.V})
|
|
@vindex .V
|
|
Vertical resolution in basic units.
|
|
|
|
@item \n[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@tie{}0
|
|
to@tie{}59, but can be up to@tie{}61 to allow for leap seconds. Initialized
|
|
at start-up of @code{gtroff}.
|
|
|
|
@item \n[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@tie{}0 to@tie{}59.
|
|
Initialized at start-up of @code{gtroff}.
|
|
|
|
@item \n[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@tie{}0 to@tie{}23.
|
|
Initialized at start-up of @code{gtroff}.
|
|
|
|
@item \n[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 \n[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 \n[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 \n[year]
|
|
@cindex date, year register (@code{year}, @code{yr})
|
|
@cindex year, current, register (@code{year}, @code{yr})
|
|
@vindex year
|
|
The current year.
|
|
|
|
@item \n[yr]
|
|
@vindex yr
|
|
The current year minus@tie{}1900. Unfortunately, the documentation of
|
|
@acronym{UNIX} Version@tie{}7's @code{troff} had a year@tie{}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 \n[.c]
|
|
@vindex .c
|
|
@itemx \n[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 \n[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 \n[.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 1.03 then @code{.x} contains@tie{}@samp{1}.
|
|
|
|
@item \n[.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 1.03 then @code{.y} contains@tie{}@samp{03}.
|
|
|
|
@item \n[.Y]
|
|
@vindex .Y
|
|
@cindex revision number register (@code{.Y})
|
|
The revision number of @code{groff}.
|
|
|
|
@item \n[$$]
|
|
@vindex $$
|
|
@cindex process ID of @code{gtroff} register (@code{$$})
|
|
@cindex @code{gtroff}, process ID register (@code{$$})
|
|
The process ID of @code{gtroff}.
|
|
|
|
@item \n[.g]
|
|
@vindex .g
|
|
@cindex @code{gtroff}, identification register (@code{.g})
|
|
@cindex GNU-specific register (@code{.g})
|
|
Always@tie{}1. Macros should use this to determine whether they are
|
|
running under GNU @code{troff}.
|
|
|
|
@item \n[.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@tie{}1, zero
|
|
otherwise. @xref{Groff Options}.
|
|
|
|
@item \n[.P]
|
|
@vindex .P
|
|
This register is set to@tie{}1 (and to@tie{}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 \n[.T]
|
|
@vindex .T
|
|
If @code{gtroff} is called with the @option{-T} command line option, the
|
|
number register @code{.T} is set to@tie{}1, and zero otherwise.
|
|
@xref{Groff Options}.
|
|
|
|
@item \*[.T]
|
|
@stindex .T
|
|
@cindex output device name string register (@code{.T})
|
|
A single read-write string register which contains the current output
|
|
device (for example, @samp{latin1} or @samp{ps}). This is the only
|
|
string register defined by @code{gtroff}.
|
|
@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@tie{}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@tie{}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@tie{}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
|
|
|
|
Finally, @var{mode} can be the numeric argument returned by the @code{.j}
|
|
register.
|
|
|
|
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
|
|
.nr ad \n[.j]
|
|
text
|
|
.ad c
|
|
text
|
|
.na
|
|
text
|
|
.ad \" back to centering
|
|
text
|
|
.ad \n[ad] \" back to right justifying
|
|
@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 size of a space between 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@tie{}12. In fill mode, the values specify the minimum distance.
|
|
|
|
@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@tie{}12 (@pxref{Implementation Differences}).
|
|
|
|
The request is ignored if there is no parameter.
|
|
|
|
@cindex discardable horizontal space
|
|
@cindex space, discardable, horizontal
|
|
@cindex horizontal discardable space
|
|
Another useful application of the @code{ss} request is to insert
|
|
discardable horizontal space, i.e., space which is discarded at a line
|
|
break. For example, paragraph-style footnotes could be separated this
|
|
way:
|
|
|
|
@Example
|
|
.ll 4.5i
|
|
1.\ This is the first footnote.\c
|
|
.ss 48
|
|
.nop
|
|
.ss 12
|
|
2.\ This is the second footnote.
|
|
@endExample
|
|
|
|
@noindent
|
|
The result:
|
|
|
|
@Example
|
|
1. This is the first footnote. 2. This
|
|
is the second footnote.
|
|
@endExample
|
|
|
|
@noindent
|
|
Note that the @code{\h} escape produces unbreakable space.
|
|
@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
|
|
|
|
|
|
Here a description of requests which 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@tie{}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@tie{}@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@tie{}255. The request maps character code@tie{}@var{a}
|
|
to code@tie{}@var{b}, code@tie{}@var{c} to code@tie{}@var{d}, and so on. You
|
|
can use character codes which would be invalid otherwise.
|
|
|
|
@pindex troffrc
|
|
@pindex troffrc-end
|
|
@pindex hyphen.us
|
|
@pindex hyphenex.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 and exceptions for American
|
|
English (in files @file{hyphen.us} and @file{hyphenex.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.
|
|
|
|
To make hyphenation work, hyphenation codes must be set up. At
|
|
start-up, groff only assigns hyphenation codes to the letters
|
|
@samp{a}-@samp{z} (mapped to themselves) and to the letters
|
|
@samp{A}-@samp{Z} (mapped to @samp{a}-@samp{z}); all other hyphenation
|
|
codes are set to zero. Normally, hyphenation patterns contain only
|
|
lowercase letters which should be applied regardless of case. With
|
|
other words, the words `FOO' and `Foo' should be hyphenated exactly the
|
|
same way as the word `foo' is hyphenated, and this is what @code{hcode}
|
|
is good for. Words which contain other letters won't be hyphenated
|
|
properly if the corresponding hyphenation patterns actually do contain
|
|
them. For example, the following @code{hcode} requests are necessary to
|
|
assign hyphenation codes to the letters @samp{ÄäÖöÜüß} (this is needed
|
|
for German):
|
|
|
|
@Example
|
|
.hcode ä ä Ä ä
|
|
.hcode ö ö Ö ö
|
|
.hcode ü ü Ü ü
|
|
.hcode ß ß
|
|
@endExample
|
|
|
|
Without those assignments, groff treats German words like
|
|
@w{`Kindergärten'} (the plural form of `kindergarten') as two
|
|
substrings @w{`kinderg'} and @w{`rten'} because the hyphenation code
|
|
of the umlaut@tie{}a is zero by default. There is a German
|
|
hyphenation pattern which covers @w{`kinder'}, so groff finds the
|
|
hyphenation `kin-der'. The other two hyphenation points
|
|
(`kin-der-gär-ten') are missed.
|
|
|
|
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@tie{}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@tie{}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@tie{}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}.
|
|
|
|
If a vertical trap is sprung during execution of @code{sp}, the amount of
|
|
vertical space after the trap is discarded. For example, this
|
|
|
|
@Example
|
|
.de xxx
|
|
..
|
|
.
|
|
.wh 0 xxx
|
|
.
|
|
.pl 5v
|
|
foo
|
|
.sp 2
|
|
bar
|
|
.sp 50
|
|
baz
|
|
@endExample
|
|
|
|
@noindent
|
|
results in
|
|
|
|
@Example
|
|
foo
|
|
|
|
|
|
bar
|
|
|
|
baz
|
|
@endExample
|
|
|
|
@cindex @code{sp} request, and traps
|
|
@cindex discarded space in traps
|
|
@cindex space, discarded, in traps
|
|
@cindex traps, and discarded space
|
|
The amount of discarded space is available in the number register
|
|
@code{.trunc}.
|
|
|
|
To protect @code{sp} against vertical traps, use the @code{vpt} request:
|
|
|
|
@Example
|
|
.vpt 0
|
|
.sp -3
|
|
.vpt 1
|
|
@endExample
|
|
@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@tie{}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@tie{}9, @acronym{EBCDIC}
|
|
char@tie{}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@tie{}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@tie{}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.8i}}.
|
|
@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@tie{}9 alias for @code{.tabs}
|
|
@cindex @code{.tabs} register, Plan@tie{}9 alias (@code{.S})
|
|
The @code{troff} version of the Plan@tie{}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@tie{}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@tie{}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@tie{}@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@tie{}@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@tie{}@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'\En[.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@tie{}@var{b}, character @var{c} to
|
|
glyph@tie{}@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@tie{}@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 éÉ
|
|
@endExample
|
|
|
|
@noindent
|
|
This maps input character @code{é} onto glyph @code{É}, 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]
|
|
@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 indentation 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@tie{}1.
|
|
@endDefreq
|
|
|
|
@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@tie{}@code{%}.
|
|
@endDefreq
|
|
|
|
@xref{Traps}.
|
|
|
|
|
|
@c =====================================================================
|
|
|
|
@node Page Control, Fonts and Symbols, Page Layout, gtroff Reference
|
|
@section Page Control
|
|
@cindex page control
|
|
@cindex control, page
|
|
|
|
@DefreqList {bp, [@Var{page}]}
|
|
@DefreqItem {bp, @t{+}@Var{page}}
|
|
@DefreqItem {bp, @t{-}@Var{page}}
|
|
@DefregListEnd {%}
|
|
@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 (which actually
|
|
becomes the current page after @code{bp} has finished). The
|
|
difference between @code{bp} and @code{pn} is that @code{pn} does not
|
|
cause a break or actually eject a page. @xref{Page Layout}.
|
|
|
|
@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}).
|
|
|
|
@cindex page number register (@code{%})
|
|
@cindex current page number (@code{%})
|
|
The read-write register@tie{}@code{%} holds the current page number.
|
|
|
|
The number register @code{.pe} is set to@tie{}1 while @code{bp} is
|
|
active. @xref{Page Location Traps}.
|
|
@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@tie{}1@dmn{v} if no
|
|
argument is given.
|
|
|
|
For example, to make sure that no fewer than 2@tie{}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@tie{}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}
|
|
@cindex current vertical position (@code{nl})
|
|
@cindex vertical position, current (@code{nl})
|
|
@cindex position, vertical, current (@code{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 and Symbols, Sizes, Page Control, gtroff Reference
|
|
@section Fonts and Symbols
|
|
@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 and Symbols, Fonts and Symbols
|
|
@subsection Changing Fonts
|
|
@cindex fonts
|
|
|
|
@DefreqList {ft, [@Var{font}]}
|
|
@DefescItem {\\f, , f, }
|
|
@DefescItem {\\f, @Lparen{}, fn, }
|
|
@DefescItem {\\f, @Lbrack{}, font, @Rbrack{}}
|
|
@DefregListEnd {.sty}
|
|
@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@tie{}@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@tie{}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
|
|
|
|
The current style name is available in the read-only number register
|
|
@samp{.sty} (this is a string-valued register); if the current font
|
|
isn't a style, the empty string is returned. It is associated with
|
|
the current environment.
|
|
|
|
@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
|
|
@cindex @code{if} request, and font translations
|
|
@cindex @code{ie} request, and font translations
|
|
@cindex @code{while} request, and font translations
|
|
Translate font@tie{}@var{f} to font@tie{}@var{g}. Whenever a font
|
|
named@tie{}@var{f} is referred to in a @code{\f} escape sequence,
|
|
in the @code{F} and @code{S} conditional operators, or in the
|
|
@code{ft}, @code{ul}, @code{bd}, @code{cs}, @code{tkf},
|
|
@code{special}, @code{fspecial}, @code{fp}, or @code{sty} requests,
|
|
font@tie{}@var{g} is used. If @var{g} is missing or equal to@tie{}@var{f}
|
|
the translation is undone.
|
|
@endDefreq
|
|
|
|
@c ---------------------------------------------------------------------
|
|
|
|
@node Font Families, Font Positions, Changing Fonts, Fonts and Symbols
|
|
@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},
|
|
@option{-Tlj4}, @option{-Tlbp}, and the X11 fonts 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@tie{}@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@tie{}@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@tie{}1 and font position@tie{}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}@tie{}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@tie{}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 and Symbols
|
|
@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@tie{}1 (which must exist; position@tie{}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@tie{}@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 and Symbols
|
|
@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
|
|
@cindex @code{special} request, and glyph search order
|
|
@cindex @code{fspecial} request, and glyph search order
|
|
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.
|
|
|
|
Here the exact rules how @code{gtroff} searches 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 whether the current font has a font-specific list of special fonts;
|
|
test all fonts in the order of appearance in the last @code{fspecial}
|
|
call if appropriate.
|
|
|
|
@item
|
|
If the symbol has been defined with the @code{fschar} request for the
|
|
current font, use it.
|
|
|
|
@item
|
|
Check all fonts in the order of appearance in the last @code{special}
|
|
call.
|
|
|
|
@item
|
|
If the symbol has been defined with the @code{schar} request, use it.
|
|
|
|
@item
|
|
As a last resort, consult all fonts loaded up to now for special fonts
|
|
and check them, starting with the lowest font number. Note that this can
|
|
sometimes lead to surprising results since the @code{fonts} line in the
|
|
@file{DESC} file often contains empty positions which are filled later
|
|
on. For example, consider the following:
|
|
|
|
@Example
|
|
fonts 3 0 0 FOO
|
|
@endExample
|
|
|
|
@noindent
|
|
This mounts font @code{foo} at font position@tie{}3. We assume that
|
|
@code{FOO} is a special font, containing glyph @code{foo},
|
|
and that no font has been loaded yet. The line
|
|
|
|
@Example
|
|
.fspecial BAR BAZ
|
|
@endExample
|
|
|
|
@noindent
|
|
makes font @code{BAZ} special only if font @code{BAR} is active. We
|
|
further assume that @code{BAZ} is really a special font, i.e., the font
|
|
description file contains the @code{special} keyword, and that it
|
|
also contains glyph @code{foo} with a special shape fitting to font
|
|
@code{BAR}. After executing @code{fspecial}, font @code{BAR} is loaded at
|
|
font position@tie{}1, and @code{BAZ} at position@tie{}2.
|
|
|
|
We now switch to a new font @code{XXX}, trying to access glyph @code{foo}
|
|
which is assumed to be missing. There are neither font-specific special
|
|
fonts for @code{XXX} nor any other fonts made special with the
|
|
@code{special} request, so @code{gtroff} starts the search for special
|
|
fonts in the list of already mounted fonts, with increasing font
|
|
positions. Consequently, it finds @code{BAZ} before @code{FOO} even for
|
|
@code{XXX} which is not the intended behaviour.
|
|
@end itemize
|
|
|
|
@xref{Font Files}, and @ref{Special Fonts}, for more details.
|
|
|
|
@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 of all glyphs. 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
|
|
|
|
@cindex composite glyph names
|
|
@cindex glyph names, composite
|
|
@cindex groff glyph list (GGL)
|
|
@cindex GGL (groff glyph list)
|
|
@cindex adobe glyph list (AGL)
|
|
@cindex AGL (adobe glyph list)
|
|
Glyph names not listed in groff_char(7) are derived algorithmically,
|
|
using a simplified version of the Adobe Glyph List (AGL) algorithm
|
|
which is described in
|
|
@uref{http://partners.adobe.com@//asn@//tech@//type@//unicodegn.jsp}.
|
|
The (frozen) set of glyph names which can't be derived algorithmically
|
|
is called @dfn{groff glyph list (GGL)}.
|
|
|
|
@itemize @bullet
|
|
@item
|
|
A glyph for Unicode character U+@var{XXXX}[@var{X}[@var{X}]] which is
|
|
not a composite character will be named
|
|
@code{u@var{XXXX}@r{[}@var{X}@r{[}@var{X}@r{]]}}. @var{X} must be an
|
|
uppercase hexadecimal digit. Examples: @code{u1234}, @code{u008E},
|
|
@code{u12DB8}. The largest Unicode value is 0x10FFFF. There must be at
|
|
least four @code{X} digits; if necessary, add leading zeroes (after the
|
|
@samp{u}). No zero padding is allowed for character codes greater than
|
|
0xFFFF. Surrogates (i.e., Unicode values greater than 0xFFFF
|
|
represented with character codes from the surrogate area U+D800-U+DFFF)
|
|
are not allowed too.
|
|
|
|
@item
|
|
A glyph representing more than a single input character will be named
|
|
|
|
@display
|
|
@samp{u} @var{component1} @samp{_} @var{component2} @samp{_} @var{component3} @dots{}
|
|
@end display
|
|
|
|
@noindent
|
|
Example: @code{u0045_0302_0301}.
|
|
|
|
For simplicity, all Unicode characters which are composites must be
|
|
decomposed maximally (this is normalization form@tie{}D in the Unicode
|
|
standard); for example, @code{u00CA_0301} is not a valid glyph name
|
|
since U+00CA (@sc{latin capital letter e with circumflex}) can be
|
|
further decomposed into U+0045 (@sc{latin capital letter e}) and U+0302
|
|
(@sc{combining circumflex accent}). @code{u0045_0302_0301} is thus the
|
|
glyph name for U+1EBE, @sc{latin capital letter e with circumflex and
|
|
acute}.
|
|
|
|
@item
|
|
groff maintains a table to decompose all algorithmically derived glyph
|
|
names which are composites itself. For example, @code{u0100} (@sc{latin
|
|
letter a with macron}) will be automatically decomposed into
|
|
@code{u0041_0304}. Additionally, a glyph name of the GGL is preferred
|
|
to an algorithmically derived glyph name; groff also automatically does
|
|
the mapping. Example: The glyph @code{u0045_0302} will be mapped to
|
|
@code{^E}.
|
|
|
|
@item
|
|
glyph names of the GGL can't be used in composite glyph names; for
|
|
example, @code{^E_u0301} is invalid.
|
|
@end itemize
|
|
|
|
@DefescList {\\, @Lparen{}, nm, }
|
|
@DefescItem {\\, @Lbrack{}, name, @Rbrack{}}
|
|
@DefescListEnd {\\, @Lbrack{}, component1 component2 @dots{}, @Rbrack{}}
|
|
Insert a symbol @var{name} (two-character name @var{nm}) or a composite
|
|
glyph with component glyphs @var{component1}, @var{component2},
|
|
@enddots{} 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.
|
|
|
|
groff resolves @code{\[...]} with more than a single component as
|
|
follows:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
Any component which is found in the GGL will be converted to the
|
|
@code{u@var{XXXX}} form.
|
|
|
|
@item
|
|
Any component @code{u@var{XXXX}} which is found in the list of
|
|
decomposable glyphs will be decomposed.
|
|
|
|
@item
|
|
The resulting elements are then concatenated with @samp{_} inbetween,
|
|
dropping the leading @samp{u} in all elements but the first.
|
|
@end itemize
|
|
|
|
No check for the existence of any component (similar to @code{tr}
|
|
request) will be done.
|
|
|
|
Examples:
|
|
|
|
@table @code
|
|
@item \[A ho]
|
|
@samp{A} maps to @code{u0041}, @samp{ho} maps to @code{u02DB}, thus the
|
|
final glyph name would be @code{u0041_02DB}. Note this is not the
|
|
expected result: The ogonek glyph @samp{ho} is a spacing ogonek, but for
|
|
a proper composite a non-spacing ogonek (U+0328) is necessary. Looking
|
|
into the file @file{composite.tmac} one can find @w{@samp{.composite ho
|
|
u0328}} which changes the mapping of @samp{ho} while a composite glyph
|
|
name is constructed, causing the final glyph name to be
|
|
@code{u0041_0328}.
|
|
|
|
@item \[^E u0301]
|
|
@itemx \[^E aa]
|
|
@itemx \[E a^ aa]
|
|
@itemx \[E ^ ']
|
|
@samp{^E} maps to @code{u0045_0302}, thus the final glyph name is
|
|
@code{u0045_0302_0301} in all forms (assuming proper calls of the
|
|
@code{composite} request).
|
|
@end table
|
|
|
|
It is not possible to define glyphs with names like @w{@samp{A ho}}
|
|
within a groff font file. This is not really a limitation; instead, you
|
|
have to define @code{u0041_0328}.
|
|
@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
|
|
|
|
@Defreq {composite, from to}
|
|
@pindex composite.tmac
|
|
Map glyph name @var{from} to glyph name @var{to} if it is used in
|
|
@code{\[...]} with more than one component. See above for examples.
|
|
|
|
This mapping is based on glyph names only; no check for the existence of
|
|
either glyph is done.
|
|
|
|
A set of default mappings for many accents can be found in the file
|
|
@file{composite.tmac} which is loaded at start-up.
|
|
@endDefreq
|
|
|
|
@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@tie{}@var{n} in the current font
|
|
(@code{n}@tie{}is @strong{not} the input character code). The
|
|
number @var{n}@tie{}can be any non-negative decimal integer. Most devices
|
|
only have glyphs with codes between 0 and@tie{}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.
|
|
|
|
No kerning is applied to glyphs accessed with @code{\N}.
|
|
@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}
|
|
@cindex @code{radicalex} glyph, and @code{cflags}
|
|
@cindex @code{sqrtex} glyph, and @code{cflags}
|
|
The character overlaps horizontally if used as a horizontal line building
|
|
element. Initially the symbols @samp{\[ul]}, @samp{\[rn]}, @samp{\[ru]},
|
|
@samp{\[radicalex]}, and @samp{\[sqrtex]} have this property.
|
|
|
|
@item 16
|
|
@cindex @code{br} glyph, and @code{cflags}
|
|
The character overlaps vertically if used as vertical line building element.
|
|
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]} and @samp{\[rq]} have
|
|
this property).
|
|
@end table
|
|
@endDefreq
|
|
|
|
@DefreqList {char, g [@Var{string}]}
|
|
@DefreqItem {fchar, g [@Var{string}]}
|
|
@DefreqItem {fschar, f g [@Var{string}]}
|
|
@DefreqListEnd {schar, g [@Var{string}]}
|
|
@cindex defining character (@code{char})
|
|
@cindex defining fallback character (@code{fchar}, @code{fschar}, @code{schar})
|
|
@cindex character, defining (@code{char})
|
|
@cindex character, defining fallback (@code{fchar}, @code{fschar}, @code{schar})
|
|
@cindex fallback character, defining (@code{fchar}, @code{fschar}, @code{schar})
|
|
@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@tie{}@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@tie{}@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 these requests 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.
|
|
|
|
@code{fschar} defines a fallback glyph for font@tie{}@var{f}: @code{gtroff}
|
|
checks for glyphs defined with @code{fschar} after the list of fonts
|
|
declared as font-specific special fonts with the @code{fspecial} request,
|
|
but before the list of fonts declared as global special fonts with the
|
|
@code{special} request.
|
|
|
|
Finally, the @code{schar} request defines a global fallback glyph:
|
|
@code{gtroff} checks for glyphs defined with @code{schar} after the list
|
|
of fonts declared as global special fonts with the @code{special} request,
|
|
but before the already mounted special fonts.
|
|
|
|
@xref{Using Symbols}, for a detailed description of the glyph
|
|
searching mechanism in @code{gtroff}.
|
|
@endDefreq
|
|
|
|
@DefreqList {rchar, c1 c2 @dots{}}
|
|
@DefreqListEnd {rfschar, f c1 c2 @dots{}}
|
|
@cindex removing glyph definition (@code{rchar}, @code{rfschar})
|
|
@cindex glyph, removing definition (@code{rchar}, @code{rfschar})
|
|
@cindex fallback glyph, removing definition (@code{rchar}, @code{rfschar})
|
|
Remove the definitions of glyphs @var{c1}, @var{c2},@tie{}@enddots{}
|
|
This undoes the effect of a @code{char}, @code{fchar}, or
|
|
@code{schar} request.
|
|
|
|
It is possible to omit the whitespace between arguments.
|
|
|
|
The request @code{rfschar} removes glyph definitions defined with
|
|
@code{fschar} for glyph@tie{}f.
|
|
@endDefreq
|
|
|
|
@xref{Special Characters}.
|
|
|
|
@c ---------------------------------------------------------------------
|
|
|
|
@node Special Fonts, Artificial Fonts, Using Symbols, Fonts and Symbols
|
|
@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, [@Var{s1} @Var{s2} @dots{}]}
|
|
@DefreqListEnd {fspecial, f [@Var{s1} @Var{s2} @dots{}]}
|
|
@kindex fonts
|
|
@pindex DESC
|
|
Use the @code{special} request to define special fonts. Initially, this
|
|
list is empty.
|
|
|
|
Use the @code{fspecial} request to designate special fonts only when
|
|
font@tie{}@var{f} is active. Initially, this list is empty.
|
|
|
|
Previous calls to @code{special} or @code{fspecial} are overwritten;
|
|
without arguments, the particular list of special fonts is set to empty.
|
|
Special fonts are searched in the order they appear as arguments.
|
|
|
|
All fonts which appear in a call to @code{special} or @code{fspecial} are
|
|
loaded.
|
|
|
|
@xref{Using Symbols}, for the exact search order of glyphs.
|
|
@endDefreq
|
|
|
|
@c ---------------------------------------------------------------------
|
|
|
|
@node Artificial Fonts, Ligatures and Kerning, Special Fonts, Fonts and Symbols
|
|
@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{+}height, '}
|
|
@DefescItem {\\H, ', @t{-}height, '}
|
|
@DefregListEnd {.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}.
|
|
|
|
The read-only number register @code{.height} contains the font height as
|
|
set by @code{\H}.
|
|
|
|
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, '}
|
|
@DefregListEnd {.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. Only integer values are possible.
|
|
|
|
The read-only number register @code{.slant} contains the font slant as
|
|
set by @code{\S}.
|
|
|
|
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@tie{}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 and Symbols
|
|
@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).
|
|
|
|
Only the current font is checked for ligatures and kerns; neither special
|
|
fonts nor entities defined with the @code{char} request (and its siblings)
|
|
are taken into account.
|
|
|
|
@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@tie{}2 if ligatures are enabled, 0@tie{}otherwise).
|
|
|
|
Setting the ligature mode to@tie{}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.
|
|
@iftex
|
|
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 iftex
|
|
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@tie{}1 if pairwise kerning is enabled,
|
|
0@tie{}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@tie{}@var{f}. If the current font
|
|
is@tie{}@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@tie{}@code{f} is immediately followed by a roman right
|
|
parenthesis, then in many fonts the top right portion of the@tie{}@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
|
|
@c can't use @Example...@endExample here
|
|
@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
|
|
@c can't use @Example...@endExample here
|
|
@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.
|
|
|
|
@iftex
|
|
@c can't use @Example...@endExample here
|
|
@example
|
|
@group
|
|
VA
|
|
@result{} @r{VA}
|
|
V\&A
|
|
@result{} @r{V@w{}A}
|
|
@end group
|
|
@end example
|
|
@end iftex
|
|
|
|
@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 and Symbols, 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%@tie{}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@tie{}point type on
|
|
12@tie{}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@tie{}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}@tie{}points. @var{n}@tie{}must be either
|
|
0 or in the range 4 to@tie{}39.
|
|
|
|
@item \s+@var{n}
|
|
@itemx \s-@var{n}
|
|
Increase or decrease the point size by @var{n}@tie{}points.
|
|
@var{n}@tie{}must be exactly one digit.
|
|
|
|
@item \s(@var{nn}
|
|
Set the point size to @var{nn}@tie{}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}@tie{}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@tie{}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
|
|
negative; the vertical spacing is then set to smallest positive value,
|
|
the vertical resolution (as given in the @code{.V} register).
|
|
|
|
Note that @w{@samp{.vs 0}} isn't saved in a diversion since it doesn't
|
|
result in a vertical motion. You explicitly have to repeat this command
|
|
before inserting the diversion.
|
|
|
|
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. Breaking
|
|
a line causes the following actions (in the given order).
|
|
|
|
@itemize @bullet
|
|
@item
|
|
@cindex extra pre-vertical line space (@code{\x})
|
|
@cindex line space, extra pre-vertical (@code{\x})
|
|
Move the current point vertically by the @dfn{extra pre-vertical line
|
|
space}. This is the minimum value of all @code{\x} escapes with a
|
|
negative argument in the current output line.
|
|
|
|
@item
|
|
Move the current point vertically by the vertical line spacing as set with
|
|
the @code{vs} request.
|
|
|
|
@item
|
|
Output the current line.
|
|
|
|
@item
|
|
@cindex extra post-vertical line space (@code{\x})
|
|
@cindex line space, extra post-vertical (@code{\x})
|
|
Move the current point vertically by the @dfn{extra post-vertical line
|
|
space}. This is the maximum value of all @code{\x} escapes with a
|
|
positive argument in the line which has just been output.
|
|
|
|
@item
|
|
@cindex post-vertical line spacing
|
|
@cindex line spacing, post-vertical (@code{pvs})
|
|
Move the current point vertically by the @dfn{post-vertical line spacing}
|
|
as set with the @code{pvs} request.
|
|
@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@tie{}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@tie{}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@tie{}scaled points, which is equal to 10.25@tie{}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}@tie{}scaled points; @var{n}@tie{}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}@tie{}scaled points;
|
|
@var{n}@tie{}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 except @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@tie{}@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 and Macro
|
|
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@tie{}@var{n2}. The first character
|
|
in the string has index@tie{}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@tie{}@minus{}1, the
|
|
character before the last character has index@tie{}@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 \*[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 (identifying a @code{-Tversatec} device).
|
|
|
|
@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@tie{}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.
|
|
|
|
@item F @var{font}
|
|
True if a font named @var{font} exists. @var{font} is handled as if it was
|
|
opened with the @code{ft} request (this is, font translation and styles are
|
|
applied), without actually mounting it.
|
|
|
|
This test doesn't load the complete font but only its header to verify
|
|
its validity.
|
|
|
|
@item S @var{style}
|
|
True if style @var{style} has been registered. Font translation is applied.
|
|
@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 a value greater than
|
|
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@tie{}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@tie{}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@tie{}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}]}
|
|
@DefreqItem {dei, name [@Var{end}]}
|
|
@DefreqListEnd {dei1, 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
|
|
|
|
The @code{dei1} request is similar to @code{dei} but with compatibility
|
|
mode switched off during execution of the defined macro.
|
|
|
|
If compatibility mode is on, @code{de} (and @code{dei}) behave similar to
|
|
@code{de1} (and @code{dei1}): A `compatibility save' token is inserted at
|
|
the beginning, and a `compatibility restore' token at the end, with
|
|
compatibility mode switched on during execution. @xref{Gtroff Internals},
|
|
for more information on switching compatibility mode on and off in a
|
|
single document.
|
|
|
|
@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, name [@Var{end}]}
|
|
@DefreqItem {am1, name [@Var{end}]}
|
|
@DefreqItem {ami, name [@Var{end}]}
|
|
@DefreqListEnd {ami1, name [@Var{end}]}
|
|
@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{name}. 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{name} or @var{end} before performing the append.
|
|
|
|
The @code{ami1} request is similar to @code{ami} but compatibility mode
|
|
is switched off during execution of the defined macro.
|
|
|
|
@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, [@Var{anything}]}
|
|
Exit a macro, immediately returning to the caller.
|
|
|
|
If called with an argument, exit twice, namely the current macro and the
|
|
macro one level higher. This is used to define a wrapper macro for
|
|
@code{return} in @file{trace.tmac}.
|
|
@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@tie{}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.
|
|
|
|
Note that the @code{shift} request can change its value.
|
|
@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@tie{}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@tie{}position, or as
|
|
many positions as specified by its argument. After executing this
|
|
request, argument@tie{}@var{i} becomes argument @math{@var{i}-@var{n}};
|
|
arguments 1 to@tie{}@var{n} are no longer available. Shifting by
|
|
negative amounts is currently undefined.
|
|
|
|
The register @code{.$} is adjusted accordingly.
|
|
@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 and Macro 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 and Macro 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@tie{}@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@tie{}1@dmn{v}.
|
|
@endDefesc
|
|
|
|
@Defesc {\\u, , , }
|
|
Move upwards@tie{}.5@dmn{v}.
|
|
@endDefesc
|
|
|
|
@Defesc {\\d, , , }
|
|
Move down@tie{}.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@tie{}@var{e}
|
|
indicates how far to move: positive is rightwards and negative
|
|
leftwards. The default scaling indicator for this escape is @samp{m}.
|
|
|
|
This horizontal space is not discarded at the end of a line. To insert
|
|
discardable space of a certain length use the @code{ss} request.
|
|
@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}. Values below the baseline are
|
|
negative.
|
|
|
|
@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@tie{}@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 (relative to the current indentation).
|
|
@endDefreg
|
|
|
|
@Defesc {\\o, ', abc, '}
|
|
@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, ', l, '}
|
|
@DefescListEnd {\\l, ', lg, '}
|
|
@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@tie{}@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, ', l, '}
|
|
@DefescListEnd {\\L, ', lg, '}
|
|
@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, and @w{@code{\D'F@var{x} @dots{}'}}
|
|
which arguments are treated similar to the @code{defcolor} request.
|
|
|
|
@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}), where positive values mean down and right,
|
|
respectively. The end point of the line is the new current location.
|
|
|
|
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@tie{}@var{d} with the leftmost point at the
|
|
current position. After drawing, the current location is positioned at the
|
|
rightmost point of the circle.
|
|
|
|
@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 and behaviour 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.
|
|
After drawing, the current location is positioned at the rightmost point of
|
|
the ellipse.
|
|
|
|
@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 and behaviour 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. After drawing, the current position is moved
|
|
to the final point of the arc.
|
|
|
|
@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.
|
|
The current position is moved to the terminal point of the drawn curve.
|
|
|
|
@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@tie{}@var{n};
|
|
@var{n}@tie{}must be an integer between 0 and@tie{}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.
|
|
|
|
Despite of being silly, the current point is moved horizontally to the
|
|
right by@tie{}@var{n}.
|
|
|
|
@cindex @w{@code{\D'f @dots{}'}} and horizontal resolution
|
|
Don't use this command! It has the serious drawback that it will be
|
|
always rounded to the next integer multiple of the horizontal resolution
|
|
(the value of the @code{hor} keyword in the @file{DESC} file). Use
|
|
@code{\M} (@pxref{Colors}) or @w{@code{\D'Fg @dots{}'}} instead.
|
|
|
|
@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. The current 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.
|
|
|
|
@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 and behaviour 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}@tie{}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}).
|
|
|
|
Despite of being silly, the current point is moved horizontally to the
|
|
right by@tie{}@var{n}.
|
|
|
|
@item \D'F@var{scheme} @var{color_components}'
|
|
@cindex unnamed fill colors (@code{\D'F@dots{}'})
|
|
@cindex fill colors, unnamed (@code{\D'F@dots{}'})
|
|
@cindex colors, fill, unnamed (@code{\D'F@dots{}'})
|
|
Change current fill color. @var{scheme} is a single letter denoting the
|
|
color scheme: @samp{r} (rgb), @samp{c} (cmy), @samp{k} (cmyk), @samp{g}
|
|
(gray), or @samp{d} (default color). The color components use exactly
|
|
the same syntax as in the @code{defcolor} request (@pxref{Colors}); the
|
|
command @code{\D'Fd'} doesn't take an argument.
|
|
|
|
@emph{No} position changing!
|
|
|
|
Examples:
|
|
|
|
@Example
|
|
@endExample
|
|
\D'Fg .3' \" same gray as \D'f 700'
|
|
\D'Fr #0000ff' \" blue
|
|
@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.
|
|
|
|
Note that a page can't be ejected if @code{vpt} is set to zero.
|
|
@endDefreq
|
|
|
|
@Defreq {wh, dist [@Var{macro}]}
|
|
Set a page location trap. Non-negative 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
|
|
in the following example):
|
|
|
|
@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 [@Var{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 in opposite order as in 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.
|
|
|
|
Since the @code{.ne} register is only set by traps it doesn't make
|
|
much sense to use it outside of trap macros.
|
|
@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.
|
|
|
|
Since the @code{.trunc} register is only set by traps it doesn't make
|
|
much sense to use it outside of trap macros.
|
|
@endDefreg
|
|
|
|
@Defreg {.pe}
|
|
@cindex @code{bp} request, and traps (@code{.pe})
|
|
@cindex traps, sprung by @code{bp} request (@code{.pe})
|
|
@cindex page ejecting register (@code{.pe})
|
|
A read-only register which is set to@tie{}1 while a page is ejected with
|
|
the @code{bp} request (or by the end of input).
|
|
|
|
Outside of traps this register is always zero. In the following example,
|
|
only the second call to@tie{}@code{x} is caused by @code{bp}.
|
|
|
|
@Example
|
|
.de x
|
|
\&.pe=\\n[.pe]
|
|
.br
|
|
..
|
|
.wh 1v x
|
|
.wh 4v x
|
|
A line.
|
|
.br
|
|
Another line.
|
|
.br
|
|
@result{} A line.
|
|
.pe=0
|
|
Another line.
|
|
|
|
.pe=1
|
|
@endExample
|
|
@endDefreg
|
|
|
|
@cindex diversions, and traps
|
|
@cindex traps, and diversions
|
|
An important fact to consider while designing macros is that diversions and
|
|
traps do not interact normally. For example, if a trap invokes a header
|
|
macro (while outputting a diversion) which tries to change the font on the
|
|
current page, the effect will not be visible before the diversion has
|
|
completely been printed (except for input protected with @code{\!} or
|
|
@code{\?}) since the data in the diversion is already formatted. In most
|
|
cases, this is not the expected behaviour.
|
|
|
|
@c ---------------------------------------------------------------------
|
|
|
|
@node Diversion Traps, Input Line Traps, Page Location Traps, Traps
|
|
@subsection Diversion Traps
|
|
@cindex diversion traps
|
|
@cindex traps, diversion
|
|
|
|
@Defreq {dt, [@Var{dist} @Var{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.
|
|
If called without arguments, the diversion trap is removed.
|
|
|
|
Note that there exists only a single diversion trap.
|
|
|
|
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}@tie{}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}@tie{}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 an interrupted text line (ending with @code{\c})
|
|
is not counted as a separate 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 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}
|
|
@cindex @code{dn} register, and @code{da} (@code{boxa})
|
|
@cindex @code{dl} register, and @code{da} (@code{boxa})
|
|
@cindex @code{da} request, and @code{dn} (@code{dl})
|
|
@cindex @code{boxa} request, and @code{dn} (@code{dl})
|
|
After completing a diversion, the read-write number registers @code{dn}
|
|
and @code{dl} contain the vertical and horizontal size of the diversion.
|
|
Note that only the just processed lines are counted: For the computation
|
|
of @code{dn} and @code{dl}, the requests @code{da} and @code{boxa} are
|
|
handled as if @code{di} and @code{box} had been used -- lines which have
|
|
been already stored in a macro are not taken into account.
|
|
|
|
@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 {\\?, , anything, \\?}
|
|
@cindex transparent output (@code{\!}, @code{\?})
|
|
@cindex output, transparent (@code{\!}, @code{\?})
|
|
Prevent requests, macros, and escapes from being
|
|
interpreted when read into a diversion. Both escapes take the given text
|
|
and @dfn{transparently} embed 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. 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@tie{}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 @var{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@tie{}@code{n} to@tie{}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@tie{}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 indentation 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 {.w}
|
|
@DefregItem {.cht}
|
|
@DefregItem {.cdp}
|
|
@DefregListEnd {.csk}
|
|
@cindex environment, dimensions of last glyph (@code{.w}, @code{.cht}, @code{.cdp}, @code{.csk})
|
|
@cindex width, of last glyph (@code{.w})
|
|
@cindex height, of last glyph (@code{.cht})
|
|
@cindex depth, of last glyph (@code{.cdp})
|
|
@cindex skew, of last glyph (@code{.csk})
|
|
@cindex last glyph, dimensions (@code{.w}, @code{.cht}, @code{.cdp}, @code{.csk})
|
|
@cindex glyph, last, dimensions (@code{.w}, @code{.cht}, @code{.cdp}, @code{.csk})
|
|
The @code{\n[.w]} register contains the
|
|
width of the last glyph added to the current environment.
|
|
|
|
The @code{\n[.cht]} register contains the
|
|
height of the last glyph added to the current environment.
|
|
|
|
The @code{\n[.cdp]} register contains the
|
|
depth of the last glyph added to the current environment.
|
|
It is positive for glyphs extending below the baseline.
|
|
|
|
The @code{\n[.csk]} register contains the
|
|
@dfn{skew} (how far to the right of the glyph's center
|
|
that @code{gtroff} should place an accent)
|
|
of the last glyph added to the current environment.
|
|
@endDefreg
|
|
|
|
@Defreg {.n}
|
|
@cindex environment, previous line length (@code{.n})
|
|
@cindex line length, previous (@code{.n})
|
|
@cindex length of previous line (@code{.n})
|
|
@cindex previous line length (@code{.n})
|
|
The @code{\n[.n]} register contains the
|
|
length of the previous output line in 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@tie{}@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@tie{}1 if colors are active,
|
|
0@tie{}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{cmy} (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@tie{}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@tie{}@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@tie{}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
|
|
|
|
@DefreqList {gcolor, [@Var{color}]}
|
|
@DefescItem {\\m, , c, }
|
|
@DefescItem {\\m, @Lparen{}, co, }
|
|
@DefescItem {\\m, @Lbrack{}, color, @Rbrack{}}
|
|
@DefregListEnd {.m}
|
|
Set (glyph) drawing color. The following examples show how to turn the
|
|
next four words red.
|
|
|
|
@Example
|
|
.gcolor red
|
|
these are in red
|
|
.gcolor
|
|
and these words are in black.
|
|
@endExample
|
|
|
|
@Example
|
|
\m[red]these are in red\m[] and these words are in black.
|
|
@endExample
|
|
|
|
The escape @code{\m[]} returns to the previous color, as does a call to
|
|
@code{gcolor} without an argument.
|
|
|
|
@cindex drawing color name register (@code{.m})
|
|
@cindex name, drawing color, register (@code{.m})
|
|
@cindex color name, drawing, register (@code{.m})
|
|
The name of the current drawing color is available in the read-only,
|
|
string-valued number register @samp{.m}.
|
|
|
|
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
|
|
|
|
@DefreqList {fcolor, [@Var{color}]}
|
|
@DefescItem {\\M, , c, }
|
|
@DefescItem {\\M, @Lparen{}, co, }
|
|
@DefescItem {\\M, @Lbrack{}, color, @Rbrack{}}
|
|
@DefregListEnd {.M}
|
|
Set fill (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, as does a call to
|
|
@code{fcolor} without an argument.
|
|
|
|
@cindex background color name register (@code{.M})
|
|
@cindex name, background color, register (@code{.M})
|
|
@cindex color name, background, register (@code{.M})
|
|
@cindex fill color name register (@code{.M})
|
|
@cindex name, fill color, register (@code{.M})
|
|
@cindex color name, fill, register (@code{.M})
|
|
The name of the current fill (background) color is available in the
|
|
read-only, string-valued number register @samp{.M}.
|
|
|
|
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}.
|
|
|
|
The search path for @var{file} can be controlled with the @option{-I} command
|
|
line option.
|
|
@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@tie{}@code{x} containing the contents of file@tie{}@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@tie{}@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@tie{}@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@tie{}5 means to emit only line numbers which
|
|
are multiples of@tie{}5; this defaults to@tie{}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@tie{}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.
|
|
|
|
For compatibility with @acronym{AT&T} @code{troff}, a call to @code{mc}
|
|
to set the margin character can't be undone immediately; at least one
|
|
line gets a margin character. Thus
|
|
|
|
@Example
|
|
.ll 1i
|
|
.mc \[br]
|
|
.mc
|
|
xxx
|
|
.br
|
|
xxx
|
|
@endExample
|
|
|
|
@noindent
|
|
produces
|
|
|
|
@Example
|
|
xxx |
|
|
xxx
|
|
@endExample
|
|
|
|
@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.
|
|
|
|
The search path for @var{filename} can be controlled with the @option{-I}
|
|
command line option.
|
|
@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@tie{}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@tie{}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}.
|
|
|
|
@cindex compatibility mode, and parameters
|
|
@cindex mode, compatibility, and parameters
|
|
@cindex arguments, and compatibility mode
|
|
@cindex parameters, and compatibility mode
|
|
@cindex macro arguments, and compatibility mode
|
|
@cindex request arguments, and compatibility mode
|
|
Macro and request arguments preserve the compatibility mode:
|
|
|
|
@Example
|
|
.cp 1 \" switch to compatibility mode
|
|
.de xx
|
|
\\$1
|
|
..
|
|
.cp 0 \" switch compatibility mode off
|
|
.xx caf\['e]
|
|
@result{} café
|
|
@endExample
|
|
|
|
@noindent
|
|
Since compatibility mode is on while @code{de} is called, the macro
|
|
@code{xx} activates compatibility mode while executing. Argument
|
|
@code{$1} can still be handled properly because it inherits the
|
|
compatibility mode status which was active at the point where @code{xx}
|
|
is called.
|
|
|
|
After expansion of the parameters, the compatibility save and restore
|
|
tokens are removed.
|
|
|
|
|
|
@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 [@Var{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 optionally 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.
|
|
|
|
Note that other @code{troff} implementations (including the original
|
|
@acronym{AT&T} version) handle @code{lf} differently. For them,
|
|
@var{line} changes the line number of the @emph{current} line.
|
|
@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@tie{}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@tie{}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@tie{}1 if compatibility mode is
|
|
on, 0@tie{}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
|
|
|
|
@noindent
|
|
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@tie{}points, whereas in GNU @code{troff} it
|
|
sets the point size to 10@tie{}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
|
|
@uref{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.cpp}.}
|
|
|
|
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@tie{}@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@tie{}@var{n} (a non-negative integer).
|
|
|
|
@item H @var{n}
|
|
Move right to the absolute vertical position@tie{}@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@tie{}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@tie{}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@tie{}color components
|
|
@var{red}, @var{green}, and @var{blue}.
|
|
@end table
|
|
|
|
@item N @var{n}
|
|
Print glyph with index@tie{}@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@tie{}@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@tie{}@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@tie{}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}@tie{}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@tie{}@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@tie{}@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}@tie{}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.
|
|
|
|
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@tie{}@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@tie{}@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@tie{}@var{h} and a vertical diameter of@tie{}@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@tie{}@var{h}
|
|
and a vertical diameter of@tie{}@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@tie{}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@tie{}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@tie{}color components @var{red}, @var{green}, and @var{blue}.
|
|
@end table
|
|
|
|
@item Df @var{n}@angles{line break}
|
|
The argument@tie{}@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} < 0} or @math{@var{n} > 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@tie{}@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@tie{}@var{n} (a non-negative integer) with font
|
|
named@tie{}@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@tie{}@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@tie{}@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@tie{}@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@tie{}1, start
|
|
underlining of spaces; if @var{n} is@tie{}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@tie{}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@tie{}@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@tie{}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@tie{}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@tie{}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@tie{}@var{f} a font file
|
|
called@tie{}@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
|
|
@cindex device resolution
|
|
@cindex resolution, device
|
|
There are @var{n}@tie{}machine units per inch.
|
|
|
|
@item hor @var{n}
|
|
@kindex hor
|
|
@cindex horizontal resolution
|
|
@cindex resolution, horizontal
|
|
The horizontal resolution is @var{n}@tie{}machine units. All horizontal
|
|
quantities are rounded to be multiples of this value.
|
|
|
|
@item vert @var{n}
|
|
@kindex vert
|
|
@cindex vertical resolution
|
|
@cindex resolution, vertical
|
|
The vertical resolution is @var{n}@tie{}machine units. All vertical
|
|
quantities are rounded to be multiples of this value.
|
|
|
|
@item sizescale @var{n}
|
|
@kindex sizescale
|
|
The scale factor for point sizes. By default this has a value of@tie{}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}@tie{}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@tie{}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}@tie{}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@tie{}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@tie{}@var{f}.
|
|
|
|
@item spacewidth @var{n}
|
|
@kindex spacewidth
|
|
The normal width of a space is@tie{}@var{n}.
|
|
|
|
@item slant @var{n}
|
|
@kindex slant
|
|
The glyphs of the font have a slant of @var{n}@tie{}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@tie{}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@tie{}@var{c} then it corresponds
|
|
to the @code{gtroff} input character@tie{}@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@tie{}@var{n}. For example,
|
|
@samp{char163} would be equivalent to the character with code@tie{}163
|
|
which is the pounds sterling sign in the ISO@tie{}@w{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@tie{}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@tie{}@var{n}. Most
|
|
entries in the kernpairs section have a negative value for@tie{}@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@tie{}@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@tie{}@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
|