/contrib/groff/doc/groff.texinfo
Unknown | 15454 lines | 12574 code | 2880 blank | 0 comment | 0 complexity | 8b088c4112aed0fed1c425e0f04bd15a MD5 | raw file
Possible License(s): MPL-2.0-no-copyleft-exception, BSD-3-Clause, LGPL-2.0, LGPL-2.1, BSD-2-Clause, 0BSD, JSON, AGPL-1.0, GPL-2.0
- \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 exept @code{.T}, but
- even this is a read-write string variable).
- @DefreqList {ds, name [@Var{string}]}
- @DefreqItem {ds1, name [@Var{string}]}
- @DefescItem {\\*, , n, }
- @DefescItem {\\*, @Lparen{}, nm, }
- @DefescListEnd {\\*, @Lbrack{}, name arg1 arg2 @dots{}, @Rbrack{}}
- @cindex string interpolation (@code{\*})
- @cindex string expansion (@code{\*})
- @cindex interpolation of strings (@code{\*})
- @cindex expansion of strings (@code{\*})
- @cindex string arguments
- @cindex arguments, of strings
- Define and access a string variable @var{name} (one-character
- name@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