1 \input texinfo @c -*-texinfo-*-
4 @c Please convert this manual with `texi2dvi -e groff.texinfo' due to
5 @c problems in texinfo regarding expansion of user-defined macros.
7 @c You need texinfo 4.6 or newer to format this document!
10 @c %**start of header (This is for running Texinfo on a region.)
12 @settitle The GNU Troff Manual
13 @setchapternewpage odd
14 @footnotestyle separate
15 @c %**end of header (This is for running Texinfo on a region.)
18 @documentencoding ISO-8859-1
27 This manual documents GNU @code{troff} version 1.19.2.
29 Copyright @copyright{} 1994-2000, 2001, 2002, 2003, 2004, 2005
30 Free Software Foundation, Inc.
33 Permission is granted to copy, distribute and/or modify this document
34 under the terms of the GNU Free Documentation License, Version 1.1 or
35 any later version published by the Free Software Foundation; with no
36 Invariant Sections, with the Front-Cover texts being `A GNU Manual,''
37 and with the Back-Cover Texts as in (a) below. A copy of the
38 license is included in the section entitled `GNU Free Documentation
41 (a) The FSF's Back-Cover Text is: `You have freedom to copy and modify
42 this GNU Manual, like GNU software. Copies published by the Free
43 Software Foundation raise funds for GNU development.''
48 @c We use the following indices:
54 @c kindex: commands in font files
55 @c pindex: programs and files
56 @c tindex: environment variables
61 @c tindex and cindex are merged.
71 @c To avoid uppercasing in @deffn while converting to info, we define
72 @c our special @Var{}.
79 @c To assure correct HTML translation, some ugly hacks are necessary.
80 @c While processing a @def... request, the HTML translator looks at the
81 @c next line to decide whether it should start indentation or not. If
82 @c it is something starting with @def... (e.g. @deffnx), it doesn't.
83 @c So we must assure during macro expansion that a @def... is seen.
85 @c The following macros have to be used:
104 @c The definition block must end with
108 @c The above is valid for texinfo 4.0f and above.
111 @c a dummy macro to assure the `@def...'
118 @c definition of requests
120 @macro Defreq{name, arg}
121 @deffn Request @t{.\name\} \arg\
126 @macro DefreqList{name, arg}
127 @deffn Request @t{.\name\} \arg\
133 @macro DefreqItem{name, arg}
134 @deffnx Request @t{.\name\} \arg\
140 @macro DefreqListEnd{name, arg}
141 @deffnx Request @t{.\name\} \arg\
151 @c definition of escapes
153 @macro Defesc{name, delimI, arg, delimII}
154 @deffn Escape @t{\name\\delimI\}@Var{\arg\}@t{\delimII\}
159 @macro DefescList{name, delimI, arg, delimII}
160 @deffn Escape @t{\name\\delimI\}@Var{\arg\}@t{\delimII\}
166 @macro DefescItem{name, delimI, arg, delimII}
167 @deffnx Escape @t{\name\\delimI\}@Var{\arg\}@t{\delimII\}
173 @macro DefescListEnd{name, delimI, arg, delimII}
174 @deffnx Escape @t{\name\\delimI\}@Var{\arg\}@t{\delimII\}
184 @c definition of registers
187 @deffn Register @t{\\n[\name\]}
192 @macro DefregList{name}
193 @deffn Register @t{\\n[\name\]}
199 @macro DefregItem{name}
200 @deffnx Register @t{\\n[\name\]}
206 @macro DefregListEnd{name}
207 @deffnx Register @t{\\n[\name\]}
217 @c definition of registers specific to macro packages, preprocessors, etc.
219 @macro Defmpreg{name, package}
220 @deffn Register @t{\\n[\name\]}
221 @vindex \name\ @r{[}\package\@r{]}
225 @macro DefmpregList{name, package}
226 @deffn Register @t{\\n[\name\]}
228 @vindex \name\ @r{[}\package\@r{]}
232 @macro DefmpregItem{name, package}
233 @deffnx Register @t{\\n[\name\]}
235 @vindex \name\ @r{[}\package\@r{]}
239 @macro DefmpregListEnd{name, package}
240 @deffnx Register @t{\\n[\name\]}
241 @vindex \name\ @r{[}\package\@r{]}
250 @c definition of macros
252 @macro Defmac{name, arg, package}
253 @defmac @t{.\name\} \arg\
254 @maindex \name\ @r{[}\package\@r{]}
258 @macro DefmacList{name, arg, package}
259 @defmac @t{.\name\} \arg\
261 @maindex \name\ @r{[}\package\@r{]}
265 @macro DefmacItem{name, arg, package}
266 @defmacx @t{.\name\} \arg\
268 @maindex \name\ @r{[}\package\@r{]}
272 @macro DefmacListEnd{name, arg, package}
273 @defmacx @t{.\name\} \arg\
274 @maindex \name\ @r{[}\package\@r{]}
283 @c definition of strings
285 @macro Defstr{name, package}
286 @deffn String @t{\\*[\name\]}
287 @stindex \name\ @r{[}\package\@r{]}
291 @macro DefstrList{name, package}
292 @deffn String @t{\\*[\name\]}
294 @stindex \name\ @r{[}\package\@r{]}
298 @macro DefstrItem{name, package}
299 @deffnx String @t{\\*[\name\]}
301 @stindex \name\ @r{[}\package\@r{]}
305 @macro DefstrListEnd{name, package}
306 @deffnx String @t{\\*[\name\]}
307 @stindex \name\ @r{[}\package\@r{]}
332 \gdef\Langlemacro{\angleleft}
333 \gdef\Ranglemacro{\angleright}
337 @set Langlemacro @Langlemacro
338 @set Ranglemacro @Ranglemacro
347 @value{Langlemacro}@r{\text\}@value{Ranglemacro}
353 @c A value defined with @set is embedded into three group levels if
354 @c called with @value, so we need seven \aftergroup to put \le outside
355 @c of the groups -- this is necessary to get proper mathematical spacing.
358 \gdef\LEmacro{\aftergroup\aftergroup\aftergroup\aftergroup
359 \aftergroup\aftergroup\aftergroup\le}
363 @set LEmacro @LEmacro
375 @c We need special parentheses and brackets:
377 @c . Real parentheses in @deffn produce an error while compiling with
379 @c . Real brackets use the wrong font in @deffn, overriding @t{}.
381 @c Since macros aren't expanded in @deffn during -E, the following
382 @c definitions are for non-TeX only.
384 @c This is true for texinfo 4.0.
387 @set Lparenmacro @lparen
388 @set Rparenmacro @rparen
389 @set Lbrackmacro @lbrack
390 @set Rbrackmacro @rbrack
414 @c This suppresses the word `Appendix' in the appendix headers.
417 \gdef\gobblefirst#1#2{#2}
418 \gdef\putwordAppendix{\gobblefirst}
422 @c We map some latin-1 characters to corresponding texinfo macros.
425 \global\catcode`^^e4\active % ä
427 \global\catcode`^^c4\active % Ä
429 \global\catcode`^^e9\active % é
431 \global\catcode`^^c9\active % É
433 \global\catcode`^^f6\active % ö
435 \global\catcode`^^d6\active % Ö
437 \global\catcode`^^fc\active % ü
439 \global\catcode`^^dc\active % Ü
441 \global\catcode`^^e6\active % æ
443 \global\catcode`^^c6\active % Æ
445 \global\catcode`^^df\active % ß
450 @c Note: We say `Roman numerals' but `roman font'.
453 @dircategory Typesetting
455 * Groff: (groff). The GNU troff document formatting system.
461 @subtitle The GNU implementation of @code{troff}
462 @subtitle Edition 1.19.2
463 @subtitle Spring 2005
464 @author by Trent A.@tie{}Fisher
465 @author and Werner Lemberg (@email{bug-groff@@gnu.org})
468 @vskip 0pt plus 1filll
476 @node Top, Introduction, (dir), (dir)
483 @node Top, Introduction, (dir), (dir)
492 * Tutorial for Macro Users::
499 * Copying This Manual::
507 * Font File Keyword Index::
508 * Program and File Index::
514 @c =====================================================================
515 @c =====================================================================
517 @node Introduction, Invoking groff, Top, Top
518 @chapter Introduction
521 GNU @code{troff} (or @code{groff}) is a system for typesetting
522 documents. @code{troff} is very flexible and has been in existence (and
523 use) for about 3@tie{}decades. It is quite widespread and firmly
524 entrenched in the @acronym{UNIX} community.
529 * groff Capabilities::
530 * Macro Package Intro::
531 * Preprocessor Intro::
532 * Output device intro::
537 @c =====================================================================
539 @node What Is groff?, History, Introduction, Introduction
540 @section What Is @code{groff}?
541 @cindex what is @code{groff}?
542 @cindex @code{groff} -- what is it?
544 @code{groff} belongs to an older generation of document preparation
545 systems, which operate more like compilers than the more recent
546 interactive @acronym{WYSIWYG}@footnote{What You See Is What You Get}
547 systems. @code{groff} and its contemporary counterpart, @TeX{}, both
548 work using a @dfn{batch} paradigm: The input (or @dfn{source}) files are
549 normal text files with embedded formatting commands. These files can
550 then be processed by @code{groff} to produce a typeset document on a
553 Likewise, @code{groff} should not be confused with a @dfn{word
554 processor}, since that term connotes an integrated system that includes
555 an editor and a text formatter. Also, many word processors follow the
556 @acronym{WYSIWYG} paradigm discussed earlier.
558 Although @acronym{WYSIWYG} systems may be easier to use, they have a
559 number of disadvantages compared to @code{troff}:
563 They must be used on a graphics display to work on a document.
566 Most of the @acronym{WYSIWYG} systems are either non-free or are not
570 @code{troff} is firmly entrenched in all @acronym{UNIX} systems.
573 It is difficult to have a wide range of capabilities available within
574 the confines of a GUI/window system.
577 It is more difficult to make global changes to a document.
581 ``GUIs normally make it simple to accomplish simple actions and
582 impossible to accomplish complex actions.'' --Doug Gwyn (22/Jun/91 in
583 @code{comp.unix.wizards})
587 @c =====================================================================
589 @node History, groff Capabilities, What Is groff?, Introduction
593 @cindex @code{runoff}, the program
594 @cindex @code{rf}, the program
595 @code{troff} can trace its origins back to a formatting program called
596 @code{runoff}, written by J.@tie{}E.@tie{}Saltzer, which ran on MIT's CTSS
597 operating system in the mid-sixties. This name came from the common
598 phrase of the time ``I'll run off a document.'' Bob Morris ported it to
599 the 635 architecture and called the program @code{roff} (an abbreviation
600 of @code{runoff}). It was rewritten as @code{rf} for the @w{PDP-7}
601 (before having @acronym{UNIX}), and at the same time (1969), Doug
602 McIllroy rewrote an extended and simplified version of @code{roff} in
603 the @acronym{BCPL} programming language.
605 @cindex @code{roff}, the program
606 The first version of @acronym{UNIX} was developed on a @w{PDP-7} which
607 was sitting around Bell Labs. In 1971 the developers wanted to get a
608 @w{PDP-11} for further work on the operating system. In order to
609 justify the cost for this system, they proposed that they would
610 implement a document formatting system for the @acronym{AT&T} patents
611 division. This first formatting program was a reimplementation of
612 McIllroy's @code{roff}, written by J.@tie{}F.@tie{}Ossanna.
614 @cindex @code{nroff}, the program
615 When they needed a more flexible language, a new version of @code{roff}
616 called @code{nroff} (``Newer @code{roff}'') was written. It had a much
617 more complicated syntax, but provided the basis for all future versions.
618 When they got a Graphic Systems CAT Phototypesetter, Ossanna wrote a
619 version of @code{nroff} that would drive it. It was dubbed
620 @code{troff}, for ``typesetter @code{roff}'', although many people have
621 speculated that it actually means ``Times @code{roff}'' because of the
622 use of the Times font family in @code{troff} by default. As such, the
623 name @code{troff} is pronounced `@w{t-roff}' rather than `trough'.
625 With @code{troff} came @code{nroff} (they were actually the same program
626 except for some @samp{#ifdef}s), which was for producing output for line
627 printers and character terminals. It understood everything @code{troff}
628 did, and ignored the commands which were not applicable (e.g.@: font
631 Since there are several things which cannot be done easily in
632 @code{troff}, work on several preprocessors began. These programs would
633 transform certain parts of a document into @code{troff}, which made a
634 very natural use of pipes in @acronym{UNIX}.
636 The @code{eqn} preprocessor allowed mathematical formulæ to be
637 specified in a much simpler and more intuitive manner. @code{tbl} is a
638 preprocessor for formatting tables. The @code{refer} preprocessor (and
639 the similar program, @code{bib}) processes citations in a document
640 according to a bibliographic database.
642 Unfortunately, Ossanna's @code{troff} was written in @w{PDP-11} assembly
643 language and produced output specifically for the CAT phototypesetter.
644 He rewrote it in C, although it was now 7000@tie{}lines of uncommented
645 code and still dependent on the CAT. As the CAT became less common, and
646 was no longer supported by the manufacturer, the need to make it support
647 other devices became a priority. However, before this could be done,
648 Ossanna was killed in a car accident.
651 @cindex @code{ditroff}, the program
652 So, Brian Kernighan took on the task of rewriting @code{troff}. The
653 newly rewritten version produced device independent code which was
654 very easy for postprocessors to read and translate to the appropriate
655 printer codes. Also, this new version of @code{troff} (called
656 @code{ditroff} for ``device independent @code{troff}'') had several
657 extensions, which included drawing functions.
659 Due to the additional abilities of the new version of @code{troff},
660 several new preprocessors appeared. The @code{pic} preprocessor
661 provides a wide range of drawing functions. Likewise the @code{ideal}
662 preprocessor did the same, although via a much different paradigm. The
663 @code{grap} preprocessor took specifications for graphs, but, unlike
664 other preprocessors, produced @code{pic} code.
666 James Clark began work on a GNU implementation of @code{ditroff} in
667 early@tie{}1989. The first version, @code{groff}@tie{}0.3.1, was released
668 June@tie{}1990. @code{groff} included:
672 A replacement for @code{ditroff} with many extensions.
675 The @code{soelim}, @code{pic}, @code{tbl}, and @code{eqn} preprocessors.
678 Postprocessors for character devices, @sc{PostScript}, @TeX{} DVI, and
679 X@tie{}Windows. GNU @code{troff} also eliminated the need for a
680 separate @code{nroff} program with a postprocessor which would produce
681 @acronym{ASCII} output.
684 A version of the @file{me} macros and an implementation of the
688 Also, a front-end was included which could construct the, sometimes
689 painfully long, pipelines required for all the post- and preprocessors.
691 Development of GNU @code{troff} progressed rapidly, and saw the
692 additions of a replacement for @code{refer}, an implementation of the
693 @file{ms} and @file{mm} macros, and a program to deduce how to format a
694 document (@code{grog}).
696 It was declared a stable (i.e.@: non-beta) package with the release of
697 version@tie{}1.04 around November@tie{}1991.
699 Beginning in@tie{}1999, @code{groff} has new maintainers (the package was
700 an orphan for a few years). As a result, new features and programs like
701 @code{grn}, a preprocessor for gremlin images, and an output device to
702 produce @acronym{HTML} output have been added.
705 @c =====================================================================
707 @node groff Capabilities, Macro Package Intro, History, Introduction
708 @section @code{groff} Capabilities
709 @cindex @code{groff} capabilities
710 @cindex capabilities of @code{groff}
712 So what exactly is @code{groff} capable of doing? @code{groff} provides
713 a wide range of low-level text formatting operations. Using these, it
714 is possible to perform a wide range of formatting tasks, such as
715 footnotes, table of contents, multiple columns, etc. Here's a list of
716 the most important operations supported by @code{groff}:
720 text filling, adjusting, and centering
729 font and glyph size control
732 vertical spacing (e.g.@: double-spacing)
735 line length and indenting
738 macros, strings, diversions, and traps
744 tabs, leaders, and fields
747 input and output conventions and character translation
750 overstrike, bracket, line drawing, and zero-width functions
753 local horizontal and vertical motions and the width function
759 output line numbering
762 conditional acceptance of input
765 environment switching
768 insertions from the standard input
771 input/output file switching
774 output and error messages
778 @c =====================================================================
780 @node Macro Package Intro, Preprocessor Intro, groff Capabilities, Introduction
781 @section Macro Packages
782 @cindex macro packages
784 Since @code{groff} provides such low-level facilities, it can be quite
785 difficult to use by itself. However, @code{groff} provides a
786 @dfn{macro} facility to specify how certain routine operations
787 (e.g.@tie{}starting paragraphs, printing headers and footers, etc.)@:
788 should be done. These macros can be collected together into a @dfn{macro
789 package}. There are a number of macro packages available; the most
790 common (and the ones described in this manual) are @file{man},
791 @file{mdoc}, @file{me}, @file{ms}, and @file{mm}.
794 @c =====================================================================
796 @node Preprocessor Intro, Output device intro, Macro Package Intro, Introduction
797 @section Preprocessors
798 @cindex preprocessors
800 Although @code{groff} provides most functions needed to format a
801 document, some operations would be unwieldy (e.g.@: to draw pictures).
802 Therefore, programs called @dfn{preprocessors} were written which
803 understand their own language and produce the necessary @code{groff}
804 operations. These preprocessors are able to differentiate their own
805 input from the rest of the document via markers.
807 To use a preprocessor, @acronym{UNIX} pipes are used to feed the output
808 from the preprocessor into @code{groff}. Any number of preprocessors
809 may be used on a given document; in this case, the preprocessors are
810 linked together into one pipeline. However, with @code{groff}, the user
811 does not need to construct the pipe, but only tell @code{groff} what
812 preprocessors to use.
814 @code{groff} currently has preprocessors for producing tables
815 (@code{tbl}), typesetting equations (@code{eqn}), drawing pictures
816 (@code{pic} and @code{grn}), and for processing bibliographies
817 (@code{refer}). An associated program which is useful when dealing with
818 preprocessors is @code{soelim}.
820 A free implementation of @code{grap}, a preprocessor for drawing graphs,
821 can be obtained as an extra package; @code{groff} can use @code{grap}
824 There are other preprocessors in existence, but, unfortunately, no free
825 implementations are available. Among them are preprocessors for drawing
826 mathematical pictures (@code{ideal}) and chemical structures
830 @c =====================================================================
832 @node Output device intro, Credits, Preprocessor Intro, Introduction
833 @section Output Devices
834 @cindex postprocessors
835 @cindex output devices
836 @cindex devices for output
838 @code{groff} actually produces device independent code which may be
839 fed into a postprocessor to produce output for a particular device.
840 Currently, @code{groff} has postprocessors for @sc{PostScript}
841 devices, character terminals, X@tie{}Windows (for previewing), @TeX{}
842 DVI format, HP LaserJet@tie{}4 and Canon LBP printers (which use
843 @acronym{CAPSL}), and @acronym{HTML}.
846 @c =====================================================================
848 @node Credits, , Output device intro, Introduction
852 Large portions of this manual were taken from existing documents, most
853 notably, the manual pages for the @code{groff} package by James Clark,
854 and Eric Allman's papers on the @file{me} macro package.
856 The section on the @file{man} macro package is partly based on
857 Susan@tie{}G.@: Kleinmann's @file{groff_man} manual page written for the
858 Debian GNU/Linux system.
860 Larry Kollar contributed the section in the @file{ms} macro package.
864 @c =====================================================================
865 @c =====================================================================
867 @node Invoking groff, Tutorial for Macro Users, Introduction, Top
868 @chapter Invoking @code{groff}
869 @cindex invoking @code{groff}
870 @cindex @code{groff} invocation
872 This section focuses on how to invoke the @code{groff} front end. This
873 front end takes care of the details of constructing the pipeline among
874 the preprocessors, @code{gtroff} and the postprocessor.
876 It has become a tradition that GNU programs get the prefix @samp{g} to
877 distinguish it from its original counterparts provided by the host (see
878 @ref{Environment}, for more details). Thus, for example, @code{geqn} is
879 GNU @code{eqn}. On operating systems like GNU/Linux or the Hurd, which
880 don't contain proprietary versions of @code{troff}, and on
881 MS-DOS/MS-Windows, where @code{troff} and associated programs are not
882 available at all, this prefix is omitted since GNU @code{troff} is the
883 only used incarnation of @code{troff}. Exception: @samp{groff} is never
884 replaced by @samp{roff}.
886 In this document, we consequently say @samp{gtroff} when talking about
887 the GNU @code{troff} program. All other implementations of @code{troff}
888 are called @acronym{AT&T} @code{troff} which is the common origin of
889 all @code{troff} derivates (with more or less compatible changes).
890 Similarly, we say @samp{gpic}, @samp{geqn}, etc.
895 * Macro Directories::
898 * Invocation Examples::
902 @c =====================================================================
904 @node Groff Options, Environment, Invoking groff, Invoking groff
917 @code{groff} normally runs the @code{gtroff} program and a postprocessor
918 appropriate for the selected device. The default device is @samp{ps}
919 (but it can be changed when @code{groff} is configured and built). It
920 can optionally preprocess with any of @code{gpic}, @code{geqn},
921 @code{gtbl}, @code{ggrn}, @code{grap}, @code{grefer}, or @code{gsoelim}.
923 This section only documents options to the @code{groff} front end. Many
924 of the arguments to @code{groff} are passed on to @code{gtroff},
925 therefore those are also included. Arguments to pre- or postprocessors
926 can be found in @ref{Invoking gpic}, @ref{Invoking geqn}, @ref{Invoking
927 gtbl}, @ref{Invoking ggrn}, @ref{Invoking grefer}, @ref{Invoking
928 gsoelim}, @ref{Invoking grotty}, @ref{Invoking grops}, @ref{Invoking
929 grohtml}, @ref{Invoking grodvi}, @ref{Invoking grolj4}, @ref{Invoking
930 grolbp}, and @ref{Invoking gxditview}.
932 The command line format for @code{groff} is:
935 groff [ -abceghilpstvzCEGNRSUVXZ ] [ -F@var{dir} ] [ -m@var{name} ]
936 [ -T@var{def} ] [ -f@var{fam} ] [ -w@var{name} ] [ -W@var{name} ]
937 [ -M@var{dir} ] [ -d@var{cs} ] [ -r@var{cn} ] [ -n@var{num} ]
938 [ -o@var{list} ] [ -P@var{arg} ] [ -L@var{arg} ] [ -I@var{dir} ]
939 [ @var{files}@dots{} ]
942 The command line format for @code{gtroff} is as follows.
945 gtroff [ -abcivzCERU ] [ -w@var{name} ] [ -W@var{name} ] [ -d@var{cs} ]
946 [ -f@var{fam} ] [ -m@var{name} ] [ -n@var{num} ]
947 [ -o@var{list} ] [ -r@var{cn} ] [ -T@var{name} ]
948 [ -F@var{dir} ] [ -M@var{dir} ] [ @var{files}@dots{} ]
952 Obviously, many of the options to @code{groff} are actually passed on to
955 Options without an argument can be grouped behind a single@tie{}@option{-}.
956 A filename of@tie{}@file{-} denotes the standard input. It is possible to
957 have whitespace between an option and its parameter.
959 The @code{grog} command can be used to guess the correct @code{groff}
960 command to format a file.
962 Here's the description of the command-line options:
964 @cindex command-line options
967 Print a help message.
970 Preprocess with @code{geqn}.
973 Preprocess with @code{gtbl}.
976 Preprocess with @code{ggrn}.
979 Preprocess with @code{grap}.
982 Preprocess with @code{gpic}.
985 Preprocess with @code{gsoelim}.
988 Suppress color output.
991 Preprocess with @code{grefer}. No mechanism is provided for passing
992 arguments to @code{grefer} because most @code{grefer} options have
993 equivalent commands which can be included in the file. @xref{grefer},
998 Note that @code{gtroff} also accepts a @option{-R} option, which is not
999 accessible via @code{groff}. This option prevents the loading of the
1000 @file{troffrc} and @file{troffrc-end} files.
1003 Make programs run by @code{groff} print out their version number.
1006 Print the pipeline on @code{stdout} instead of executing it. If specified
1007 more than once, print the pipeline on @code{stderr} and execute it.
1010 Suppress output from @code{gtroff}. Only error messages are printed.
1013 Do not postprocess the output of @code{gtroff}. Normally @code{groff}
1014 automatically runs the appropriate postprocessor.
1017 Pass @var{arg} to the postprocessor. Each argument should be passed
1018 with a separate @option{-P} option. Note that @code{groff} does not
1019 prepend @samp{-} to @var{arg} before passing it to the postprocessor.
1022 Send the output to a spooler for printing. The command used for this is
1023 specified by the @code{print} command in the device description file
1024 (see @ref{Font Files}, for more info). If not present, @option{-l} is
1028 Pass @var{arg} to the spooler. Each argument should be passed with a
1029 separate @option{-L} option. Note that @code{groff} does not prepend
1030 a @samp{-} to @var{arg} before passing it to the postprocessor.
1031 If the @code{print} keyword in the device description file is missing,
1032 @option{-L} is ignored.
1035 Prepare output for device @var{dev}. The default device is @samp{ps},
1036 unless changed when @code{groff} was configured and built. The
1037 following are the output devices currently available:
1041 For @sc{PostScript} printers and previewers.
1044 For @TeX{} DVI format.
1047 For a 75@dmn{dpi} X11 previewer.
1050 For a 75@dmn{dpi} X11 previewer with a 12@dmn{pt} base font in the
1054 For a 100@dmn{dpi} X11 previewer.
1057 For a 100@dmn{dpi} X11 previewer with a 12@dmn{pt} base font in the
1061 @cindex encoding, output, @acronym{ASCII}
1062 @cindex @acronym{ASCII}, output encoding
1063 @cindex output encoding, @acronym{ASCII}
1064 For typewriter-like devices using the (7-bit) @acronym{ASCII}
1068 @cindex encoding, output, @w{latin-1} (ISO @w{8859-1})
1069 @cindex @w{latin-1} (ISO @w{8859-1}), output encoding
1070 @cindex ISO @w{8859-1} (@w{latin-1}), output encoding
1071 @cindex output encoding, @w{latin-1} (ISO @w{8859-1})
1072 For typewriter-like devices that support the @w{Latin-1}
1073 (ISO@tie{}@w{8859-1}) character set.
1076 @cindex encoding, output, @w{utf-8}
1077 @cindex @w{utf-8}, output encoding
1078 @cindex output encoding, @w{utf-8}
1079 For typewriter-like devices which use the Unicode (ISO@tie{}10646)
1080 character set with @w{UTF-8} encoding.
1083 @cindex encoding, output, @acronym{EBCDIC}
1084 @cindex @acronym{EBCDIC}, output encoding
1085 @cindex output encoding, @acronym{EBCDIC}
1086 @cindex encoding, output, cp1047
1087 @cindex cp1047, output encoding
1088 @cindex output encoding, cp1047
1089 @cindex IBM cp1047 output encoding
1090 For typewriter-like devices which use the @acronym{EBCDIC} encoding IBM
1094 For HP LaserJet4-compatible (or other PCL5-compatible) printers.
1097 For Canon @acronym{CAPSL} printers (@w{LBP-4} and @w{LBP-8} series laser
1101 @pindex post-grohtml
1102 @cindex @code{grohtml}, the program
1104 To produce @acronym{HTML} output. Note that the @acronym{HTML} driver
1105 consists of two parts, a preprocessor (@code{pre-grohtml}) and a
1106 postprocessor (@code{post-grohtml}).
1109 @cindex output device name string register (@code{.T})
1110 @cindex output device usage number register (@code{.T})
1111 The predefined @code{gtroff} string register @code{.T} contains the
1112 current output device; the read-only number register @code{.T} is set
1113 to@tie{}1 if this option is used (which is always true if @code{groff} is
1114 used to call @code{gtroff}). @xref{Built-in Registers}.
1116 The postprocessor to be used for a device is specified by the
1117 @code{postpro} command in the device description file. (@xref{Font
1118 Files}, for more info.) This can be overridden with the @option{-X}
1122 Preview with @code{gxditview} instead of using the usual postprocessor.
1123 This is unlikely to produce good results except with @option{-Tps}.
1125 Note that this is not the same as using @option{-TX75} or
1126 @option{-TX100} to view a document with @code{gxditview}: The former
1127 uses the metrics of the specified device, whereas the latter uses
1128 X-specific fonts and metrics.
1131 Don't allow newlines with @code{eqn} delimiters. This is the same as
1132 the @option{-N} option in @code{geqn}.
1135 @cindex @code{open} request, and safer mode
1136 @cindex @code{opena} request, and safer mode
1137 @cindex @code{pso} request, and safer mode
1138 @cindex @code{sy} request, and safer mode
1139 @cindex @code{pi} request, and safer mode
1142 Safer mode. Pass the @option{-S} option to @code{gpic} and disable the
1143 @code{open}, @code{opena}, @code{pso}, @code{sy}, and @code{pi}
1144 requests. For security reasons, this is enabled by default.
1147 @cindex mode, unsafe
1149 Unsafe mode. This enables the @code{open}, @code{opena}, @code{pso},
1150 @code{sy}, and @code{pi} requests.
1153 @cindex @acronym{ASCII} approximation output register (@code{.A})
1154 Generate an @acronym{ASCII} approximation of the typeset output. The
1155 read-only register @code{.A} is then set to@tie{}1. @xref{Built-in
1156 Registers}. A typical example is
1159 groff -a -man -Tdvi troff.man | less
1163 which shows how lines are broken for the DVI device. Note that this
1164 option is rather useless today since graphic output devices are
1165 available virtually everywhere.
1168 Print a backtrace with each warning or error message. This backtrace
1169 should help track down the cause of the error. The line numbers given
1170 in the backtrace may not always be correct: @code{gtroff} can get
1171 confused by @code{as} or @code{am} requests while counting line numbers.
1174 Read the standard input after all the named input files have been
1178 Enable warning @var{name}. Available warnings are described in
1179 @ref{Debugging}. Multiple @option{-w} options are allowed.
1182 Inhibit warning @var{name}. Multiple @option{-W} options are allowed.
1185 Inhibit all error messages.
1188 Enable compatibility mode. @xref{Implementation Differences}, for the
1189 list of incompatibilities between @code{groff} and @acronym{AT&T}
1192 @item -d@var{c}@var{s}
1193 @itemx -d@var{name}=@var{s}
1194 Define @var{c} or @var{name} to be a string@tie{}@var{s}. @var{c}@tie{}must
1195 be a one-letter name; @var{name} can be of arbitrary length. All string
1196 assignments happen before loading any macro file (including the start-up
1200 Use @var{fam} as the default font family. @xref{Font Families}.
1203 Read in the file @file{@var{name}.tmac}. Normally @code{groff} searches
1204 for this in its macro directories. If it isn't found, it tries
1205 @file{tmac.@var{name}} (searching in the same directories).
1208 Number the first page @var{num}.
1211 @cindex print current page register (@code{.P})
1212 Output only pages in @var{list}, which is a comma-separated list of page
1213 ranges; @samp{@var{n}} means print page@tie{}@var{n}, @samp{@var{m}-@var{n}}
1214 means print every page between @var{m} and@tie{}@var{n}, @samp{-@var{n}}
1215 means print every page up to@tie{}@var{n}, @samp{@var{n}-} means print every
1216 page beginning with@tie{}@var{n}. @code{gtroff} exits after printing the
1217 last page in the list. All the ranges are inclusive on both ends.
1219 Within @code{gtroff}, this information can be extracted with the
1220 @samp{.P} register. @xref{Built-in Registers}.
1222 If your document restarts page numbering at the beginning of each
1223 chapter, then @code{gtroff} prints the specified page range for each
1226 @item -r@var{c}@var{n}
1227 @itemx -r@var{name}=@var{n}
1228 Set number register@tie{}@var{c} or @var{name} to the value@tie{}@var{n}.
1229 @var{c}@tie{}must be a one-letter name; @var{name} can be of arbitrary
1230 length. @var{n}@tie{}can be any @code{gtroff} numeric expression. All
1231 register assignments happen before loading any macro file (including
1235 Search @file{@var{dir}} for subdirectories @file{dev@var{name}}
1236 (@var{name} is the name of the device), for the @file{DESC} file, and
1237 for font files before looking in the standard directories (@pxref{Font
1238 Directories}). This option is passed to all pre- and postprocessors
1239 using the @env{GROFF_FONT_PATH} environment variable.
1242 Search directory @file{@var{dir}} for macro files before the standard
1243 directories (@pxref{Macro Directories}).
1246 This option may be used to specify a directory to search for files.
1247 It is passed to the following programs:
1251 @code{gsoelim} (see @ref{gsoelim} for more details);
1252 it also implies @code{groff}'s @option{-s} option.
1255 @code{gtroff}; it is used to search files named in the @code{psbb} and
1259 @code{grops}; it is used to search files named in the
1260 @w{@code{\X'ps: import}} and @w{@code{\X'ps: file}} escapes.
1263 The current directory is always searched first. This option may be specified
1264 more than once; the directories will be searched in the order specified. No
1265 directory search is performed for files specified using an absolute path.
1269 @c =====================================================================
1271 @node Environment, Macro Directories, Groff Options, Invoking groff
1272 @section Environment
1273 @cindex environment variables
1274 @cindex variables in environment
1276 There are also several environment variables (of the operating system,
1277 not within @code{gtroff}) which can modify the behavior of @code{groff}.
1280 @item GROFF_COMMAND_PREFIX
1281 @tindex GROFF_COMMAND_PREFIX@r{, environment variable}
1282 @cindex command prefix
1283 @cindex prefix, for commands
1284 If this is set to@tie{}@var{X}, then @code{groff} runs @code{@var{X}troff}
1285 instead of @code{gtroff}. This also applies to @code{tbl}, @code{pic},
1286 @code{eqn}, @code{grn}, @code{refer}, and @code{soelim}. It does not
1287 apply to @code{grops}, @code{grodvi}, @code{grotty}, @code{pre-grohtml},
1288 @code{post-grohtml}, @code{grolj4}, and @code{gxditview}.
1290 The default command prefix is determined during the installation process.
1291 If a non-GNU troff system is found, prefix @samp{g} is used, none
1294 @item GROFF_TMAC_PATH
1295 @tindex GROFF_TMAC_PATH@r{, environment variable}
1296 A colon-separated list of directories in which to search for macro files
1297 (before the default directories are tried). @xref{Macro Directories}.
1299 @item GROFF_TYPESETTER
1300 @tindex GROFF_TYPESETTER@r{, environment variable}
1301 The default output device.
1303 @item GROFF_FONT_PATH
1304 @tindex GROFF_FONT_PATH@r{, environment variable}
1305 A colon-separated list of directories in which to search for the
1306 @code{dev}@var{name} directory (before the default directories are
1307 tried). @xref{Font Directories}.
1309 @item GROFF_BIN_PATH
1310 @tindex GROFF_BIN_PATH@r{, environment variable}
1311 This search path, followed by @code{PATH}, is used for commands executed
1315 @tindex GROFF_TMPDIR@r{, environment variable}
1316 @tindex TMPDIR@r{, environment variable}
1317 The directory in which @code{groff} creates temporary files. If this is
1318 not set and @env{TMPDIR} is set, temporary files are created in that
1319 directory. Otherwise temporary files are created in a system-dependent
1320 default directory (on Unix and GNU/Linux systems, this is usually
1321 @file{/tmp}). @code{grops}, @code{grefer}, @code{pre-grohtml}, and
1322 @code{post-grohtml} can create temporary files in this directory.
1325 Note that MS-DOS and MS-Windows ports of @code{groff} use semi-colons,
1326 rather than colons, to separate the directories in the lists described
1330 @c =====================================================================
1332 @node Macro Directories, Font Directories, Environment, Invoking groff
1333 @section Macro Directories
1334 @cindex macro directories
1335 @cindex directories for macros
1336 @cindex searching macros
1337 @cindex macros, searching
1339 All macro file names must be named @code{@var{name}.tmac} or
1340 @code{tmac.@var{name}} to make the @option{-m@var{name}} command line
1341 option work. The @code{mso} request doesn't have this restriction; any
1342 file name can be used, and @code{gtroff} won't try to append or prepend
1343 the @samp{tmac} string.
1345 @cindex tmac, directory
1346 @cindex directory, for tmac files
1348 @cindex path, for tmac files
1349 @cindex searching macro files
1350 @cindex macro files, searching
1351 @cindex files, macro, searching
1352 Macro files are kept in the @dfn{tmac directories}, all of which
1353 constitute the @dfn{tmac path}. The elements of the search path for
1354 macro files are (in that order):
1358 The directories specified with @code{gtroff}'s or @code{groff}'s
1359 @option{-M} command line option.
1362 @tindex GROFF_TMAC_PATH@r{, environment variable}
1363 The directories given in the @env{GROFF_TMAC_PATH} environment
1370 @cindex mode, unsafe
1371 @cindex current directory
1372 @cindex directory, current
1373 The current directory (only if in unsafe mode using the @option{-U}
1374 command line switch).
1377 @cindex home directory
1378 @cindex directory, home
1382 @cindex site-specific directory
1383 @cindex directory, site-specific
1384 @cindex platform-specific directory
1385 @cindex directory, platform-specific
1386 A platform-dependent directory, a site-specific (platform-independent)
1387 directory, and the main tmac directory; the default locations are
1390 /usr/local/lib/groff/site-tmac
1391 /usr/local/share/groff/site-tmac
1392 /usr/local/share/groff/1.18.2/tmac
1396 assuming that the version of @code{groff} is 1.18.2, and the installation
1397 prefix was @file{/usr/local}. It is possible to fine-tune those
1398 directories during the installation process.
1402 @c =====================================================================
1404 @node Font Directories, Paper Size, Macro Directories, Invoking groff
1405 @section Font Directories
1406 @cindex font directories
1407 @cindex directories for fonts
1408 @cindex searching fonts
1409 @cindex fonts, searching
1411 Basically, there is no restriction how font files for @code{groff} are
1412 named and how long font names are; however, to make the font family
1413 mechanism work (@pxref{Font Families}), fonts within a family should
1414 start with the family name, followed by the shape. For example, the
1415 Times family uses @samp{T} for the family name and @samp{R}, @samp{B},
1416 @samp{I}, and @samp{BI} to indicate the shapes `roman', `bold',
1417 `italic', and `bold italic', respectively. Thus the final font names
1418 are @samp{TR}, @samp{TB}, @samp{TI}, and @samp{TBI}.
1421 @cindex path, for font files
1422 All font files are kept in the @dfn{font directories} which constitute
1423 the @dfn{font path}. The file search functions will always append the
1424 directory @code{dev}@var{name}, where @var{name} is the name of the
1425 output device. Assuming, say, DVI output, and @file{/foo/bar} as a
1426 font directory, the font files for @code{grodvi} must be in
1427 @file{/foo/bar/devdvi}.
1429 The elements of the search path for font files are (in that order):
1433 The directories specified with @code{gtroff}'s or @code{groff}'s
1434 @option{-F} command line option. All device drivers and some
1435 preprocessors also have this option.
1438 @tindex GROFF_FONT_PATH@r{, environment variable}
1439 The directories given in the @env{GROFF_FONT_PATH} environment
1443 @cindex site-specific directory
1444 @cindex directory, site-specific
1445 A site-specific directory and the main font directory; the default
1449 /usr/local/share/groff/site-font
1450 /usr/local/share/groff/1.18.2/font
1454 assuming that the version of @code{groff} is 1.18.2, and the installation
1455 prefix was @file{/usr/local}. It is possible to fine-tune those
1456 directories during the installation process.
1460 @c =====================================================================
1462 @node Paper Size, Invocation Examples, Font Directories, Invoking groff
1466 @cindex landscape page orientation
1467 @cindex orientation, landscape
1468 @cindex page orientation, landscape
1470 In groff, the page size for @code{gtroff} and for output devices are
1471 handled separately. @xref{Page Layout}, for vertical manipulation of
1472 the page size. @xref{Line Layout}, for horizontal changes.
1474 A default paper size can be set in the device's @file{DESC} file. Most
1475 output devices also have a command line option @option{-p} to override
1476 the default paper size and option @option{-l} to use landscape
1477 orientation. @xref{DESC File Format}, for a description of the
1478 @code{papersize} keyword which takes the same argument as @option{-p}.
1480 @pindex papersize.tmac
1482 A convenient shorthand to set a particular paper size for @code{gtroff}
1483 is command line option @option{-dpaper=@var{size}}. This defines string
1484 @code{paper} which is processed in file @file{papersize.tmac} (loaded in
1485 the start-up file @file{troffrc} by default). Possible values for
1486 @var{size} are the same as the predefined values for the
1487 @code{papersize} keyword (but only in lowercase) except
1488 @code{a7}-@code{d7}. An appended @samp{l} (ell) character denotes
1489 landscape orientation.
1491 For example, use the following for PS output on A4 paper in landscape
1495 groff -Tps -dpaper=a4l -P-pa4 -P-l -ms foo.ms > foo.ps
1498 Note that it is up to the particular macro package to respect default
1499 page dimensions set in this way (most do).
1502 @c =====================================================================
1504 @node Invocation Examples, , Paper Size, Invoking groff
1505 @section Invocation Examples
1506 @cindex invocation examples
1507 @cindex examples of invocation
1509 This section lists several common uses of @code{groff} and the
1510 corresponding command lines.
1517 This command processes @file{file} without a macro package or a
1518 preprocessor. The output device is the default, @samp{ps}, and the
1519 output is sent to @code{stdout}.
1522 groff -t -mandoc -Tascii file | less
1526 This is basically what a call to the @code{man} program does.
1527 @code{gtroff} processes the manual page @file{file} with the
1528 @file{mandoc} macro file (which in turn either calls the @file{man} or
1529 the @file{mdoc} macro package), using the @code{tbl} preprocessor and
1530 the @acronym{ASCII} output device. Finally, the @code{less} pager
1531 displays the result.
1538 Preview @file{file} with @code{gxditview}, using the @file{me} macro
1539 package. Since no @option{-T} option is specified, use the default
1540 device (@samp{ps}). Note that you can either say @w{@samp{-m me}} or
1541 @w{@samp{-me}}; the latter is an anachronism from the early days of
1542 @acronym{UNIX}.@footnote{The same is true for the other main macro
1543 packages that come with @code{groff}: @file{man}, @file{mdoc},
1544 @file{ms}, @file{mm}, and @file{mandoc}. This won't work in general;
1545 for example, to load @file{trace.tmac}, either @samp{-mtrace} or
1546 @w{@samp{-m trace}} must be used.}
1549 groff -man -rD1 -z file
1553 Check @file{file} with the @file{man} macro package, forcing
1554 double-sided printing -- don't produce any output.
1560 @c ---------------------------------------------------------------------
1562 @node grog, , Invocation Examples, Invocation Examples
1563 @subsection @code{grog}
1566 @code{grog} reads files, guesses which of the @code{groff} preprocessors
1567 and/or macro packages are required for formatting them, and prints the
1568 @code{groff} command including those options on the standard output. It
1569 generates one or more of the options @option{-e}, @option{-man},
1570 @option{-me}, @option{-mm}, @option{-mom}, @option{-ms}, @option{-mdoc},
1571 @option{-mdoc-old}, @option{-p}, @option{-R}, @option{-g}, @option{-G},
1572 @option{-s}, and @option{-t}.
1574 A special file name@tie{}@file{-} refers to the standard input. Specifying
1575 no files also means to read the standard input. Any specified options
1576 are included in the printed command. No space is allowed between
1577 options and their arguments. The only options recognized are
1578 @option{-C} (which is also passed on) to enable compatibility mode, and
1579 @option{-v} to print the version number and exit.
1588 guesses the appropriate command to print @file{paper.ms} and then prints
1589 it to the command line after adding the @option{-Tdvi} option. For
1590 direct execution, enclose the call to @code{grog} in backquotes at the
1591 @acronym{UNIX} shell prompt:
1594 `grog -Tdvi paper.ms` > paper.dvi
1598 As seen in the example, it is still necessary to redirect the output to
1599 something meaningful (i.e.@: either a file or a pager program like
1604 @c =====================================================================
1605 @c =====================================================================
1607 @node Tutorial for Macro Users, Macro Packages, Invoking groff, Top
1608 @chapter Tutorial for Macro Users
1609 @cindex tutorial for macro users
1610 @cindex macros, tutorial for users
1611 @cindex user's tutorial for macros
1612 @cindex user's macro tutorial
1614 Most users tend to use a macro package to format their papers. This
1615 means that the whole breadth of @code{groff} is not necessary for most
1616 people. This chapter covers the material needed to efficiently use a
1625 @c =====================================================================
1627 @node Basics, Common Features, Tutorial for Macro Users, Tutorial for Macro Users
1629 @cindex basics of macros
1630 @cindex macro basics
1632 This section covers some of the basic concepts necessary to understand
1633 how to use a macro package.@footnote{This section is derived from
1634 @cite{Writing Papers with nroff using -me} by Eric P.@tie{}Allman.}
1635 References are made throughout to more detailed information, if desired.
1637 @code{gtroff} reads an input file prepared by the user and outputs a
1638 formatted document suitable for publication or framing. The input
1639 consists of text, or words to be printed, and embedded commands
1640 (@dfn{requests} and @dfn{escapes}), which tell @code{gtroff} how to
1641 format the output. For more detail on this, see @ref{Embedded
1644 The word @dfn{argument} is used in this chapter to mean a word or number
1645 which appears on the same line as a request, and which modifies the
1646 meaning of that request. For example, the request
1653 spaces one line, but
1660 spaces four lines. The number@tie{}4 is an argument to the @code{sp}
1661 request which says to space four lines instead of one. Arguments are
1662 separated from the request and from each other by spaces (@emph{no}
1663 tabs). More details on this can be found in @ref{Request and Macro
1666 The primary function of @code{gtroff} is to collect words from input
1667 lines, fill output lines with those words, justify the right-hand margin
1668 by inserting extra spaces in the line, and output the result. For
1676 Four score and seven
1681 is read, packed onto output lines, and justified to produce:
1684 Now is the time for all good men to come to the aid of their party.
1685 Four score and seven years ago, etc.
1690 Sometimes a new output line should be started even though the current
1691 line is not yet full; for example, at the end of a paragraph. To do
1692 this it is possible to cause a @dfn{break}, which starts a new output
1693 line. Some requests cause a break automatically, as normally do blank
1694 input lines and input lines beginning with a space.
1696 Not all input lines are text to be formatted. Some input lines are
1697 requests which describe how to format the text. Requests always have a
1698 period (@samp{.}) or an apostrophe (@samp{'}) as the first character of
1701 The text formatter also does more complex things, such as automatically
1702 numbering pages, skipping over page boundaries, putting footnotes in the
1703 correct place, and so forth.
1705 Here are a few hints for preparing text for input to @code{gtroff}.
1709 First, keep the input lines short. Short input lines are easier to
1710 edit, and @code{gtroff} packs words onto longer lines anyhow.
1713 In keeping with this, it is helpful to begin a new line after every
1714 comma or phrase, since common corrections are to add or delete sentences
1718 End each sentence with two spaces -- or better, start each sentence on a
1719 new line. @code{gtroff} recognizes characters that usually end a
1720 sentence, and inserts sentence space accordingly.
1723 Do not hyphenate words at the end of lines -- @code{gtroff} is smart
1724 enough to hyphenate words as needed, but is not smart enough to take
1725 hyphens out and join a word back together. Also, words such as
1726 ``mother-in-law'' should not be broken over a line, since then a space
1727 can occur where not wanted, such as ``@w{mother- in}-law''.
1730 @cindex double-spacing (@code{ls})
1732 @code{gtroff} double-spaces output text automatically if you use the
1733 request @w{@samp{.ls 2}}. Reactivate single-spaced mode by typing
1734 @w{@samp{.ls 1}}.@footnote{If you need finer granularity of the
1735 vertical space, use the @code{pvs} request (@pxref{Changing Type
1738 A number of requests allow to change the way the output looks,
1739 sometimes called the @dfn{layout} of the output page. Most of these
1740 requests adjust the placing of @dfn{whitespace} (blank lines or
1743 @cindex new page (@code{bp})
1744 The @code{bp} request starts a new page, causing a line break.
1746 @cindex blank line (@code{sp})
1747 @cindex empty line (@code{sp})
1748 @cindex line, empty (@code{sp})
1749 The request @w{@samp{.sp @var{N}}} leaves @var{N}@tie{}lines of blank
1750 space. @var{N}@tie{}can be omitted (meaning skip a single line) or can
1751 be of the form @var{N}i (for @var{N}@tie{}inches) or @var{N}c (for
1752 @var{N}@tie{}centimeters). For example, the input:
1756 My thoughts on the subject
1761 leaves one and a half inches of space, followed by the line ``My
1762 thoughts on the subject'', followed by a single blank line (more
1763 measurement units are available, see @ref{Measurements}).
1765 @cindex centering lines (@code{ce})
1766 @cindex lines, centering (@code{ce})
1767 Text lines can be centered by using the @code{ce} request. The line
1768 after @code{ce} is centered (horizontally) on the page. To center more
1769 than one line, use @w{@samp{.ce @var{N}}} (where @var{N} is the number
1770 of lines to center), followed by the @var{N}@tie{}lines. To center many
1771 lines without counting them, type:
1780 The @w{@samp{.ce 0}} request tells @code{groff} to center zero more
1781 lines, in other words, stop centering.
1783 @cindex line break (@code{br})
1784 @cindex break (@code{br})
1785 All of these requests cause a break; that is, they always start a new
1786 line. To start a new line without performing any other action, use
1790 @c =====================================================================
1792 @node Common Features, , Basics, Tutorial for Macro Users
1793 @section Common Features
1794 @cindex common features
1795 @cindex features, common
1797 @code{gtroff} provides very low-level operations for formatting a
1798 document. There are many common routine operations which are done in
1799 all documents. These common operations are written into @dfn{macros}
1800 and collected into a @dfn{macro package}.
1802 All macro packages provide certain common capabilities which fall into
1803 the following categories.
1807 * Sections and Chapters::
1808 * Headers and Footers::
1809 * Page Layout Adjustment::
1811 * Footnotes and Annotations::
1812 * Table of Contents::
1815 * Multiple Columns::
1816 * Font and Size Changes::
1817 * Predefined Strings::
1818 * Preprocessor Support::
1819 * Configuration and Customization::
1822 @c ---------------------------------------------------------------------
1824 @node Paragraphs, Sections and Chapters, Common Features, Common Features
1825 @subsection Paragraphs
1828 One of the most common and most used capability is starting a
1829 paragraph. There are a number of different types of paragraphs, any
1830 of which can be initiated with macros supplied by the macro package.
1831 Normally, paragraphs start with a blank line and the first line
1832 indented, like the text in this manual. There are also block style
1833 paragraphs, which omit the indentation:
1836 Some men look at constitutions with sanctimonious
1837 reverence, and deem them like the ark of the covenant, too
1838 sacred to be touched.
1842 And there are also indented paragraphs which begin with a tag or label
1843 at the margin and the remaining text indented.
1846 one This is the first paragraph. Notice how the first
1847 line of the resulting paragraph lines up with the
1848 other lines in the paragraph.
1852 This paragraph had a long label. The first
1853 character of text on the first line does not line up
1854 with the text on second and subsequent lines,
1855 although they line up with each other.
1858 A variation of this is a bulleted list.
1861 . Bulleted lists start with a bullet. It is possible
1862 to use other glyphs instead of the bullet. In nroff
1863 mode using the ASCII character set for output, a dot
1864 is used instead of a real bullet.
1867 @c ---------------------------------------------------------------------
1869 @node Sections and Chapters, Headers and Footers, Paragraphs, Common Features
1870 @subsection Sections and Chapters
1872 Most macro packages supply some form of section headers. The simplest
1873 kind is simply the heading on a line by itself in bold type. Others
1874 supply automatically numbered section heading or different heading
1875 styles at different levels. Some, more sophisticated, macro packages
1876 supply macros for starting chapters and appendices.
1878 @c ---------------------------------------------------------------------
1880 @node Headers and Footers, Page Layout Adjustment, Sections and Chapters, Common Features
1881 @subsection Headers and Footers
1883 Every macro package gives some way to manipulate the @dfn{headers} and
1884 @dfn{footers} (also called @dfn{titles}) on each page. This is text
1885 put at the top and bottom of each page, respectively, which contain
1886 data like the current page number, the current chapter title, and so
1887 on. Its appearance is not affected by the running text. Some packages
1888 allow for different ones on the even and odd pages (for material printed
1891 The titles are called @dfn{three-part titles}, that is, there is a
1892 left-justified part, a centered part, and a right-justified part. An
1893 automatically generated page number may be put in any of these fields
1894 with the @samp{%} character (see @ref{Page Layout}, for more details).
1896 @c ---------------------------------------------------------------------
1898 @node Page Layout Adjustment, Displays, Headers and Footers, Common Features
1899 @subsection Page Layout
1901 Most macro packages let the user specify top and bottom margins and
1902 other details about the appearance of the printed pages.
1904 @c ---------------------------------------------------------------------
1906 @node Displays, Footnotes and Annotations, Page Layout Adjustment, Common Features
1907 @subsection Displays
1910 @dfn{Displays} are sections of text to be set off from the body of
1911 the paper. Major quotes, tables, and figures are types of displays, as
1912 are all the examples used in this document.
1914 @cindex quotes, major
1915 @cindex major quotes
1916 @dfn{Major quotes} are quotes which are several lines long, and hence
1917 are set in from the rest of the text without quote marks around them.
1920 A @dfn{list} is an indented, single-spaced, unfilled display. Lists
1921 should be used when the material to be printed should not be filled and
1922 justified like normal text, such as columns of figures or the examples
1926 A @dfn{keep} is a display of lines which are kept on a single page if
1927 possible. An example for a keep might be a diagram. Keeps differ from
1928 lists in that lists may be broken over a page boundary whereas keeps are
1931 @cindex keep, floating
1932 @cindex floating keep
1933 @dfn{Floating keeps} move relative to the text. Hence, they are good for
1934 things which are referred to by name, such as ``See figure@tie{}3''. A
1935 floating keep appears at the bottom of the current page if it fits;
1936 otherwise, it appears at the top of the next page. Meanwhile, the
1937 surrounding text `flows' around the keep, thus leaving no blank areas.
1939 @c ---------------------------------------------------------------------
1941 @node Footnotes and Annotations, Table of Contents, Displays, Common Features
1942 @subsection Footnotes and Annotations
1946 There are a number of requests to save text for later printing.
1948 @dfn{Footnotes} are printed at the bottom of the current page.
1950 @cindex delayed text
1951 @dfn{Delayed text} is very similar to a footnote except that it is
1952 printed when called for explicitly. This allows a list of references to
1953 appear (for example) at the end of each chapter, as is the convention in
1956 Most macro packages which supply this functionality also supply a means
1957 of automatically numbering either type of annotation.
1959 @c ---------------------------------------------------------------------
1961 @node Table of Contents, Indices, Footnotes and Annotations, Common Features
1962 @subsection Table of Contents
1963 @cindex table of contents
1964 @cindex contents, table of
1966 @dfn{Tables of contents} are a type of delayed text having a tag
1967 (usually the page number) attached to each entry after a row of dots.
1968 The table accumulates throughout the paper until printed, usually after
1969 the paper has ended. Many macro packages provide the ability to have
1970 several tables of contents (e.g.@: a standard table of contents, a list
1973 @c ---------------------------------------------------------------------
1975 @node Indices, Paper Formats, Table of Contents, Common Features
1977 @cindex index, in macro package
1979 While some macro packages use the term @dfn{index}, none actually
1980 provide that functionality. The facilities they call indices are
1981 actually more appropriate for tables of contents.
1984 To produce a real index in a document, external tools like the
1985 @code{makeindex} program are necessary.
1987 @c ---------------------------------------------------------------------
1989 @node Paper Formats, Multiple Columns, Indices, Common Features
1990 @subsection Paper Formats
1991 @cindex paper formats
1993 Some macro packages provide stock formats for various kinds of
1994 documents. Many of them provide a common format for the title and
1995 opening pages of a technical paper. The @file{mm} macros in particular
1996 provide formats for letters and memoranda.
1998 @c ---------------------------------------------------------------------
2000 @node Multiple Columns, Font and Size Changes, Paper Formats, Common Features
2001 @subsection Multiple Columns
2003 Some macro packages (but not @file{man}) provide the ability to have two
2004 or more columns on a page.
2006 @c ---------------------------------------------------------------------
2008 @node Font and Size Changes, Predefined Strings, Multiple Columns, Common Features
2009 @subsection Font and Size Changes
2011 The built-in font and size functions are not always intuitive, so all
2012 macro packages provide macros to make these operations simpler.
2014 @c ---------------------------------------------------------------------
2016 @node Predefined Strings, Preprocessor Support, Font and Size Changes, Common Features
2017 @subsection Predefined Strings
2019 Most macro packages provide various predefined strings for a variety of
2020 uses; examples are sub- and superscripts, printable dates, quotes and
2021 various special characters.
2023 @c ---------------------------------------------------------------------
2025 @node Preprocessor Support, Configuration and Customization, Predefined Strings, Common Features
2026 @subsection Preprocessor Support
2028 All macro packages provide support for various preprocessors and may
2029 extend their functionality.
2031 For example, all macro packages mark tables (which are processed with
2032 @code{gtbl}) by placing them between @code{TS} and @code{TE} macros.
2033 The @file{ms} macro package has an option, @samp{.TS@tie{}H}, that prints
2034 a caption at the top of a new page (when the table is too long to fit on
2037 @c ---------------------------------------------------------------------
2039 @node Configuration and Customization, , Preprocessor Support, Common Features
2040 @subsection Configuration and Customization
2042 Some macro packages provide means of customizing many of the details of
2043 how the package behaves. This ranges from setting the default type size
2044 to changing the appearance of section headers.
2048 @c =====================================================================
2049 @c =====================================================================
2051 @node Macro Packages, gtroff Reference, Tutorial for Macro Users, Top
2052 @chapter Macro Packages
2053 @cindex macro packages
2054 @cindex packages, macros
2056 This chapter documents the main macro packages that come with
2059 Different main macro packages can't be used at the same time; for example
2062 groff -m man foo.man -m ms bar.doc
2066 doesn't work. Note that option arguments are processed before non-option
2067 arguments; the above (failing) sample is thus reordered to
2070 groff -m man -m ms foo.man bar.doc
2082 @c =====================================================================
2084 @node man, mdoc, Macro Packages, Macro Packages
2086 @cindex manual pages
2090 @pindex man-old.tmac
2092 This is the most popular and probably the most important macro package
2093 of @code{groff}. It is easy to use, and a vast majority of manual pages
2100 * Miscellaneous man macros::
2101 * Predefined man strings::
2102 * Preprocessors in man pages::
2103 * Optional man extensions::
2106 @c ---------------------------------------------------------------------
2108 @node Man options, Man usage, man, man
2111 The command line format for using the @file{man} macros with
2115 groff -m man [ -rLL=@var{length} ] [ -rLT=@var{length} ] [ -rFT=@var{dist} ]
2116 [ -rcR=1 ] [ -rC1 ] [ -rD1 ] [-rHY=@var{flags} ]
2117 [ -rP@var{nnn} ] [ -rS@var{xx} ] [ -rX@var{nnn} ]
2118 [ -rIN=@var{length} ] [ -rSN=@var{length} ] [ @var{files}@dots{} ]
2122 It is possible to use @samp{-man} instead of @w{@samp{-m man}}.
2126 This option (the default if a TTY output device is used) creates a
2127 single, very long page instead of multiple pages. Use @code{-rcR=0}
2131 If more than one manual page is given on the command line, number the
2132 pages continuously, rather than starting each at@tie{}1.
2135 Double-sided printing. Footers for even and odd pages are formatted
2138 @item -rFT=@var{dist}
2139 Set the position of the footer text to @var{dist}. If positive, the
2140 distance is measured relative to the top of the page, otherwise it is
2141 relative to the bottom. The default is @minus{}0.5@dmn{i}.
2143 @item -rHY=@var{flags}
2144 Set hyphenation flags. Possible values are 1@tie{}to hyphenate without
2145 restrictions, 2@tie{} to not hyphenate the last word on a page,
2146 4@tie{}to not hyphenate the last two characters of a word, and
2147 8@tie{}to not hyphenate the first two characters of a word. These
2148 values are additive; the default is@tie{}14.
2150 @item -rIN=@var{length}
2151 Set the body text indent to @var{length}.
2152 If not specified, the indent defaults to 7@dmn{n}
2153 (7@tie{}characters) in nroff mode and 7.2@dmn{n} otherwise.
2154 For nroff, this value should always be an integer multiple of unit @samp{n}
2155 to get consistent indentation.
2157 @item -rLL=@var{length}
2158 Set line length to @var{length}. If not specified, the line length
2159 defaults to 78@tie{}en in nroff mode (this is 78@tie{}characters per
2160 line) and 6.5@tie{}inch otherwise.
2162 @item -rLT=@var{length}
2163 Set title length to @var{length}. If not specified, the title length
2164 defaults to the line length.
2167 Page numbering starts with @var{nnn} rather than with@tie{}1.
2170 Use @var{xx} (which can be 10, 11, or@tie{}12@dmn{pt}) as the base
2171 document font size instead of the default value of@tie{}10@dmn{pt}.
2173 @item -rSN=@var{length}
2174 Set the indent for sub-subheadings to @var{length}.
2175 If not specified, the indent defaults to 3@dmn{n}.
2178 After page @var{nnn}, number pages as @var{nnn}a, @var{nnn}b,
2179 @var{nnn}c, etc. For example, the option @option{-rX2} produces the
2180 following page numbers: 1, 2, 2a, 2b, 2c, etc.
2183 @c ---------------------------------------------------------------------
2185 @node Man usage, Man font macros, Man options, man
2187 @cindex @code{man} macros
2188 @cindex macros for manual pages [@code{man}]
2191 This section describes the available macros for manual pages. For
2192 further customization, put additional macros and requests into the file
2193 @file{man.local} which is loaded immediately after the @file{man}
2196 @Defmac {TH, title section [@Var{extra1} [@Var{extra2} [@Var{extra3}]]], man}
2197 Set the title of the man page to @var{title} and the section to
2198 @var{section}, which must have a value between 1 and@tie{}8. The value
2199 of @var{section} may also have a string appended, e.g.@: @samp{.pm},
2200 to indicate a specific subsection of the man pages.
2202 Both @var{title} and @var{section} are positioned at the left and right
2203 in the header line (with @var{section} in parentheses immediately
2204 appended to @var{title}. @var{extra1} is positioned in the middle of
2205 the footer line. @var{extra2} is positioned at the left in the footer
2206 line (or at the left on even pages and at the right on odd pages if
2207 double-sided printing is active). @var{extra3} is centered in the
2210 For @acronym{HTML} output, headers and footers are completely suppressed.
2212 Additionally, this macro starts a new page; the new line number is@tie{}1
2213 again (except if the @option{-rC1} option is given on the command line)
2214 -- this feature is intended only for formatting multiple man pages; a
2215 single man page should contain exactly one @code{TH} macro at the
2216 beginning of the file.
2219 @Defmac {SH, [@Var{heading}], man}
2220 Set up an unnumbered section heading sticking out to the left. Prints
2221 out all the text following @code{SH} up to the end of the line (or the
2222 text in the next line if there is no argument to @code{SH}) in bold
2223 face (or the font specified by the string @code{HF}), one size larger than
2224 the base document size. Additionally, the left margin and the indentation
2225 for the following text is reset to its default value.
2228 @Defmac {SS, [@Var{heading}], man}
2229 Set up an unnumbered (sub)section heading. Prints out all the text
2230 following @code{SS} up to the end of the line (or the text in the next
2231 line if there is no argument to @code{SS}) in bold face (or the font
2232 specified by the string @code{HF}), at the same size as the base document
2233 size. Additionally, the left margin and the indentation for the
2234 following text is reset to its default value.
2237 @Defmac {TP, [@Var{nnn}], man}
2238 Set up an indented paragraph with label. The indentation is set to
2239 @var{nnn} if that argument is supplied (the default unit is @samp{n}
2240 if omitted), otherwise it is set to the previous indentation value
2241 specified with @code{TP}, @code{IP}, or @code{HP} (or to the default
2242 value if none of them have been used yet).
2244 The first line of text following this macro is interpreted as a string
2245 to be printed flush-left, as it is appropriate for a label. It is not
2246 interpreted as part of a paragraph, so there is no attempt to fill the
2247 first line with text from the following input lines. Nevertheless, if
2248 the label is not as wide as the indentation the paragraph starts
2249 at the same line (but indented), continuing on the following lines.
2250 If the label is wider than the indentation the descriptive part
2251 of the paragraph begins on the line following the label, entirely
2252 indented. Note that neither font shape nor font size of the label is
2253 set to a default value; on the other hand, the rest of the text has
2254 default font settings.
2257 @DefmacList {LP, , man}
2258 @DefmacItem {PP, , man}
2259 @DefmacListEnd {P, , man}
2260 These macros are mutual aliases. Any of them causes a line break at
2261 the current position, followed by a vertical space downwards by the
2262 amount specified by the @code{PD} macro. The font size and shape are
2263 reset to the default value (10@dmn{pt} roman if no @option{-rS} option
2264 is given on the command line). Finally, the current left margin and the
2265 indentation is restored.
2268 @Defmac {IP, [@Var{designator} [@Var{nnn}]], man}
2269 Set up an indented paragraph, using @var{designator} as a tag to mark
2270 its beginning. The indentation is set to @var{nnn} if that argument
2271 is supplied (default unit is @samp{n}), otherwise it is set to the
2272 previous indentation value specified with @code{TP}, @code{IP}, or
2273 @code{HP} (or the default value if none of them have been used yet).
2274 Font size and face of the paragraph (but not the designator) are reset
2275 to their default values.
2277 To start an indented paragraph with a particular indentation but without
2278 a designator, use @samp{""} (two double quotes) as the first argument of
2281 For example, to start a paragraph with bullets as the designator and
2282 4@tie{}en indentation, write
2289 @Defmac {HP, [@Var{nnn}], man}
2290 @cindex hanging indentation [@code{man}]
2291 @cindex @code{man} macros, hanging indentation
2292 Set up a paragraph with hanging left indentation. The indentation is
2293 set to @var{nnn} if that argument is supplied (default unit is
2294 @samp{n}), otherwise it is set to the previous indentation value
2295 specified with @code{TP}, @code{IP}, or @code{HP} (or the default
2296 value if non of them have been used yet). Font size and face are reset
2297 to their default values.
2300 @Defmac {RS, [@Var{nnn}], man}
2301 @cindex left margin, how to move [@code{man}]
2302 @cindex @code{man} macros, moving left margin
2303 Move the left margin to the right by the value @var{nnn} if specified
2304 (default unit is @samp{n}); otherwise it is set to the previous
2305 indentation value specified with @code{TP}, @code{IP}, or @code{HP}
2306 (or to the default value if none of them have been used yet). The
2307 indentation value is then set to the default.
2309 Calls to the @code{RS} macro can be nested.
2312 @Defmac {RE, [@Var{nnn}], man}
2313 Move the left margin back to level @var{nnn}, restoring the previous left
2314 margin. If no argument is given, it moves one level back. The first
2315 level (i.e., no call to @code{RS} yet) has number@tie{}1, and each call
2316 to @code{RS} increases the level by@tie{}1.
2319 @cindex line breaks, with vertical space [@code{man}]
2320 @cindex @code{man} macros, line breaks with vertical space
2321 To summarize, the following macros cause a line break with the insertion
2322 of vertical space (which amount can be changed with the @code{PD}
2323 macro): @code{SH}, @code{SS}, @code{TP}, @code{LP} (@code{PP},
2324 @code{P}), @code{IP}, and @code{HP}.
2326 @cindex line breaks, without vertical space [@code{man}]
2327 @cindex @code{man} macros, line breaks without vertical space
2328 The macros @code{RS} and @code{RE} also cause a break but do not insert
2331 @cindex default indentation, resetting [@code{man}]
2332 @cindex indentaion, resetting to default [@code{man}]
2333 @cindex @code{man} macros, resetting default indentation
2334 Finally, the macros @code{SH}, @code{SS}, @code{LP} (@code{PP}, @code{P}),
2335 and @code{RS} reset the indentation to its default value.
2337 @c ---------------------------------------------------------------------
2339 @node Man font macros, Miscellaneous man macros, Man usage, man
2340 @subsection Macros to set fonts
2341 @cindex font selection [@code{man}]
2342 @cindex @code{man} macros, how to set fonts
2344 The standard font is roman; the default text size is 10@tie{}point.
2345 If command line option @option{-rS=@var{n}} is given, use
2346 @var{n}@dmn{pt} as the default text size.
2348 @Defmac {SM, [@Var{text}], man}
2349 Set the text on the same line or the text on the next line in a font
2350 that is one point size smaller than the default font.
2353 @Defmac {SB, [@Var{text}], man}
2354 @cindex bold face [@code{man}]
2355 @cindex @code{man} macros, bold face
2356 Set the text on the same line or the text on the next line in bold face
2357 font, one point size smaller than the default font.
2360 @Defmac {BI, text, man}
2361 Set its arguments alternately in bold face and italic, without a space
2362 between the arguments. Thus,
2365 .BI this "word and" that
2369 produces ``thisword andthat'' with ``this'' and ``that'' in bold face,
2370 and ``word and'' in italics.
2373 @Defmac {IB, text, man}
2374 Set its arguments alternately in italic and bold face, without a space
2375 between the arguments.
2378 @Defmac {RI, text, man}
2379 Set its arguments alternately in roman and italic, without a space between
2383 @Defmac {IR, text, man}
2384 Set its arguments alternately in italic and roman, without a space between
2388 @Defmac {BR, text, man}
2389 Set its arguments alternately in bold face and roman, without a space
2390 between the arguments.
2393 @Defmac {RB, text, man}
2394 Set its arguments alternately in roman and bold face, without a space
2395 between the arguments.
2398 @Defmac {B, [@Var{text}], man}
2399 Set @var{text} in bold face. If no text is present on the line where
2400 the macro is called, then the text of the next line appears in bold
2404 @Defmac {I, [@Var{text}], man}
2405 @cindex italic fonts [@code{man}]
2406 @cindex @code{man} macros, italic fonts
2407 Set @var{text} in italic. If no text is present on the line where the
2408 macro is called, then the text of the next line appears in italic.
2411 @c ---------------------------------------------------------------------
2413 @node Miscellaneous man macros, Predefined man strings, Man font macros, man
2414 @subsection Miscellaneous macros
2417 @cindex @code{man} macros, default indentation
2418 @cindex default indentation [@code{man}]
2419 The default indentation is 7.2@dmn{n} in troff mode and 7@dmn{n} in
2420 nroff mode except for @code{grohtml} which ignores indentation.
2423 @cindex tab stops [@code{man}]
2424 @cindex @code{man} macros, tab stops
2425 Set tabs every 0.5@tie{}inches. Since this macro is always executed
2426 during a call to the @code{TH} macro, it makes sense to call it only if
2427 the tab positions have been changed.
2430 @Defmac {PD, [@Var{nnn}], man}
2431 @cindex empty space before a paragraph [@code{man}]
2432 @cindex @code{man} macros, empty space before a paragraph
2433 Adjust the empty space before a new paragraph (or section). The
2434 optional argument gives the amount of space (default unit is
2435 @samp{v}); without parameter, the value is reset to its default value
2436 (1@tie{}line in nroff mode, 0.4@dmn{v}@tie{}otherwise).
2438 This affects the macros @code{SH}, @code{SS}, @code{TP}, @code{LP} (as
2439 well as @code{PP} and @code{P}), @code{IP}, and @code{HP}.
2442 The following two macros are included for
2445 @Defmac {AT, [@Var{system} [@Var{release}]], man}
2446 @cindex @code{man}macros, BSD compatibility
2447 Alter the footer for use with @acronym{AT&T} manpages.
2448 This command exists only for compatibility; don't use it.
2449 The first argument @var{system} can be:
2453 7th Edition (the default)
2462 An optional second argument @var{release} to @code{AT} specifies the
2463 release number (such as ``System V Release 3'').
2466 @Defmac {UC, [@Var{version}], man}
2467 @cindex @code{man}macros, BSD compatibility
2468 Alters the footer for use with @acronym{BSD} manpages.
2469 This command exists only for compatibility; don't use it.
2470 The argument can be:
2474 3rd Berkeley Distribution (the default)
2477 4th Berkeley Distribution
2480 4.2 Berkeley Distribution
2483 4.3 Berkeley Distribution
2486 4.4 Berkeley Distribution
2490 @c ---------------------------------------------------------------------
2492 @node Predefined man strings, Preprocessors in man pages, Miscellaneous man macros, man
2493 @subsection Predefined strings
2495 The following strings are defined:
2498 Switch back to the default font size.
2502 The typeface used for headings.
2503 The default is @samp{B}.
2507 The `registered' sign.
2511 The `trademark' sign.
2514 @DefstrList {lq, man}
2515 @DefstrListEnd {rq, man}
2516 @cindex @code{lq} glyph, and @code{lq} string [@code{man}]
2517 @cindex @code{rq} glyph, and @code{rq} string [@code{man}]
2518 Left and right quote. This is equal to @code{\(lq} and @code{\(rq},
2522 @c ---------------------------------------------------------------------
2524 @node Preprocessors in man pages, Optional man extensions, Predefined man strings, man
2525 @subsection Preprocessors in @file{man} pages
2527 @cindex preprocessor, calling convention
2528 @cindex calling convention of preprocessors
2529 If a preprocessor like @code{gtbl} or @code{geqn} is needed, it has
2530 become common usage to make the first line of the man page look like
2537 @pindex geqn@r{, invocation in manual pages}
2538 @pindex grefer@r{, invocation in manual pages}
2539 @pindex gtbl@r{, invocation in manual pages}
2540 @pindex man@r{, invocation of preprocessors}
2542 Note the single space character after the double quote. @var{word}
2543 consists of letters for the needed preprocessors: @samp{e} for
2544 @code{geqn}, @samp{r} for @code{grefer}, @samp{t} for @code{gtbl}.
2545 Modern implementations of the @code{man} program read this first line
2546 and automatically call the right preprocessor(s).
2548 @c ---------------------------------------------------------------------
2550 @node Optional man extensions, , Preprocessors in man pages, man
2551 @subsection Optional @file{man} extensions
2554 Use the file @file{man.local} for local extensions
2555 to the @code{man} macros or for style changes.
2557 @unnumberedsubsubsec Custom headers and footers
2558 @cindex @code{man} macros, custom headers and footers
2560 In groff versions 1.18.2 and later, you can specify custom
2561 headers and footers by redefining the following macros in
2565 Control the content of the headers.
2566 Normally, the header prints the command name
2567 and section number on either side, and the
2568 optional fifth argument to @code{TH} in the center.
2572 Control the content of the footers.
2573 Normally, the footer prints the page number
2574 and the third and fourth arguments to @code{TH}.
2576 Use the @code{FT} number register to specify the
2578 The default is @minus{}0.5@dmn{i}.
2581 @unnumberedsubsubsec Ultrix-specific man macros
2582 @cindex Ultrix-specific @code{man} macros
2583 @cindex @code{man} macros, Ultrix-specific
2586 The @code{groff} source distribution includes
2587 a file named @file{man.ultrix}, containing
2588 macros compatible with the Ultrix variant of
2590 Copy this file into @file{man.local} (or use the @code{mso} request to
2591 load it) to enable the following macros.
2593 @Defmac {CT, @Var{key}, man}
2594 Print @samp{<CTRL/@var{key}>}.
2598 Print subsequent text using the constant width (Courier) typeface.
2602 Begin a non-filled display.
2606 End a non-filled display started with @code{Ds}.
2609 @Defmac {EX, [@Var{indent}], man}
2610 Begins a non-filled display
2611 using the constant width (Courier) typeface.
2612 Use the optional @var{indent} argument to
2617 End a non-filled display started with @code{EX}.
2620 @Defmac {G, [@Var{text}], man}
2621 Sets @var{text} in Helvetica.
2622 If no text is present on the line where
2623 the macro is called, then the text of the
2624 next line appears in Helvetica.
2627 @Defmac {GL, [@Var{text}], man}
2628 Sets @var{text} in Helvetica Oblique.
2629 If no text is present on the line where
2630 the macro is called, then the text of the
2631 next line appears in Helvetica Oblique.
2634 @Defmac {HB, [@Var{text}], man}
2635 Sets @var{text} in Helvetica Bold.
2636 If no text is present on the line where
2637 the macro is called, then all text up to
2638 the next @code{HB} appears in Helvetica Bold.
2641 @Defmac {TB, [@Var{text}], man}
2642 Identical to @code{HB}.
2645 @Defmac {MS, @Var{title} @Var{sect} [@Var{punct}], man}
2646 Set a manpage reference in Ultrix format.
2647 The @var{title} is in Courier instead of italic.
2648 Optional punctuation follows the section number without
2649 an intervening space.
2652 @Defmac {NT, [@code{C}] [@Var{title}], man}
2654 Print the optional @Var{title}, or the word ``Note'',
2655 centered on the page.
2656 Text following the macro makes up the body of the note,
2657 and is indented on both sides.
2658 If the first argument is @code{C}, the body of the
2659 note is printed centered (the second argument replaces
2660 the word ``Note'' if specified).
2664 End a note begun with @code{NT}.
2667 @Defmac {PN, @Var{path} [@Var{punct}], man}
2668 Set the path name in constant width (Courier),
2669 followed by optional punctuation.
2672 @Defmac {Pn, [@Var{punct}] @Var{path} [@Var{punct}], man}
2673 When called with two arguments, identical to @code{PN}.
2674 When called with three arguments,
2675 set the second argument in constant width (Courier),
2676 bracketed by the first and third arguments in the current font.
2680 Switch to roman font and turn off any underlining in effect.
2684 Print the string @samp{<RETURN>}.
2687 @Defmac {VS, [@code{4}], man}
2688 Start printing a change bar in the margin if
2689 the number @code{4} is specified.
2690 Otherwise, this macro does nothing.
2694 End printing the change bar begun by @code{VS}.
2697 @unnumberedsubsubsec Simple example
2699 The following example @file{man.local} file
2700 alters the @code{SH} macro to add some extra
2701 vertical space before printing the heading.
2702 Headings are printed in Helvetica Bold.
2705 .\" Make the heading fonts Helvetica
2708 .\" Put more whitespace in front of headings.
2711 . if t .sp (u;\\n[PD]*2)
2716 @c =====================================================================
2718 @node mdoc, ms, man, Macro Packages
2719 @section @file{mdoc}
2720 @cindex @code{mdoc} macros
2722 @c XXX documentation
2723 @c XXX this is a placeholder until we get stuff knocked into shape
2724 See the @cite{groff_mdoc(7)} man page (type @command{man groff_mdoc}
2725 at the command line).
2728 @c =====================================================================
2730 @node ms, me, mdoc, Macro Packages
2732 @cindex @code{ms} macros
2735 macros are suitable for reports, letters, books,
2736 user manuals, and so forth.
2737 The package provides macros for cover pages, section headings,
2738 paragraphs, lists, footnotes, pagination,
2739 and a table of contents.
2743 * General ms Structure::
2744 * ms Document Control Registers::
2745 * ms Cover Page Macros::
2748 * Differences from AT&T ms::
2751 @c ---------------------------------------------------------------------
2753 @node ms Intro, General ms Structure, ms, ms
2754 @subsection Introduction to @file{ms}
2756 The original @file{-ms} macros were included with
2757 @acronym{AT&T} @code{troff} as well as the
2759 While the @file{man} package is intended for brief documents
2760 that can be read on-line as well as printed, the @file{ms}
2761 macros are suitable for longer documents that are meant to be
2762 printed rather than read on-line.
2764 The @file{ms} macro package included with @code{groff}
2765 is a complete, bottom-up re-implementation.
2766 Several macros (specific to @acronym{AT&T}
2767 or Berkeley) are not included, while several new commands are.
2768 @xref{Differences from AT&T ms}, for more information.
2770 @c ---------------------------------------------------------------------
2772 @node General ms Structure, ms Document Control Registers, ms Intro, ms
2773 @subsection General structure of an @file{ms} document
2774 @cindex @code{ms} macros, general structure
2776 The @file{ms} macro package expects a certain amount of structure,
2777 but not as much as packages such as @file{man} or @file{mdoc}.
2779 The simplest documents can begin with a paragraph macro
2780 (such as @code{LP} or @code{PP}),
2781 and consist of text separated by paragraph macros
2782 or even blank lines.
2783 Longer documents have a structure as follows:
2787 If you invoke the @code{RP}
2788 (report) macro on the first line of the document,
2789 @code{groff} prints the cover page information on its own page;
2790 otherwise it prints the information on the
2791 first page with your document text immediately following.
2792 Other document formats found in @acronym{AT&T} @code{troff}
2793 are specific to @acronym{AT&T} or Berkeley, and are not supported in
2796 @item Format and layout
2797 By setting number registers,
2798 you can change your document's type (font and size),
2799 margins, spacing, headers and footers, and footnotes.
2800 @xref{ms Document Control Registers}, for more details.
2803 A cover page consists of a title, the author's name and institution,
2804 an abstract, and the date.
2805 @footnote{Actually, only the title is required.}
2806 @xref{ms Cover Page Macros}, for more details.
2809 Following the cover page is your document.
2810 You can use the @file{ms}
2811 macros to write reports, letters, books, and so forth.
2812 The package is designed for structured documents,
2813 consisting of paragraphs interspersed with headings
2814 and augmented by lists, footnotes, tables, and other
2816 @xref{ms Body Text}, for more details.
2818 @item Table of contents
2819 Longer documents usually include a table of contents,
2820 which you can invoke by placing the
2822 macro at the end of your document.
2824 macros have minimal indexing facilities, consisting of the
2825 @code{IX} macro, which prints an entry on standard error.
2826 Printing the table of contents at the end is necessary since
2827 @code{groff} is a single-pass text formatter,
2828 thus it cannot determine the page number of each section
2829 until that section has actually been set and printed.
2830 Since @file{ms} output is intended for hardcopy,
2831 you can manually relocate the pages containing
2832 the table of contents between the cover page and the
2833 body text after printing.
2836 @c ---------------------------------------------------------------------
2838 @node ms Document Control Registers, ms Cover Page Macros, General ms Structure, ms
2839 @subsection Document control registers
2840 @cindex @code{ms} macros, document control registers
2842 The following is a list of document control number registers.
2843 For the sake of consistency,
2844 set registers related to margins at the beginning of your document,
2845 or just after the @code{RP} macro.
2846 You can set other registers later in your document,
2847 but you should keep them together at the beginning
2848 to make them easy to find and edit as necessary.
2850 @unnumberedsubsubsec Margin Settings
2853 Defines the page offset (i.e.@: the left margin).
2854 There is no explicit right margin setting; the combination of
2855 the @code{PO} and @code{LL} registers implicitly define the
2858 Effective: next page.
2860 Default value: 1@dmn{i}.
2864 Defines the line length (i.e.@: the width of the body text).
2866 Effective: next paragraph.
2872 Defines the title length (i.e.@: the header and footer width).
2873 This is usually the same as @code{LL}, but not necessarily.
2875 Effective: next paragraph.
2881 Defines the header margin height at the top of the page.
2883 Effective: next page.
2889 Defines the footer margin height at the bottom of the page.
2891 Effective: next page.
2896 @unnumberedsubsubsec Text Settings
2899 Defines the point size of the body text. If the value is larger than or
2900 equal to 1000, divide it by 1000 to get a fractional point size. For
2901 example, @samp{.nr PS 10250} sets the document's point size to 10.25@dmn{p}.
2903 Effective: next paragraph.
2909 Defines the space between lines (line height plus leading). If the value
2910 is larger than or equal to 1000, divide it by 1000 to get a fractional point
2911 size. Due to backwards compatibility, @code{VS} must be smaller than
2912 40000 (this is 40.0@dmn{p}).
2914 Effective: next paragraph.
2919 @Defmpreg {PSINCR, ms}
2920 Defines an increment in point size, which will be applied to section
2921 headings at nesting levels below the value specified in @code{GROWPS}. The
2922 value of @code{PSINCR} should be specified in points, with the @dmn{p}
2923 scaling factor, and may include a fractional component; for example,
2924 @w{@samp{.nr PSINCR 1.5p}} sets a point size increment of 1.5@dmn{p}.
2926 Effective: next section heading.
2931 @Defmpreg {GROWPS, ms}
2932 Defines the heading level below which the point size increment set by
2933 @code{PSINCR} becomes effective. Section headings at and above the level
2934 specified by @code{GROWPS} will be printed at the point size set by @code{PS};
2935 for each level below the value of @code{GROWPS}, the point size will be
2936 increased in steps equal to the value of @code{PSINCR}. Setting @code{GROWPS}
2937 to any value less than@tie{}2 disables the incremental heading size feature.
2939 Effective: next section heading.
2945 Defines the hyphenation level. @code{HY} sets safely the value of the
2946 low-level @code{.hy} register. Setting the value of @code{HY} to 0 is
2947 equivalent to using the @code{.nh} request.
2949 Effective: next paragraph.
2955 Defines the font family used to typeset the document.
2957 Effective: next paragraph.
2959 Default: as defined in the output device.
2962 @unnumberedsubsubsec Paragraph Settings
2965 Defines the initial indent of a @code{.PP} paragraph.
2967 Effective: next paragraph.
2973 Defines the space between paragraphs.
2975 Effective: next paragraph.
2977 Default: 0.3@dmn{v}.
2981 Defines the indent on both sides of a quoted (@code{.QP}) paragraph.
2983 Effective: next paragraph.
2988 @Defmpreg {PORPHANS, ms}
2989 Defines the minimum number of initial lines of any paragraph which should
2990 be kept together, to avoid orphan lines at the bottom of a page. If a new
2991 paragraph is started close to the bottom of a page, and there is insufficient
2992 space to accommodate @code{PORPHANS} lines before an automatic page break,
2993 then the page break will be forced, before the start of the paragraph.
2995 Effective: next paragraph.
3000 @Defmpreg {HORPHANS, ms}
3001 Defines the minimum number of lines of the following paragraph which should
3002 be kept together with any section heading introduced by the @code{NH} or
3003 @code{SH} macros. If a section heading is placed close to the bottom of a
3004 page, and there is insufficient space to accommodate both the heading and
3005 at least @code{HORPHANS} lines of the following paragraph, before an
3006 automatic page break, then the page break will be forced before the heading.
3008 Effective: next paragraph.
3013 @unnumberedsubsubsec Footnote Settings
3016 Defines the length of a footnote.
3018 Effective: next footnote.
3020 Default: @math{@code{@\n[LL]} * 5 / 6}.
3024 Defines the footnote indent.
3026 Effective: next footnote.
3032 The footnote format:
3035 Prints the footnote number as a superscript; indents the footnote (default).
3038 Prints the number followed by a period (like 1.)
3039 and indents the footnote.
3042 Like 1, without an indent.
3045 Like 1, but prints the footnote number as a hanging paragraph.
3048 Effective: next footnote.
3054 Defines the footnote point size. If the value is larger than or equal to
3055 1000, divide it by 1000 to get a fractional point size.
3057 Effective: next footnote.
3059 Default: @math{@code{@\n[PS]} - 2}.
3063 Defines the footnote vertical spacing. If the value is larger than or equal
3064 to 1000, divide it by 1000 to get a fractional point size.
3066 Effective: next footnote.
3068 Default: @math{@code{@\n[FPS]} + 2}.
3072 Defines the footnote paragraph spacing.
3074 Effective: next footnote.
3076 Default: @math{@code{@\n[PD]} / 2}.
3079 @unnumberedsubsubsec Miscellaneous Number Registers
3081 @Defmpreg {MINGW, ms}
3082 Defines the minimum width between columns in a multi-column document.
3084 Effective: next page.
3089 @c ---------------------------------------------------------------------
3091 @node ms Cover Page Macros, ms Body Text, ms Document Control Registers, ms
3092 @subsection Cover page macros
3093 @cindex @code{ms} macros, cover page
3094 @cindex cover page macros, [@code{ms}]
3096 Use the following macros to create a cover page for your document
3099 @Defmac {RP, [@code{no}], ms}
3100 Specifies the report format for your document.
3101 The report format creates a separate cover page.
3102 The default action (no @code{.RP}
3103 macro) is to print a subset of the
3104 cover page on page 1 of your document.
3106 If you use the word @code{no} as an optional argument,
3107 @code{groff} prints a title page but
3108 does not repeat any of the title page information
3109 (title, author, abstract, etc.)
3110 on page 1 of the document.
3113 @Defmac {DA, [@dots{}], ms}
3114 (optional) Print the current date, or the arguments to the macro if any,
3115 on the title page (if specified) and in the footers.
3116 This is the default for @code{nroff}.
3119 @Defmac {ND, [@dots{}], ms}
3120 (optional) Print the current date, or the arguments to the macro if any,
3121 on the title page (if specified) but not in the footers.
3122 This is the default for @code{troff}.
3126 Specifies the document title.
3127 @code{groff} collects text following the @code{.TL}
3128 macro into the title, until reaching the author name or abstract.
3132 Specifies the author's name, which appears on the
3133 line (or lines) immediately following.
3134 You can specify multiple authors as follows:
3140 University of West Bumblefuzz
3144 Monolithic Corporation
3151 Specifies the author's institution.
3152 You can specify multiple institutions in the same way
3153 that you specify multiple authors.
3156 @Defmac {AB, [@code{no}], ms}
3157 Begins the abstract.
3158 The default is to print the word @acronym{ABSTRACT},
3159 centered and in italics, above the text of the abstract.
3160 The word @code{no} as an optional argument suppresses this heading.
3167 The following is example mark-up for a title page.
3168 @cindex title page, example markup
3169 @cindex example markup, title page
3175 The Inevitability of Code Bloat
3176 in Commercial and Free Software
3180 University of West Bumblefuzz
3182 This report examines the long-term growth
3183 of the code bases in two large, popular software
3184 packages; the free Emacs and the commercial
3186 While differences appear in the type or order
3187 of features added, due to the different
3188 methodologies used, the results are the same
3191 The free software approach is shown to be
3192 superior in that while free software can
3193 become as bloated as commercial offerings,
3194 free software tends to have fewer serious
3195 bugs and the added features are in line with
3199 ... the rest of the paper follows ...
3203 @c ---------------------------------------------------------------------
3205 @node ms Body Text, ms Page Layout, ms Cover Page Macros, ms
3206 @subsection Body text
3207 @cindex @code{ms} macros, body text
3209 This section describes macros used to mark up the body of your document.
3210 Examples include paragraphs, sections, and other groups.
3213 * Paragraphs in ms::
3215 * Highlighting in ms::
3219 * ms Displays and Keeps::
3221 * Example multi-page table::
3225 @c ---------------------------------------------------------------------
3227 @node Paragraphs in ms, Headings in ms, ms Body Text, ms Body Text
3228 @subsubsection Paragraphs
3229 @cindex @code{ms} macros, paragraph handling
3231 The following paragraph types are available.
3234 Sets a paragraph with an initial indent.
3238 Sets a paragraph with no initial indent.
3242 Sets a paragraph that is indented at both left and right margins.
3243 The effect is identical to the @acronym{HTML} @code{<BLOCKQUOTE>} element.
3244 The next paragraph or heading returns margins to normal.
3248 Sets a paragraph whose lines are indented,
3249 except for the first line.
3250 This is a Berkeley extension.
3253 The following markup uses all four paragraph macros.
3258 Cases used in the study
3260 The following software and versions were
3261 considered for this report.
3263 For commercial software, we chose
3264 .B "Microsoft Word for Windows" ,
3265 starting with version 1.0 through the
3266 current version (Word 2000).
3268 For free software, we chose
3270 from its first appearance as a standalone
3271 editor through the current version (v20).
3272 See [Bloggs 2002] for details.
3274 Franklin's Law applied to software:
3275 software expands to outgrow both
3276 RAM and disk space over time.
3281 .I "Everyone's a Critic" ,
3282 Underground Press, March 2002.
3283 A definitive work that answers all questions
3284 and criticisms about the quality and usability of
3289 The @code{PORPHANS} register (@pxref{ms Document Control Registers})
3290 operates in conjunction with each of these macros, to inhibit the
3291 printing of orphan lines at the bottom of any page.
3293 @c ---------------------------------------------------------------------
3295 @node Headings in ms, Highlighting in ms, Paragraphs in ms, ms Body Text
3296 @subsubsection Headings
3297 @cindex @code{ms} macros, headings
3299 Use headings to create a hierarchical structure for your document.
3300 The @file{ms} macros print headings in @strong{bold},
3301 using the same font family and point size as the body text.
3303 The following describes the heading macros:
3305 @DefmacList {NH, @Var{curr-level}, ms}
3306 @DefmacListEnd {NH, @t{S} @Var{level0} @dots{}, ms}
3308 The argument is either a numeric argument to indicate the
3309 level of the heading, or the letter@tie{}@code{S} followed by numeric
3310 arguments to set the heading level explicitly.
3312 If you specify heading levels out of sequence, such as invoking
3313 @samp{.NH 3} after @samp{.NH 1}, @code{groff}
3314 prints a warning on standard error.
3317 @DefstrList {SN, ms}
3318 @DefstrItem {SN-DOT, ms}
3319 @DefstrListEnd {SN-NO-DOT, ms}
3320 After invocation of @code{NH}, the assigned section number is made
3321 available in the strings @code{SN-DOT} (exactly as it appears in the
3322 printed section heading) and @code{SN-NO-DOT} (with the final period
3323 omitted). The string @code{SN} is also defined, as an alias for
3324 @code{SN-DOT}; if preferred, you may redefine it as an alias for
3325 @code{SN-NO-DOT}, by including the initialization
3333 @strong{before} your first use of @code{NH}, or simply
3340 @strong{after} your first use of @code{NH}.
3343 @Defmac {SH, [@Var{match-level}], ms}
3344 Unnumbered subheading.
3346 The optional @code{match-level} argument is a GNU extension. It is a
3347 number indicating the level of the heading, in a manner analogous to
3348 the @code{curr-level} argument to @code{.NH}. Its purpose is to match
3349 the point size, at which the heading is printed, to the size of a
3350 numbered heading at the same level, when the @code{GROWPS}/@code{PSINCR}
3351 heading size adjustment mechanism is in effect.
3352 @xref{ms Document Control Registers}.
3355 The @code{HORPHANS} register (@pxref{ms Document Control Registers})
3356 operates in conjunction with the @code{NH} and @code{SH} macros, to
3357 inhibit the printing of orphaned section headings at the bottom of any
3360 @c ---------------------------------------------------------------------
3362 @node Highlighting in ms, Lists in ms, Headings in ms, ms Body Text
3363 @subsubsection Highlighting
3364 @cindex @code{ms} macros, highlighting
3366 The @file{ms} macros provide a variety of methods to highlight
3369 @Defmac {B, [@Var{txt} [@Var{post} [@Var{pre}]]], ms}
3370 Sets its first argument in @strong{bold type}.
3371 If you specify a second argument, @code{groff} prints it in the
3372 previous font after the bold text, with no intervening space
3373 (this allows you to set punctuation after the highlighted text
3374 without highlighting the punctuation).
3375 Similarly, it prints the third argument (if any) in the previous
3376 font @strong{before} the first argument.
3383 prints (@strong{foo}).
3385 If you give this macro no arguments, @code{groff}
3386 prints all text following in bold until
3387 the next highlighting, paragraph, or heading macro.
3390 @Defmac {R, [@Var{txt} [@Var{post} [@Var{pre}]]], ms}
3391 Sets its first argument in roman (or regular) type.
3392 It operates similarly to the @code{B}@tie{}macro otherwise.
3395 @Defmac {I, [@Var{txt} [@Var{post} [@Var{pre}]]], ms}
3396 Sets its first argument in @emph{italic type}.
3397 It operates similarly to the @code{B}@tie{}macro otherwise.
3400 @Defmac {CW, [@Var{txt} [@Var{post} [@Var{pre}]]], ms}
3401 Sets its first argument in a @code{constant width face}.
3402 It operates similarly to the @code{B}@tie{}macro otherwise.
3405 @Defmac {BI, [@Var{txt} [@Var{post} [@Var{pre}]]], ms}
3406 Sets its first argument in bold italic type.
3407 It operates similarly to the @code{B}@tie{}macro otherwise.
3410 @Defmac {BX, [@Var{txt}], ms}
3411 Prints its argument and draws a box around it.
3412 If you want to box a string that contains spaces,
3413 use a digit-width space (@code{\0}).
3416 @Defmac {UL, [@Var{txt} [@Var{post}]], ms}
3417 Prints its first argument with an underline.
3418 If you specify a second argument, @code{groff}
3419 prints it in the previous font after
3420 the underlined text, with no intervening space.
3424 Prints all text following in larger type
3425 (two points larger than the current point size) until
3426 the next font size, highlighting, paragraph, or heading macro.
3427 You can specify this macro multiple times
3428 to enlarge the point size as needed.
3432 Prints all text following in smaller type
3433 (two points smaller than the current point size) until
3434 the next type size, highlighting, paragraph, or heading macro.
3435 You can specify this macro multiple times
3436 to reduce the point size as needed.
3440 Prints all text following in the normal point size
3441 (that is, the value of the @code{PS} register).
3444 @c ---------------------------------------------------------------------
3446 @node Lists in ms, Indents in ms, Highlighting in ms, ms Body Text
3447 @subsubsection Lists
3448 @cindex @code{ms} macros, lists
3450 The @code{.IP} macro handles duties for all lists.
3452 @Defmac {IP, [@Var{marker} [@Var{width}]], ms}
3453 The @var{marker} is usually a bullet glyph (@code{\[bu]})
3454 for unordered lists, a number (or auto-incrementing number
3455 register) for numbered lists, or a word or phrase for indented
3456 (glossary-style) lists.
3458 The @var{width} specifies the indent for the body of each list item;
3459 its default unit is @samp{n}.
3460 Once specified, the indent remains the same for all
3461 list items in the document until specified again.
3463 The @code{PORPHANS} register (@pxref{ms Document Control Registers})
3464 operates in conjunction with the @code{IP} macro, to inhibit the
3465 printing of orphaned list markers at the bottom of any page.
3468 The following is an example of a bulleted list.
3469 @cindex example markup, bulleted list [@code{ms}]
3470 @cindex bulleted list, example markup [@code{ms}]
3496 The following is an example of a numbered list.
3497 @cindex example markup, numbered list [@code{ms}]
3498 @cindex numbered list, example markup [@code{ms}]
3523 Note the use of the auto-incrementing number
3524 register in this example.
3527 The following is an example of a glossary-style list.
3528 @cindex example markup, glossary-style list [@code{ms}]
3529 @cindex glossary-style list, example markup [@code{ms}]
3532 A glossary-style list:
3534 Two or more attorneys.
3536 Firearms, preferably
3546 A glossary-style list:
3549 Two or more attorneys.
3551 guns Firearms, preferably large-caliber.
3554 Gotta pay for those lawyers and guns!
3557 In the last example, the @code{IP} macro places the definition
3558 on the same line as the term if it has enough space; otherwise,
3559 it breaks to the next line and starts the definition below the
3561 This may or may not be the effect you want, especially if some
3562 of the definitions break and some do not.
3563 The following examples show two possible ways to force a break.
3565 The first workaround uses the @code{br}
3566 request to force a break after printing the term or label.
3570 A glossary-style list:
3572 Two or more attorneys.
3575 Firearms, preferably large-caliber.
3577 Gotta pay for those lawyers and guns!
3582 The second workaround uses the @code{\p} escape to force the break.
3583 Note the space following the escape; this is important.
3584 If you omit the space, @code{groff} prints the first word on
3585 the same line as the term or label (if it fits) @strong{then}
3590 A glossary-style list:
3592 Two or more attorneys.
3594 \p Firearms, preferably large-caliber.
3596 Gotta pay for those lawyers and guns!
3601 To set nested lists, use the @code{RS} and @code{RE} macros.
3602 @xref{Indents in ms}, for more information.
3603 @cindex @code{ms} macros, nested lists
3604 @cindex nested lists [@code{ms}]
3639 @c ---------------------------------------------------------------------
3641 @node Indents in ms, Tabstops in ms, Lists in ms, ms Body Text
3642 @subsubsection Indents
3645 you may need to indent a section of text
3646 while still wrapping and filling.
3648 for an example of nested lists.
3650 @DefmacList {RS, , ms}
3651 @DefmacListEnd {RE, , ms}
3652 These macros begin and end an indented section.
3653 The @code{PI} register controls the amount of indent,
3654 allowing the indented text to line up under hanging
3655 and indented paragraphs.
3658 @xref{ms Displays and Keeps},
3659 for macros to indent and turn off filling.
3661 @c ---------------------------------------------------------------------
3663 @node Tabstops in ms, ms Displays and Keeps, Indents in ms, ms Body Text
3664 @subsubsection Tab Stops
3666 Use the @code{ta} request to define tab stops as needed.
3667 @xref{Tabs and Fields}.
3670 Use this macro to reset the tab stops to the default for @file{ms}
3672 You can redefine the @code{TA} macro to create a different set
3673 of default tab stops.
3676 @c ---------------------------------------------------------------------
3678 @node ms Displays and Keeps, ms Insertions, Tabstops in ms, ms Body Text
3679 @subsubsection Displays and keeps
3680 @cindex @code{ms} macros, displays
3681 @cindex @code{ms} macros, keeps
3682 @cindex keeps [@code{ms}]
3683 @cindex displays [@code{ms}]
3685 Use displays to show text-based examples or figures
3686 (such as code listings).
3688 Displays turn off filling, so lines of code are displayed
3689 as-is without inserting @code{br} requests in between each line.
3690 Displays can be @dfn{kept} on a single page, or allowed
3691 to break across pages.
3693 @DefmacList {DS, @t{L}, ms}
3694 @DefmacItem {LD, , ms}
3695 @DefmacListEnd {DE, , ms}
3696 Left-justified display.
3697 The @samp{.DS L} call generates a page break, if necessary,
3698 to keep the entire display on one page.
3699 The @code{LD} macro allows the display to break across pages.
3700 The @code{DE} macro ends the display.
3703 @DefmacList {DS, @t{I}, ms}
3704 @DefmacItem {ID, , ms}
3705 @DefmacListEnd {DE, , ms}
3706 Indents the display as defined by the @code{DI} register.
3707 The @samp{.DS I} call generates a page break, if necessary,
3708 to keep the entire display on one page.
3709 The @code{ID} macro allows the display to break across pages.
3710 The @code{DE} macro ends the display.
3713 @DefmacList {DS, @t{B}, ms}
3714 @DefmacItem {BD, , ms}
3715 @DefmacListEnd {DE, , ms}
3716 Sets a block-centered display: the entire display is left-justified,
3717 but indented so that the longest line in the display is centered
3719 The @samp{.DS B} call generates a page break, if necessary,
3720 to keep the entire display on one page.
3721 The @code{BD} macro allows the display to break across pages.
3722 The @code{DE} macro ends the display.
3725 @DefmacList {DS, @t{C}, ms}
3726 @DefmacItem {CD, , ms}
3727 @DefmacListEnd {DE, , ms}
3728 Sets a centered display: each line in the display is centered.
3729 The @samp{.DS C} call generates a page break, if necessary,
3730 to keep the entire display on one page.
3731 The @code{CD} macro allows the display to break across pages.
3732 The @code{DE} macro ends the display.
3735 @DefmacList {DS, @t{R}, ms}
3736 @DefmacItem {RD, , ms}
3737 @DefmacListEnd {DE, , ms}
3738 Right-justifies each line in the display.
3739 The @samp{.DS R} call generates a page break, if necessary,
3740 to keep the entire display on one page.
3741 The @code{RD} macro allows the display to break across pages.
3742 The @code{DE} macro ends the display.
3745 @DefmacList {Ds, , ms}
3746 @DefmacListEnd {De, , ms}
3747 These two macros were formerly provided as aliases for
3748 @code{DS} and @code{DE}, respectively.
3749 They have been removed, and should no longer be used.
3750 The original implementations of @code{DS} and @code{DE}
3751 are retained, and should be used instead.
3752 X11 documents which actually use @code{Ds} and @code{De} always load a
3753 specific macro file from the X11 distribution (@file{macros.t}) which
3754 provides proper definitions for the two macros.
3758 On occasion, you may want to @dfn{keep} other text together on a page.
3759 For example, you may want to keep two paragraphs together, or
3760 a paragraph that refers to a table (or list, or other item)
3761 immediately following.
3762 The @file{ms} macros provide the @code{KS} and @code{KE}
3763 macros for this purpose.
3765 @DefmacList {KS, , ms}
3766 @DefmacListEnd {KE, , ms}
3767 The @code{KS} macro begins a block of text to be kept on a
3768 single page, and the @code{KE} macro ends the block.
3771 @DefmacList {KF, , ms}
3772 @DefmacListEnd {KE, , ms}
3773 Specifies a @dfn{floating keep};
3774 if the keep cannot fit on the current page, @code{groff}
3775 holds the contents of the keep and allows text following
3776 the keep (in the source file) to fill in the remainder of
3778 When the page breaks, whether by an explicit @code{bp}
3779 request or by reaching the end of the page, @code{groff}
3780 prints the floating keep at the top of the new page.
3781 This is useful for printing large graphics or tables
3782 that do not need to appear exactly where specified.
3785 You can also use the @code{ne} request to force a page break if
3786 there is not enough vertical space remaining on the page.
3789 Use the following macros to draw a box around a section of
3790 text (such as a display).
3792 @DefmacList {B1, , ms}
3793 @DefmacListEnd {B2, , ms}
3794 Marks the beginning and ending of text that is to have a
3795 box drawn around it.
3796 The @code{B1} macro begins the box; the @code{B2} macro ends it.
3797 Text in the box is automatically placed in a diversion (keep).
3800 @c ---------------------------------------------------------------------
3802 @node ms Insertions, Example multi-page table, ms Displays and Keeps, ms Body Text
3803 @subsubsection Tables, figures, equations, and references
3804 @cindex @code{ms} macros, tables
3805 @cindex @code{ms} macros, figures
3806 @cindex @code{ms} macros, equations
3807 @cindex @code{ms} macros, references
3808 @cindex tables [@code{ms}]
3809 @cindex figures [@code{ms}]
3810 @cindex equations [@code{ms}]
3811 @cindex references [@code{ms}]
3813 The @file{ms} macros support the standard
3814 @code{groff} preprocessors:
3815 @code{tbl}, @code{pic}, @code{eqn}, and @code{refer}.
3820 You mark text meant for preprocessors by enclosing it
3821 in pairs of tags as follows.
3823 @DefmacList {TS, [@code{H}], ms}
3824 @DefmacListEnd {TE, , ms}
3825 Denotes a table, to be processed by the @code{tbl} preprocessor.
3826 The optional argument@tie{}@code{H} to @code{TS} instructs @code{groff}
3827 to create a running header with the information
3828 up to the @code{TH} macro.
3829 @code{groff} prints the header at the beginning of the
3830 table; if the table runs onto another page, @code{groff}
3831 prints the header on the next page as well.
3834 @DefmacList {PS, , ms}
3835 @DefmacListEnd {PE, , ms}
3836 Denotes a graphic, to be processed by the @code{pic} preprocessor.
3837 You can create a @code{pic} file by hand, using the @acronym{AT&T}
3838 @code{pic} manual available on the Web as a reference, or by using
3839 a graphics program such as @code{xfig}.
3842 @DefmacList {EQ, [@Var{align}], ms}
3843 @DefmacListEnd {EN, , ms}
3844 Denotes an equation, to be processed by the @code{eqn} preprocessor.
3845 The optional @var{align} argument can be @code{C}, @code{L},
3846 or@tie{}@code{I} to center (the default), left-justify, or indent the
3850 @DefmacList {[, , ms}
3851 @DefmacListEnd {], , ms}
3852 Denotes a reference, to be processed by the @code{refer} preprocessor.
3853 The @acronym{GNU} @cite{refer(1)} man page provides a comprehensive
3854 reference to the preprocessor and the format of the bibliographic
3859 * Example multi-page table::
3862 @c ---------------------------------------------------------------------
3864 @node Example multi-page table, ms Footnotes, ms Insertions, ms Body Text
3865 @subsubsection An example multi-page table
3866 @cindex example markup, multi-page table [@code{ms}]
3867 @cindex multi-page table, example markup [@code{ms}]
3869 The following is an example of how to set up a
3870 table that may print across two or more pages.
3877 Text ...of heading...
3882 ... the rest of the table follows...
3888 @c ---------------------------------------------------------------------
3890 @node ms Footnotes, , Example multi-page table, ms Body Text
3891 @subsubsection Footnotes
3892 @cindex @code{ms} macros, footnotes
3893 @cindex footnotes [@code{ms}]
3895 The @file{ms} macro package has a flexible footnote system.
3896 You can specify either numbered footnotes or symbolic footnotes
3897 (that is, using a marker such as a dagger symbol).
3900 Specifies the location of a numbered footnote marker in the text.
3903 @DefmacList {FS, , ms}
3904 @DefmacListEnd {FE, , ms}
3905 Specifies the text of the footnote.
3906 The default action is to create a numbered footnote;
3907 you can create a symbolic footnote by specifying
3909 (such as @code{\[dg]} for the dagger glyph)
3910 in the body text and as an argument to the @code{FS} macro,
3911 followed by the text of the footnote
3912 and the @code{FE} macro.
3915 You can control how @code{groff}
3916 prints footnote numbers by changing the value of the
3917 @code{FF} register. @xref{ms Document Control Registers}.
3919 @c ---------------------------------------------------------------------
3921 @node ms Page Layout, Differences from AT&T ms, ms Body Text, ms
3922 @subsection Page layout
3923 @cindex @code{ms} macros, page layout
3924 @cindex page layout [@code{ms}]
3926 The default output from the @file{ms}
3927 macros provides a minimalist page layout:
3928 it prints a single column, with the page number centered at the top
3930 It prints no footers.
3932 You can change the layout by setting
3933 the proper number registers and strings.
3936 * ms Headers and Footers::
3938 * ms Multiple Columns::
3940 * ms Strings and Special Characters::
3943 @c ---------------------------------------------------------------------
3945 @node ms Headers and Footers, ms Margins, ms Page Layout, ms Page Layout
3946 @subsubsection Headers and footers
3947 @cindex @code{ms} macros, headers
3948 @cindex @code{ms} macros, footers
3949 @cindex headers [@code{ms}]
3950 @cindex footers [@code{ms}]
3952 For documents that do not distinguish between odd and even pages,
3953 set the following strings:
3955 @DefstrList {LH, ms}
3956 @DefstrItem {CH, ms}
3957 @DefstrListEnd {RH, ms}
3958 Sets the left, center, and right headers.
3961 @DefstrList {LF, ms}
3962 @DefstrItem {CF, ms}
3963 @DefstrListEnd {RF, ms}
3964 Sets the left, center, and right footers.
3968 For documents that need different information printed in the
3969 even and odd pages, use the following macros:
3971 @DefmacList {OH, @t{'}@Var{left}@t{'}@Var{center}@t{'}@Var{right}@t{'}, ms}
3972 @DefmacItem {EH, @t{'}@Var{left}@t{'}@Var{center}@t{'}@Var{right}@t{'}, ms}
3973 @DefmacItem {OF, @t{'}@Var{left}@t{'}@Var{center}@t{'}@Var{right}@t{'}, ms}
3974 @DefmacListEnd {EF, @t{'}@Var{left}@t{'}@Var{center}@t{'}@Var{right}@t{'}, ms}
3975 The @code{OH} and @code{EH} macros define headers for the odd and even pages;
3976 the @code{OF} and @code{EF} macros define footers for the odd and even pages.
3977 This is more flexible than defining the individual strings.
3979 You can replace the quote (@code{'}) marks with any character not
3980 appearing in the header or footer text.
3983 @c ---------------------------------------------------------------------
3985 @node ms Margins, ms Multiple Columns, ms Headers and Footers, ms Page Layout
3986 @subsubsection Margins
3987 @cindex @code{ms} macros, margins
3989 You control margins using a set of number registers.
3990 @xref{ms Document Control Registers}, for details.
3992 @c ---------------------------------------------------------------------
3994 @node ms Multiple Columns, ms TOC, ms Margins, ms Page Layout
3995 @subsubsection Multiple columns
3996 @cindex @code{ms} macros, multiple columns
3997 @cindex multiple columns [@code{ms}]
3999 The @file{ms} macros can set text in as many columns as will
4000 reasonably fit on the page.
4001 The following macros are available;
4002 all of them force a page break if a multi-column mode is already set.
4003 However, if the current mode is single-column, starting a multi-column
4004 mode does @strong{not} force a page break.
4014 @Defmac {MC, [@Var{width} [@Var{gutter}]], ms}
4016 If you specify no arguments, it is equivalent to the
4018 Otherwise, @var{width} is the width of each column and
4019 @var{gutter} is the space between columns.
4020 The @code{MINGW} number register controls the default gutter width.
4023 @c ---------------------------------------------------------------------
4025 @node ms TOC, ms Strings and Special Characters, ms Multiple Columns, ms Page Layout
4026 @subsubsection Creating a table of contents
4027 @cindex @code{ms} macros, creating table of contents
4028 @cindex table of contents, creating [@code{ms}]
4030 The facilities in the @file{ms} macro package for creating
4031 a table of contents are semi-automated at best.
4032 Assuming that you want the table of contents to consist of
4033 the document's headings, you need to repeat those headings
4034 wrapped in @code{XS} and @code{XE} macros.
4036 @DefmacList {XS, [@Var{page}], ms}
4037 @DefmacItem {XA, [@Var{page}], ms}
4038 @DefmacListEnd {XE, , ms}
4039 These macros define a table of contents
4040 or an individual entry in the table of contents,
4041 depending on their use.
4042 The macros are very simple; they cannot indent a heading based on its level.
4043 The easiest way to work around this is to add tabs
4044 to the table of contents string.
4045 The following is an example:
4067 You can manually create a table of contents
4068 by beginning with the @code{XS} macro for the first entry,
4069 specifying the page number for that entry as the argument to @code{XS}.
4070 Add subsequent entries using the @code{XA} macro,
4071 specifying the page number for that entry as the argument to @code{XA}.
4072 The following is an example:
4079 A Brief History of the Universe
4081 Details of Galactic Formation
4088 @Defmac {TC, [@code{no}], ms}
4089 Prints the table of contents on a new page,
4090 setting the page number to@tie{}@strong{i} (Roman numeral one).
4091 You should usually place this macro at the end of the
4092 file, since @code{groff} is a single-pass formatter and
4093 can only print what has been collected up to the point
4094 that the @code{TC} macro appears.
4096 The optional argument @code{no} suppresses printing
4097 the title specified by the string register @code{TOC}.
4100 @Defmac{PX, [@code{no}], ms}
4101 Prints the table of contents on a new page,
4102 using the current page numbering sequence.
4103 Use this macro to print a manually-generated table of contents
4104 at the beginning of your document.
4106 The optional argument @code{no} suppresses printing
4107 the title specified by the string register @code{TOC}.
4110 The @cite{Groff and Friends HOWTO}
4111 includes a @code{sed} script that automatically inserts
4112 @code{XS} and @code{XE} macro entries after each heading in a document.
4114 Altering the @code{NH} macro to automatically build the table
4115 of contents is perhaps initially more difficult, but would save
4116 a great deal of time in the long run if you use @file{ms} regularly.
4118 @c ---------------------------------------------------------------------
4120 @node ms Strings and Special Characters, , ms TOC, ms Page Layout
4121 @subsubsection Strings and Special Characters
4122 @cindex @code{ms} macros, strings
4123 @cindex @code{ms} macros, special characters
4124 @cindex @code{ms} macros, accent marks
4125 @cindex accent marks [@code{ms}]
4126 @cindex special characters [@code{ms}]
4127 @cindex strings [@code{ms}]
4129 The @file{ms} macros provide the following predefined strings.
4130 You can change the string definitions to help in creating
4131 documents in languages other than English.
4133 @Defstr {REFERENCES, ms}
4134 Contains the string printed at the beginning of the
4135 references (bibliography) page.
4136 The default is @samp{References}.
4139 @Defstr {ABSTRACT, ms}
4140 Contains the string printed at the beginning of the abstract.
4141 The default is @samp{ABSTRACT}.
4145 Contains the string printed at the beginning of the table of contents.
4148 @DefstrList {MONTH1, ms}
4149 @DefstrItem {MONTH2, ms}
4150 @DefstrItem {MONTH3, ms}
4151 @DefstrItem {MONTH4, ms}
4152 @DefstrItem {MONTH5, ms}
4153 @DefstrItem {MONTH6, ms}
4154 @DefstrItem {MONTH7, ms}
4155 @DefstrItem {MONTH8, ms}
4156 @DefstrItem {MONTH9, ms}
4157 @DefstrItem {MONTH10, ms}
4158 @DefstrItem {MONTH11, ms}
4159 @DefstrListEnd {MONTH12, ms}
4160 Prints the full name of the month in dates.
4161 The default is @samp{January}, @samp{February}, etc.
4164 The following special characters are available@footnote{For an
4165 explanation what special characters are see @ref{Special Characters}.}:
4171 @DefstrList {*Q, ms}
4172 @DefstrListEnd {*U, ms}
4173 Prints typographer's quotes in troff,
4174 plain quotes in nroff.
4175 @code{*Q} is the left quote and @code{*U} is the right quote.
4178 Improved accent marks are available in the @file{ms} macros.
4181 Specify this macro at the beginning of your document
4182 to enable extended accent marks and special characters.
4183 This is a Berkeley extension.
4185 To use the accent marks, place them @strong{after}
4186 the character being accented.
4189 The following accent marks are available
4190 after invoking the @code{AM} macro:
4212 @deffn String @t{\*[:]}
4214 @stindex : @r{[}ms@r{]}
4217 @stindex \*[@r{<colon>}] @r{[}ms@r{]}
4238 The following are standalone characters
4239 available after invoking the @code{AM} macro:
4242 Upside-down question mark.
4246 Upside-down exclamation point.
4278 Lowercase æ ligature.
4282 Uppercase Æ ligature.
4285 @c ---------------------------------------------------------------------
4287 @node Differences from AT&T ms, , ms Page Layout, ms
4288 @subsection Differences from @acronym{AT&T} @file{ms}
4289 @cindex @code{ms} macros, differences from @acronym{AT&T}
4290 @cindex @acronym{AT&T} @code{troff}, @code{ms} macro package differences
4292 This section lists the (minor) differences between the
4293 @code{groff -ms} macros and @acronym{AT&T}
4294 @code{troff -ms} macros.
4297 * Missing ms Macros::
4298 * Additional ms Macros::
4301 @c ---------------------------------------------------------------------
4303 @node Missing ms Macros, Additional ms Macros, Differences from AT&T ms, Differences from AT&T ms
4304 @subsubsection @code{troff} macros not appearing in @code{groff}
4306 Macros missing from @code{groff -ms}
4307 are cover page macros specific to Bell Labs.
4308 The macros known to be missing are:
4312 Technical memorandum; a cover sheet style
4315 Internal memorandum; a cover sheet style
4318 Memo for record; a cover sheet style
4321 Memo for file; a cover sheet style
4324 Engineer's notes; a cover sheet style
4327 Computing Science Tech Report; a cover sheet style
4333 Cover sheet information
4339 @c ---------------------------------------------------------------------
4341 @node Additional ms Macros, , Missing ms Macros, Differences from AT&T ms
4342 @subsubsection @code{groff} macros not appearing in @acronym{AT&T} @code{troff}
4344 The @code{groff -ms} macros have a few minor extensions
4345 compared to the @acronym{AT&T} @code{troff -ms} macros.
4348 Improved accent marks.
4349 @xref{ms Strings and Special Characters}, for details.
4352 @Defmac {DS, @t{I}, ms}
4354 The default behavior of @acronym{AT&T} @code{troff -ms}
4355 was to indent; the @code{groff} default prints displays
4356 flush left with the body text.
4360 Print text in @code{constant width} (Courier) font.
4364 Indexing term (printed on standard error).
4365 You can write a script to capture and process an index
4366 generated in this manner.
4370 The following additional number registers
4371 appear in @code{groff -ms}:
4373 @Defmpreg {MINGW, ms}
4374 Specifies a minimum space
4375 between columns (for multi-column output); this takes the
4376 place of the @code{GW} register that was documented but apparently
4377 not implemented in @acronym{AT&T} @code{troff}.
4381 Several new string registers are available as well.
4382 You can change these to handle (for example) the local language.
4383 @xref{ms Strings and Special Characters}, for details.
4386 @c =====================================================================
4388 @node me, mm, ms, Macro Packages
4390 @cindex @code{me} macro package
4392 @c XXX documentation
4393 @c XXX this is a placeholder until we get stuff knocked into shape
4394 See the @file{meintro.me} and @file{meref.me} documents in
4395 groff's @file{doc} directory.
4398 @c =====================================================================
4400 @node mm, , me, Macro Packages
4402 @cindex @code{mm} macro package
4404 @c XXX documentation
4405 @c XXX this is a placeholder until we get stuff knocked into shape
4406 See the @cite{groff_mm(7)} man page (type @command{man groff_mm} at
4410 @c =====================================================================
4411 @c =====================================================================
4413 @node gtroff Reference, Preprocessors, Macro Packages, Top
4414 @chapter @code{gtroff} Reference
4415 @cindex reference, @code{gtroff}
4416 @cindex @code{gtroff}, reference
4418 This chapter covers @strong{all} of the facilities of @code{gtroff}.
4419 Users of macro packages may skip it if not interested in details.
4427 * Embedded Commands::
4429 * Manipulating Filling and Adjusting::
4430 * Manipulating Hyphenation::
4431 * Manipulating Spacing::
4433 * Character Translations::
4434 * Troff and Nroff Mode::
4439 * Fonts and Symbols::
4442 * Conditionals and Loops::
4445 * Drawing Requests::
4449 * Suppressing output::
4452 * Postprocessor Access::
4454 * Gtroff Internals::
4456 * Implementation Differences::
4460 @c =====================================================================
4462 @node Text, Measurements, gtroff Reference, gtroff Reference
4464 @cindex text, @code{gtroff} processing
4466 @code{gtroff} input files contain text with control commands
4467 interspersed throughout. But, even without control codes, @code{gtroff}
4468 still does several things with the input text:
4472 filling and adjusting
4475 adding additional space after sentences
4481 inserting implicit line breaks
4485 * Filling and Adjusting::
4489 * Implicit Line Breaks::
4490 * Input Conventions::
4494 @c ---------------------------------------------------------------------
4496 @node Filling and Adjusting, Hyphenation, Text, Text
4497 @subsection Filling and Adjusting
4501 When @code{gtroff} reads text, it collects words from the input and fits
4502 as many of them together on one output line as it can. This is known as
4505 @cindex leading spaces
4506 @cindex spaces, leading and trailing
4507 @cindex extra spaces
4508 @cindex trailing spaces
4509 Once @code{gtroff} has a @dfn{filled} line, it tries to @dfn{adjust}
4510 it. This means it widens the spacing between words until the text
4511 reaches the right margin (in the default adjustment mode). Extra spaces
4512 between words are preserved, but spaces at the end of lines are ignored.
4513 Spaces at the front of a line cause a @dfn{break} (breaks are
4514 explained in @ref{Implicit Line Breaks}).
4516 @xref{Manipulating Filling and Adjusting}.
4518 @c ---------------------------------------------------------------------
4520 @node Hyphenation, Sentences, Filling and Adjusting, Text
4521 @subsection Hyphenation
4524 Since the odds are not great for finding a set of words, for every
4525 output line, which fit nicely on a line without inserting excessive
4526 amounts of space between words, @code{gtroff} hyphenates words so
4527 that it can justify lines without inserting too much space between
4528 words. It uses an internal hyphenation algorithm (a simplified version
4529 of the algorithm used within @TeX{}) to indicate which words can be
4530 hyphenated and how to do so. When a word is hyphenated, the first part
4531 of the word is added to the current filled line being output (with
4532 an attached hyphen), and the other portion is added to the next
4535 @xref{Manipulating Hyphenation}.
4537 @c ---------------------------------------------------------------------
4539 @node Sentences, Tab Stops, Hyphenation, Text
4540 @subsection Sentences
4543 Although it is often debated, some typesetting rules say there should be
4544 different amounts of space after various punctuation marks. For
4545 example, the @cite{Chicago typsetting manual} says that a period at the
4546 end of a sentence should have twice as much space following it as would
4547 a comma or a period as part of an abbreviation.
4549 @c XXX exact citation of Chicago manual
4551 @cindex sentence space
4552 @cindex space between sentences
4553 @cindex french-spacing
4554 @code{gtroff} does this by flagging certain characters (normally
4555 @samp{!}, @samp{?}, and @samp{.}) as @dfn{end-of-sentence} characters.
4556 When @code{gtroff} encounters one of these characters at the end of a
4557 line, it appends a normal space followed by a @dfn{sentence space} in
4558 the formatted output. (This justifies one of the conventions mentioned
4559 in @ref{Input Conventions}.)
4561 @cindex transparent characters
4562 @cindex character, transparent
4563 @cindex @code{dg} glyph, at end of sentence
4564 @cindex @code{rq} glyph, at end of sentence
4565 @cindex @code{"}, at end of sentence
4566 @cindex @code{'}, at end of sentence
4567 @cindex @code{)}, at end of sentence
4568 @cindex @code{]}, at end of sentence
4569 @cindex @code{*}, at end of sentence
4570 In addition, the following characters and symbols are treated
4571 transparently while handling end-of-sentence characters: @samp{"},
4572 @samp{'}, @samp{)}, @samp{]}, @samp{*}, @code{\[dg]}, and @code{\[rq]}.
4574 See the @code{cflags} request in @ref{Using Symbols}, for more details.
4576 @cindex @code{\&}, at end of sentence
4577 To prevent the insertion of extra space after an end-of-sentence
4578 character (at the end of a line), append @code{\&}.
4580 @c ---------------------------------------------------------------------
4582 @node Tab Stops, Implicit Line Breaks, Sentences, Text
4583 @subsection Tab Stops
4585 @cindex stops, tabulator
4586 @cindex tab character
4587 @cindex character, tabulator
4589 @cindex @acronym{EBCDIC} encoding
4590 @cindex encoding, @acronym{EBCDIC}
4591 @code{gtroff} translates @dfn{tabulator characters}, also called
4592 @dfn{tabs} (normally code point @acronym{ASCII} @code{0x09} or
4593 @acronym{EBCDIC} @code{0x05}), in the input into movements to the next
4594 tabulator stop. These tab stops are initially located every half inch
4595 across the page. Using this, simple tables can be made easily.
4596 However, it can often be deceptive as the appearance (and width) of the
4597 text on a terminal and the results from @code{gtroff} can vary greatly.
4599 Also, a possible sticking point is that lines beginning with tab
4600 characters are still filled, again producing unexpected results.
4601 For example, the following input
4603 @multitable {12345678} {12345678} {12345678} {12345678}
4605 @tab 1 @tab 2 @tab 3
4613 @multitable {12345678} {12345678} {12345678} {12345678} {12345678} {12345678} {12345678}
4615 @tab 1 @tab 2 @tab 3 @tab @tab 4 @tab 5
4618 @xref{Tabs and Fields}.
4620 @c ---------------------------------------------------------------------
4622 @node Implicit Line Breaks, Input Conventions, Tab Stops, Text
4623 @subsection Implicit Line Breaks
4624 @cindex implicit line breaks
4625 @cindex implicit breaks of lines
4626 @cindex line, implicit breaks
4627 @cindex break, implicit
4630 An important concept in @code{gtroff} is the @dfn{break}. When a break
4631 occurs, @code{gtroff} outputs the partially filled line
4632 (unjustified), and resumes collecting and filling text on the next output
4638 @cindex blank line macro (@code{blm})
4639 There are several ways to cause a break in @code{gtroff}. A blank
4640 line not only causes a break, but it also outputs a one-line vertical
4641 space (effectively a blank line). Note that this behaviour can be
4642 modified with the blank line macro request @code{blm}.
4643 @xref{Blank Line Traps}.
4647 A line that begins with a space causes a break and the space is
4648 output at the beginning of the next line. Note that this space isn't
4649 adjusted, even in fill mode.
4651 The end of file also causes a break -- otherwise the last line of
4652 the document may vanish!
4654 Certain requests also cause breaks, implicitly or explicitly. This is
4655 discussed in @ref{Manipulating Filling and Adjusting}.
4657 @c ---------------------------------------------------------------------
4659 @node Input Conventions, Input Encodings, Implicit Line Breaks, Text
4660 @subsection Input Conventions
4661 @cindex input conventions
4662 @cindex conventions for input
4664 Since @code{gtroff} does filling automatically, it is traditional in
4665 @code{groff} not to try and type things in as nicely formatted
4666 paragraphs. These are some conventions commonly used when typing
4671 Break lines after punctuation, particularly at the end of a sentence
4672 and in other logical places. Keep separate phrases on lines by
4673 themselves, as entire phrases are often added or deleted when editing.
4676 Try to keep lines less than 40-60@tie{}characters, to allow space for
4677 inserting more text.
4680 Do not try to do any formatting in a @acronym{WYSIWYG} manner (i.e.,
4681 don't try using spaces to get proper indentation).
4684 @c ---------------------------------------------------------------------
4686 @node Input Encodings, , Input Conventions, Text
4687 @subsection Input Encodings
4689 Currently, the following input encodings are available.
4693 @cindex encoding, input, @acronym{EBCDIC}
4694 @cindex @acronym{EBCDIC}, input encoding
4695 @cindex input encoding, @acronym{EBCDIC}
4696 @cindex encoding, input, cp1047
4697 @cindex cp1047, input encoding
4698 @cindex input encoding, cp1047
4699 @cindex IBM cp1047 input encoding
4701 This input encoding works only on @acronym{EBCDIC} platforms (and vice
4702 versa, the other input encodings don't work with @acronym{EBCDIC}); the
4703 file @file{cp1047.tmac} is by default loaded at start-up.
4706 @cindex encoding, input, @w{latin-1} (ISO @w{8859-1})
4707 @cindex @w{latin-1} (ISO @w{8859-1}), input encoding
4708 @cindex ISO @w{8859-1} (@w{latin-1}), input encoding
4709 @cindex input encoding, @w{latin-1} (ISO @w{8859-1})
4711 This is the default input encoding on non-@acronym{EBCDIC} platforms;
4712 the file @file{latin1.tmac} is loaded at start-up.
4715 @cindex encoding, input, @w{latin-2} (ISO @w{8859-2})
4716 @cindex @w{latin-2} (ISO @w{8859-2}), input encoding
4717 @cindex ISO @w{8859-2} (@w{latin-2}), input encoding
4718 @cindex input encoding, @w{latin-2} (ISO @w{8859-2})
4720 To use this encoding, either say @w{@samp{.mso latin2.tmac}} at the very
4721 beginning of your document or use @samp{-mlatin2} as a command line
4722 argument for @code{groff}.
4724 @item latin-9 (latin-0)
4725 @cindex encoding, input, @w{latin-9} (@w{latin-0}, ISO @w{8859-15})
4726 @cindex @w{latin-9} (@w{latin-0}, ISO @w{8859-15}), input encoding
4727 @cindex ISO @w{8859-15} (@w{latin-9}, @w{latin-0}), input encoding
4728 @cindex input encoding, @w{latin-9} (@w{latin-9}, ISO @w{8859-15})
4730 This encoding is intended (at least in Europe) to replace @w{latin-1}
4731 encoding. The main difference to @w{latin-1} is that @w{latin-9}
4732 contains the Euro character. To use this encoding, either say
4733 @w{@samp{.mso latin9.tmac}} at the very beginning of your document or
4734 use @samp{-mlatin9} as a command line argument for @code{groff}.
4737 Note that it can happen that some input encoding characters are not
4738 available for a particular output device. For example, saying
4741 groff -Tlatin1 -mlatin9 ...
4745 will fail if you use the Euro character in the input. Usually, this
4746 limitation is present only for devices which have a limited set of
4747 output glyphs (e.g.@: @option{-Tascii} and @option{-Tlatin1}); for other
4748 devices it is usually sufficient to install proper fonts which contain
4749 the necessary glyphs.
4751 @pindex freeeuro.pfa
4753 Due to the importance of the Euro glyph in Europe, the groff package now
4754 comes with a @sc{PostScript} font called @file{freeeuro.pfa} which
4755 provides various glyph shapes for the Euro. With other words,
4756 @w{latin-9} encoding is supported for the @option{-Tps} device out of
4757 the box (@w{latin-2} isn't).
4759 By its very nature, @option{-Tutf8} supports all input encodings;
4760 @option{-Tdvi} has support for both @w{latin-2} and @w{latin-9} if the
4761 command line @option{-mec} is used also to load the file @file{ec.tmac}
4762 (which flips to the EC fonts).
4765 @c =====================================================================
4767 @node Measurements, Expressions, Text, gtroff Reference
4768 @section Measurements
4769 @cindex measurements
4771 @cindex units of measurement
4772 @cindex basic unit (@code{u})
4773 @cindex machine unit (@code{u})
4774 @cindex measurement unit
4775 @cindex @code{u} unit
4776 @cindex unit, @code{u}
4777 @code{gtroff} (like many other programs) requires numeric parameters to
4778 specify various measurements. Most numeric parameters@footnote{those
4779 that specify vertical or horizontal motion or a type size} may have a
4780 @dfn{measurement unit} attached. These units are specified as a single
4781 character which immediately follows the number or expression. Each of
4782 these units are understood, by @code{gtroff}, to be a multiple of its
4783 @dfn{basic unit}. So, whenever a different measurement unit is
4784 specified @code{gtroff} converts this into its @dfn{basic units}. This
4785 basic unit, represented by a @samp{u}, is a device dependent measurement
4786 which is quite small, ranging from 1/75@dmn{th} to 1/72000@dmn{th} of an
4787 inch. The values may be given as fractional numbers; however,
4788 fractional basic units are always rounded to integers.
4790 Some of the measurement units are completely independent of any of the
4791 current settings (e.g.@: type size) of @code{gtroff}.
4795 @cindex inch unit (@code{i})
4796 @cindex @code{i} unit
4797 @cindex unit, @code{i}
4798 Inches. An antiquated measurement unit still in use in certain
4799 backwards countries with incredibly low-cost computer equipment. One
4800 inch is equal to@tie{}2.54@dmn{cm}.
4803 @cindex centimeter unit (@code{c})
4804 @cindex @code{c} unit
4805 @cindex unit, @code{c}
4806 Centimeters. One centimeter is equal to@tie{}0.3937@dmn{in}.
4809 @cindex point unit (@code{p})
4810 @cindex @code{p} unit
4811 @cindex unit, @code{p}
4812 Points. This is a typesetter's measurement used for measure type size.
4813 It is 72@tie{}points to an inch.
4816 @cindex pica unit (@code{P})
4817 @cindex @code{P} unit
4818 @cindex unit, @code{P}
4819 Pica. Another typesetting measurement. 6@tie{}Picas to an inch (and
4820 12@tie{}points to a pica).
4824 @cindex @code{s} unit
4825 @cindex unit, @code{s}
4826 @cindex @code{z} unit
4827 @cindex unit, @code{z}
4828 @xref{Fractional Type Sizes}, for a discussion of these units.
4831 @cindex @code{f} unit
4832 @cindex unit, @code{f}
4833 Fractions. Value is 65536.
4834 @xref{Colors}, for usage.
4837 The other measurements understood by @code{gtroff} depend on
4838 settings currently in effect in @code{gtroff}. These are very useful
4839 for specifying measurements which should look proper with any size of
4844 @cindex em unit (@code{m})
4845 @cindex @code{m} unit
4846 @cindex unit, @code{m}
4847 Ems. This unit is equal to the current font size in points. So called
4848 because it is @emph{approximately} the width of the letter@tie{}@samp{m}
4849 in the current font.
4852 @cindex en unit (@code{n})
4853 @cindex @code{n} unit
4854 @cindex unit, @code{n}
4855 Ens. In @code{groff}, this is half of an em.
4858 @cindex vertical space unit (@code{v})
4859 @cindex space, vertical, unit (@code{v})
4860 @cindex @code{v} unit
4861 @cindex unit, @code{v}
4862 Vertical space. This is equivalent to the current line spacing.
4863 @xref{Sizes}, for more information about this.
4866 @cindex @code{M} unit
4867 @cindex unit, @code{M}
4875 @c ---------------------------------------------------------------------
4877 @node Default Units, , Measurements, Measurements
4878 @subsection Default Units
4879 @cindex default units
4880 @cindex units, default
4882 Many requests take a default unit. While this can be helpful at times,
4883 it can cause strange errors in some expressions. For example, the line
4884 length request expects em units. Here are several attempts to get a
4885 line length of 3.5@tie{}inches and their results:
4891 (7 / 2)u @result{} 0i
4893 7i/2u @result{} 3.5i
4897 Everything is converted to basic units first. In the above example it
4898 is assumed that 1@dmn{i} equals@tie{}240@dmn{u}, and 1@dmn{m}
4899 equals@tie{}10@dmn{p} (thus 1@dmn{m} equals@tie{}33@dmn{u}). The value
4900 7@dmn{i}/2 is first handled as 7@dmn{i}/2@dmn{m}, then converted to
4901 1680@dmn{u}/66@dmn{u} which is 25@dmn{u}, and this is approximately
4902 0.1@dmn{i}. As can be seen, a scaling indicator after a closing
4903 parenthesis is simply ignored.
4905 @cindex measurements, specifying safely
4906 Thus, the safest way to specify measurements is to always
4907 attach a scaling indicator. If you want to multiply or divide by a
4908 certain scalar value, use @samp{u} as the unit for that value.
4911 @c =====================================================================
4913 @node Expressions, Identifiers, Measurements, gtroff Reference
4914 @section Expressions
4917 @code{gtroff} has most arithmetic operators common to other languages:
4921 @cindex arithmetic operators
4922 @cindex operators, arithmetic
4928 Arithmetic: @samp{+} (addition), @samp{-} (subtraction), @samp{/}
4929 (division), @samp{*} (multiplication), @samp{%} (modulo).
4931 @code{gtroff} only provides integer arithmetic. The internal type used
4932 for computing results is @samp{int}, which is usually a 32@dmn{bit}
4936 @cindex comparison operators
4937 @cindex operators, comparison
4944 Comparison: @samp{<} (less than), @samp{>} (greater than), @samp{<=}
4945 (less than or equal), @samp{>=} (greater than or equal), @samp{=}
4946 (equal), @samp{==} (the same as @samp{=}).
4949 @cindex logical operators
4950 @cindex operators, logical
4956 @opindex @r{<colon>}
4958 Logical: @samp{&} (logical and), @samp{:} (logical or).
4961 @cindex unary operators
4962 @cindex operators, unary
4966 @cindex @code{if} request, and the @samp{!} operator
4967 @cindex @code{while} request, and the @samp{!} operator
4968 Unary operators: @samp{-} (negating, i.e.@: changing the sign), @samp{+}
4969 (just for completeness; does nothing in expressions), @samp{!} (logical
4970 not; this works only within @code{if} and @code{while} requests). See
4971 below for the use of unary operators in motion requests.
4974 @cindex extremum operators (@code{>?}, @code{<?})
4975 @cindex operators, extremum (@code{>?}, @code{<?})
4978 Extrema: @samp{>?} (maximum), @samp{<?} (minimum).
4985 .nr z (\n[x] >? \n[y])
4989 The register@tie{}@code{z} now contains@tie{}5.
4992 @cindex scaling operator
4993 @cindex operator, scaling
4994 Scaling: @code{(@var{c};@var{e})}. Evaluate@tie{}@var{e} using@tie{}@var{c}
4995 as the default scaling indicator. If @var{c} is missing, ignore scaling
4996 indicators in the evaluation of@tie{}@var{e}.
5000 @cindex order of evaluation in expressions
5001 @cindex expression, order of evaluation
5004 Parentheses may be used as in any other language. However, in
5005 @code{gtroff} they are necessary to ensure order of evaluation.
5006 @code{gtroff} has no operator precedence; expressions are evaluated left
5007 to right. This means that @code{gtroff} evaluates @samp{3+5*4} as if it were
5008 parenthesized like @samp{(3+5)*4}, not as @samp{3+(5*4)}, as might be
5011 @cindex @code{+}, and page motion
5012 @cindex @code{-}, and page motion
5013 @cindex motion operators
5014 @cindex operators, motion
5015 For many requests which cause a motion on the page, the unary operators
5016 @samp{+} and @samp{-} work differently if leading an expression. They
5017 then indicate a motion relative to the current position (down or up,
5020 @cindex @code{|}, and page motion
5021 @cindex absolute position operator (@code{|})
5022 @cindex position, absolute, operator (@code{|})
5023 Similarly, a leading @samp{|} operator indicates an absolute position.
5024 For vertical movements, it specifies the distance from the top of the
5025 page; for horizontal movements, it gives the distance from the beginning
5026 of the @emph{input} line.
5028 @cindex @code{bp} request, using @code{+} and@tie{}@code{-}
5029 @cindex @code{in} request, using @code{+} and@tie{}@code{-}
5030 @cindex @code{ll} request, using @code{+} and@tie{}@code{-}
5031 @cindex @code{lt} request, using @code{+} and@tie{}@code{-}
5032 @cindex @code{nm} request, using @code{+} and@tie{}@code{-}
5033 @cindex @code{nr} request, using @code{+} and@tie{}@code{-}
5034 @cindex @code{pl} request, using @code{+} and@tie{}@code{-}
5035 @cindex @code{pn} request, using @code{+} and@tie{}@code{-}
5036 @cindex @code{po} request, using @code{+} and@tie{}@code{-}
5037 @cindex @code{ps} request, using @code{+} and@tie{}@code{-}
5038 @cindex @code{pvs} request, using @code{+} and@tie{}@code{-}
5039 @cindex @code{rt} request, using @code{+} and@tie{}@code{-}
5040 @cindex @code{ti} request, using @code{+} and@tie{}@code{-}
5041 @cindex @code{\H}, using @code{+} and@tie{}@code{-}
5042 @cindex @code{\R}, using @code{+} and@tie{}@code{-}
5043 @cindex @code{\s}, using @code{+} and@tie{}@code{-}
5044 @samp{+} and @samp{-} are also treated differently by the following
5045 requests and escapes: @code{bp}, @code{in}, @code{ll}, @code{lt},
5046 @code{nm}, @code{nr}, @code{pl}, @code{pn}, @code{po}, @code{ps},
5047 @code{pvs}, @code{rt}, @code{ti}, @code{\H}, @code{\R}, and @code{\s}.
5048 Here, leading plus and minus signs indicate increments and decrements.
5050 @xref{Setting Registers}, for some examples.
5052 @Defesc {\\B, ', anything, '}
5053 @cindex numeric expression, valid
5054 @cindex valid numeric expression
5055 Return@tie{}1 if @var{anything} is a valid numeric expression;
5056 or@tie{}0 if @var{anything} is empty or not a valid numeric expression.
5059 @cindex space characters, in expressions
5060 @cindex expressions, and space characters
5061 Due to the way arguments are parsed, spaces are not allowed in
5062 expressions, unless the entire expression is surrounded by parentheses.
5064 @xref{Request and Macro Arguments}, and @ref{Conditionals and Loops}.
5067 @c =====================================================================
5069 @node Identifiers, Embedded Commands, Expressions, gtroff Reference
5070 @section Identifiers
5073 Like any other language, @code{gtroff} has rules for properly formed
5074 @dfn{identifiers}. In @code{gtroff}, an identifier can be made up of
5075 almost any printable character, with the exception of the following
5080 @cindex whitespace characters
5081 @cindex newline character
5082 @cindex character, whitespace
5083 Whitespace characters (spaces, tabs, and newlines).
5086 @cindex character, backspace
5087 @cindex backspace character
5088 @cindex @acronym{EBCDIC} encoding of backspace
5089 Backspace (@acronym{ASCII}@tie{}@code{0x08} or
5090 @acronym{EBCDIC}@tie{}@code{0x16}) and character code @code{0x01}.
5093 @cindex invalid input characters
5094 @cindex input characters, invalid
5095 @cindex characters, invalid input
5097 The following input characters are invalid and are ignored if
5098 @code{groff} runs on a machine based on @acronym{ASCII}, causing a
5099 warning message of type @samp{input} (see @ref{Debugging}, for more
5100 details): @code{0x00}, @code{0x0B}, @code{0x0D}-@code{0x1F},
5101 @code{0x80}-@code{0x9F}.
5103 And here are the invalid input characters if @code{groff} runs on an
5104 @acronym{EBCDIC} host: @code{0x00}, @code{0x08}, @code{0x09},
5105 @code{0x0B}, @code{0x0D}-@code{0x14}, @code{0x17}-@code{0x1F},
5106 @code{0x30}-@code{0x3F}.
5108 Currently, some of these reserved codepoints are used internally, thus
5109 making it non-trivial to extend @code{gtroff} to cover Unicode or other
5110 character sets and encodings which use characters of these ranges.
5112 Note that invalid characters are removed before parsing; an
5113 identifier @code{foo}, followed by an invalid character, followed by
5114 @code{bar} is treated as @code{foobar}.
5117 For example, any of the following is valid.
5127 @cindex @code{]}, as part of an identifier
5129 Note that identifiers longer than two characters with a closing bracket
5130 (@samp{]}) in its name can't be accessed with escape sequences which
5131 expect an identifier as a parameter. For example, @samp{\[foo]]}
5132 accesses the glyph @samp{foo}, followed by @samp{]}, whereas
5133 @samp{\C'foo]'} really asks for glyph @samp{foo]}.
5135 @cindex @code{refer}, and macro names starting with @code{[} or @code{]}
5136 @cindex @code{[}, macro names starting with, and @code{refer}
5137 @cindex @code{]}, macro names starting with, and @code{refer}
5138 @cindex macro names, starting with @code{[} or @code{]}, and @code{refer}
5139 To avoid problems with the @code{refer} preprocessor, macro names
5140 should not start with @samp{[} or @samp{]}. Due to backwards
5141 compatibility, everything after @samp{.[} and @samp{.]} is handled as
5142 a special argument to @code{refer}. For example, @samp{.[foo} makes
5143 @code{refer} to start a reference, using @samp{foo} as a parameter.
5145 @Defesc {\\A, ', ident, '}
5146 Test whether an identifier @var{ident} is valid in @code{gtroff}. It
5147 expands to the character@tie{}1 or@tie{}0 according to whether its
5148 argument (usually delimited by quotes) is or is not acceptable as the
5149 name of a string, macro, diversion, number register, environment, or
5150 font. It returns@tie{}0 if no argument is given. This is useful for
5151 looking up user input in some sort of associative table.
5159 @xref{Escapes}, for details on parameter delimiting characters.
5161 Identifiers in @code{gtroff} can be any length, but, in some contexts,
5162 @code{gtroff} needs to be told where identifiers end and text begins
5163 (and in different ways depending on their length):
5169 @cindex @code{(}, starting a two-character identifier
5171 Two characters. Must be prefixed with @samp{(} in some situations.
5173 @cindex @code{[}, starting an identifier
5174 @cindex @code{]}, ending an identifier
5176 Arbitrary length (@code{gtroff} only). Must be bracketed with @samp{[}
5177 and@tie{}@samp{]} in some situations. Any length identifier can be put
5181 @cindex undefined identifiers
5182 @cindex identifiers, undefined
5183 Unlike many other programming languages, undefined identifiers are
5184 silently ignored or expanded to nothing.
5185 When @code{gtroff} finds an undefined identifier, it emits a
5186 warning, doing the following:
5190 If the identifier is a string, macro, or diversion,
5191 @code{gtroff} defines it as empty.
5194 If the identifier is a number register, @code{gtroff}
5195 defines it with a value of@tie{}0.
5198 @xref{Warnings}., @ref{Interpolating Registers}, and @ref{Strings}.
5200 Note that macros, strings, and diversions share the same name space.
5217 As can be seen in the previous example, @code{gtroff} reuses the
5218 identifier @samp{xxx}, changing it from a macro to a diversion.
5219 No warning is emitted! The contents of the first macro definition is
5222 @xref{Interpolating Registers}, and @ref{Strings}.
5225 @c =====================================================================
5227 @node Embedded Commands, Registers, Identifiers, gtroff Reference
5228 @section Embedded Commands
5229 @cindex embedded commands
5230 @cindex commands, embedded
5232 Most documents need more functionality beyond filling, adjusting and
5233 implicit line breaking. In order to gain further functionality,
5234 @code{gtroff} allows commands to be embedded into the text, in two ways.
5236 The first is a @dfn{request} which takes up an entire line, and does
5237 some large-scale operation (e.g.@: break lines, start new pages).
5239 The other is an @dfn{escape} which can be usually embedded anywhere
5240 in the text; most requests can accept it even as an argument.
5241 Escapes generally do more minor operations like sub- and superscripts,
5242 print a symbol, etc.
5250 @c ---------------------------------------------------------------------
5252 @node Requests, Macros, Embedded Commands, Embedded Commands
5253 @subsection Requests
5256 @cindex control character (@code{.})
5257 @cindex character, control (@code{.})
5258 @cindex no-break control character (@code{'})
5259 @cindex character, no-break control (@code{'})
5260 @cindex control character, no-break (@code{'})
5261 A request line begins with a control character, which is either a single
5262 quote (@samp{'}, the @dfn{no-break control character}) or a period
5263 (@samp{.}, the normal @dfn{control character}). These can be changed;
5264 see @ref{Character Translations}, for details. After this there may be
5265 optional tabs or spaces followed by an identifier which is the name of
5266 the request. This may be followed by any number of space-separated
5267 arguments (@emph{no} tabs here).
5269 @cindex structuring source code of documents or macro packages
5270 @cindex documents, structuring the source code
5271 @cindex macro packages, structuring the source code
5272 Since a control character followed by whitespace only is ignored, it
5273 is common practice to use this feature for structuring the source code
5274 of documents or macro packages.
5288 @cindex blank line macro (@code{blm})
5289 Another possibility is to use the blank line macro request @code{blm}
5290 by assigning an empty macro to it.
5295 .blm do-nothing \" activate blank line macro
5306 .blm \" deactivate blank line macro
5309 @xref{Blank Line Traps}.
5311 @cindex zero width space character (@code{\&})
5312 @cindex character, zero width space (@code{\&})
5313 @cindex space character, zero width (@code{\&})
5314 @cindex @code{\&}, escaping control characters
5315 To begin a line with a control character without it being interpreted,
5316 precede it with @code{\&}. This represents a zero width space, which
5317 means it does not affect the output.
5319 In most cases the period is used as a control character. Several
5320 requests cause a break implicitly; using the single quote control
5321 character prevents this.
5324 * Request and Macro Arguments::
5327 @node Request and Macro Arguments, , Requests, Requests
5328 @subsubsection Request and Macro Arguments
5329 @cindex request arguments
5330 @cindex macro arguments
5331 @cindex arguments to requests and macros
5333 Arguments to requests and macros are processed much like the shell:
5334 The line is split into arguments according to
5335 spaces.@footnote{Plan@tie{}9's @code{troff} implementation also allows
5336 tabs for argument separation -- @code{gtroff} intentionally doesn't
5339 @cindex spaces, in a macro argument
5340 An argument to a macro which is intended to contain spaces can either be
5341 enclosed in double quotes, or have the spaces @dfn{escaped} with
5342 backslashes. This is @emph{not} true for requests.
5344 Here are a few examples for a hypothetical macro @code{uh}:
5347 .uh The Mouse Problem
5348 .uh "The Mouse Problem"
5349 .uh The\ Mouse\ Problem
5352 @cindex @code{\~}, difference to @code{\@key{SP}}
5353 @cindex @code{\@key{SP}}, difference to @code{\~}
5355 The first line is the @code{uh} macro being called with 3 arguments,
5356 @samp{The}, @samp{Mouse}, and @samp{Problem}. The latter two have the
5357 same effect of calling the @code{uh} macro with one argument, @samp{The
5358 Mouse Problem}.@footnote{The last solution, i.e., using escaped spaces,
5359 is ``classical'' in the sense that it can be found in most @code{troff}
5360 documents. Nevertheless, it is not optimal in all situations, since
5361 @w{@samp{\ }} inserts a fixed-width, non-breaking space character which
5362 can't stretch. @code{gtroff} provides a different command @code{\~} to
5363 insert a stretchable, non-breaking space.}
5365 @cindex @code{"}, in a macro argument
5366 @cindex double quote, in a macro argument
5367 A double quote which isn't preceded by a space doesn't start a macro
5368 argument. If not closing a string, it is printed literally.
5373 .xxx a" "b c" "de"fg"
5377 has the arguments @samp{a"}, @w{@samp{b c}}, @samp{de}, and @samp{fg"}.
5378 Don't rely on this obscure behaviour!
5380 There are two possibilities to get a double quote reliably.
5384 Enclose the whole argument with double quotes and use two consecutive double
5385 quotes to represent a single one. This traditional solution has the
5386 disadvantage that double quotes don't survive argument expansion again if
5387 called in compatibility mode (using the @option{-C} option of @code{groff}):
5391 . tm xx: `\\$1' `\\$2' `\\$3'
5393 . yy "\\$1" "\\$2" "\\$3"
5396 . tm yy: `\\$1' `\\$2' `\\$3'
5398 .xx A "test with ""quotes""" .
5399 @result{} xx: `A' `test with "quotes"' `.'
5400 @result{} yy: `A' `test with ' `quotes""'
5404 If not in compatibility mode, you get the expected result
5407 xx: `A' `test with "quotes"' `.'
5408 yy: `A' `test with "quotes"' `.'
5412 since @code{gtroff} preserves the input level.
5415 Use the double quote glyph @code{\(dq}. This works with and without
5416 compatibility mode enabled since @code{gtroff} doesn't convert @code{\(dq}
5417 back to a double quote input character.
5419 Not that this method won't work with @acronym{UNIX} @code{troff} in general
5420 since the glyph `dq' isn't defined normally.
5423 @cindex @code{ds} request, and double quotes
5424 Double quotes in the @code{ds} request are handled differently.
5425 @xref{Strings}, for more details.
5427 @c ---------------------------------------------------------------------
5429 @node Macros, Escapes, Requests, Embedded Commands
5433 @code{gtroff} has a @dfn{macro} facility for defining a series of lines
5434 which can be invoked by name. They are called in the same manner as
5435 requests -- arguments also may be passed basically in the same manner.
5437 @xref{Writing Macros}, and @ref{Request and Macro Arguments}.
5439 @c ---------------------------------------------------------------------
5441 @node Escapes, , Macros, Embedded Commands
5445 Escapes may occur anywhere in the input to @code{gtroff}. They usually
5446 begin with a backslash and are followed by a single character which
5447 indicates the function to be performed. The escape character can be
5448 changed; see @ref{Character Translations}.
5450 Escape sequences which require an identifier as a parameter accept three
5451 possible syntax forms.
5455 The next single character is the identifier.
5457 @cindex @code{(}, starting a two-character identifier
5459 If this single character is an opening parenthesis, take the following
5460 two characters as the identifier. Note that there is no closing
5461 parenthesis after the identifier.
5463 @cindex @code{[}, starting an identifier
5464 @cindex @code{]}, ending an identifier
5466 If this single character is an opening bracket, take all characters
5467 until a closing bracket as the identifier.
5479 @cindex @code{'}, delimiting arguments
5480 @cindex argument delimiting characters
5481 @cindex characters, argument delimiting
5482 @cindex delimiting characters for arguments
5483 Other escapes may require several arguments and/or some special format.
5484 In such cases the argument is traditionally enclosed in single quotes
5485 (and quotes are always used in this manual for the definitions of escape
5486 sequences). The enclosed text is then processed according to what that
5487 escape expects. Example:
5493 @cindex @code{\o}, possible quote characters
5494 @cindex @code{\b}, possible quote characters
5495 @cindex @code{\X}, possible quote characters
5496 Note that the quote character can be replaced with any other character
5497 which does not occur in the argument (even a newline or a space
5498 character) in the following escapes: @code{\o}, @code{\b}, and
5499 @code{\X}. This makes e.g.
5508 @result{} A café in Paris
5512 possible, but it is better not to use this feature to avoid confusion.
5514 @cindex @code{\%}, used as delimiter
5515 @cindex @code{\@key{SP}}, used as delimiter
5516 @cindex @code{\|}, used as delimiter
5517 @cindex @code{\^}, used as delimiter
5518 @cindex @code{\@{}, used as delimiter
5519 @cindex @code{\@}}, used as delimiter
5520 @cindex @code{\'}, used as delimiter
5521 @cindex @code{\`}, used as delimiter
5522 @cindex @code{\-}, used as delimiter
5523 @cindex @code{\_}, used as delimiter
5524 @cindex @code{\!}, used as delimiter
5525 @cindex @code{\?}, used as delimiter
5526 @cindex @code{\@@}, used as delimiter
5527 @cindex @code{\)}, used as delimiter
5528 @cindex @code{\/}, used as delimiter
5529 @cindex @code{\,}, used as delimiter
5530 @cindex @code{\&}, used as delimiter
5532 @cindex @code{\:}, used as delimiter
5535 @cindex @code{\@r{<colon>}}, used as delimiter
5537 @cindex @code{\~}, used as delimiter
5538 @cindex @code{\0}, used as delimiter
5539 @cindex @code{\a}, used as delimiter
5540 @cindex @code{\c}, used as delimiter
5541 @cindex @code{\d}, used as delimiter
5542 @cindex @code{\e}, used as delimiter
5543 @cindex @code{\E}, used as delimiter
5544 @cindex @code{\p}, used as delimiter
5545 @cindex @code{\r}, used as delimiter
5546 @cindex @code{\t}, used as delimiter
5547 @cindex @code{\u}, used as delimiter
5548 The following escapes sequences (which are handled similarly to
5549 characters since they don't take a parameter) are also allowed as
5550 delimiters: @code{\%}, @w{@samp{\ }}, @code{\|}, @code{\^}, @code{\@{},
5551 @code{\@}}, @code{\'}, @code{\`}, @code{\-}, @code{\_}, @code{\!},
5552 @code{\?}, @code{\@@}, @code{\)}, @code{\/}, @code{\,}, @code{\&},
5553 @code{\:}, @code{\~}, @code{\0}, @code{\a}, @code{\c}, @code{\d},
5554 @code{\e}, @code{\E}, @code{\p}, @code{\r}, @code{\t}, and @code{\u}.
5555 Again, don't use these if possible.
5557 @cindex @code{\A}, allowed delimiters
5558 @cindex @code{\B}, allowed delimiters
5559 @cindex @code{\Z}, allowed delimiters
5560 @cindex @code{\C}, allowed delimiters
5561 @cindex @code{\w}, allowed delimiters
5562 No newline characters as delimiters are allowed in the following
5563 escapes: @code{\A}, @code{\B}, @code{\Z}, @code{\C}, and @code{\w}.
5565 @cindex @code{\D}, allowed delimiters
5566 @cindex @code{\h}, allowed delimiters
5567 @cindex @code{\H}, allowed delimiters
5568 @cindex @code{\l}, allowed delimiters
5569 @cindex @code{\L}, allowed delimiters
5570 @cindex @code{\N}, allowed delimiters
5571 @cindex @code{\R}, allowed delimiters
5572 @cindex @code{\s}, allowed delimiters
5573 @cindex @code{\S}, allowed delimiters
5574 @cindex @code{\v}, allowed delimiters
5575 @cindex @code{\x}, allowed delimiters
5576 Finally, the escapes @code{\D}, @code{\h}, @code{\H}, @code{\l},
5577 @code{\L}, @code{\N}, @code{\R}, @code{\s}, @code{\S}, @code{\v},
5578 and @code{\x} can't use the following characters as delimiters:
5582 @cindex numbers, and delimiters
5583 @cindex digits, and delimiters
5584 The digits @code{0}-@code{9}.
5587 @cindex operators, as delimiters
5588 @cindex @code{+}, as delimiter
5589 @cindex @code{-}, as delimiter
5590 @cindex @code{/}, as delimiter
5591 @cindex @code{*}, as delimiter
5592 @cindex @code{%}, as delimiter
5593 @cindex @code{<}, as delimiter
5594 @cindex @code{>}, as delimiter
5595 @cindex @code{=}, as delimiter
5596 @cindex @code{&}, as delimiter
5598 @cindex @code{:}, as delimiter
5601 @cindex <colon>, as delimiter
5603 @cindex @code{(}, as delimiter
5604 @cindex @code{)}, as delimiter
5605 @cindex @code{.}, as delimiter
5606 The (single-character) operators @samp{+-/*%<>=&:().}.
5609 @cindex space character
5610 @cindex character, space
5611 @cindex tab character
5612 @cindex character, tab
5613 @cindex newline character
5614 @cindex character, newline
5615 The space, tab, and newline characters.
5618 @cindex @code{\%}, used as delimiter
5620 @cindex @code{\:}, used as delimiter
5623 @cindex @code{\@r{<colon>}}, used as delimiter
5625 @cindex @code{\@{}, used as delimiter
5626 @cindex @code{\@}}, used as delimiter
5627 @cindex @code{\'}, used as delimiter
5628 @cindex @code{\`}, used as delimiter
5629 @cindex @code{\-}, used as delimiter
5630 @cindex @code{\_}, used as delimiter
5631 @cindex @code{\!}, used as delimiter
5632 @cindex @code{\@@}, used as delimiter
5633 @cindex @code{\/}, used as delimiter
5634 @cindex @code{\c}, used as delimiter
5635 @cindex @code{\e}, used as delimiter
5636 @cindex @code{\p}, used as delimiter
5637 All escape sequences except @code{\%}, @code{\:}, @code{\@{}, @code{\@}},
5638 @code{\'}, @code{\`}, @code{\-}, @code{\_}, @code{\!}, @code{\@@},
5639 @code{\/}, @code{\c}, @code{\e}, and @code{\p}.
5642 @cindex printing backslash (@code{\\}, @code{\e}, @code{\E}, @code{\[rs]})
5643 @cindex backslash, printing (@code{\\}, @code{\e}, @code{\E}, @code{\[rs]})
5644 To have a backslash (actually, the current escape character) appear in the
5645 output several escapes are defined: @code{\\}, @code{\e} or @code{\E}.
5646 These are very similar, and only differ with respect to being used in
5647 macros or diversions. @xref{Character Translations}, for an exact
5648 description of those escapes.
5650 @xref{Implementation Differences}, @ref{Copy-in Mode}, and @ref{Diversions},
5651 @ref{Identifiers}, for more information.
5657 @node Comments, , Escapes, Escapes
5658 @subsubsection Comments
5661 Probably one of the most@footnote{Unfortunately, this is a lie. But
5662 hopefully future @code{gtroff} hackers will believe it @code{:-)}}
5663 common forms of escapes is the comment.
5666 Start a comment. Everything to the end of the input line is ignored.
5668 This may sound simple, but it can be tricky to keep the comments from
5669 interfering with the appearance of the final output.
5671 @cindex @code{ds}, @code{ds1} requests, and comments
5672 @cindex @code{as}, @code{as1} requests, and comments
5673 If the escape is to the right of some text or a request, that portion
5674 of the line is ignored, but the space leading up to it is noticed by
5675 @code{gtroff}. This only affects the @code{ds} and @code{as}
5676 request and its variants.
5678 @cindex tabs, before comments
5679 @cindex comments, lining up with tabs
5680 One possibly irritating idiosyncracy is that tabs must not be used to
5681 line up comments. Tabs are not treated as whitespace between the
5682 request and macro arguments.
5684 @cindex undefined request
5685 @cindex request, undefined
5686 A comment on a line by itself is treated as a blank line, because
5687 after eliminating the comment, that is all that remains:
5704 To avoid this, it is common to start the line with @code{.\"} which
5705 causes the line to be treated as an undefined request and thus ignored
5708 @cindex @code{'}, as a comment
5709 Another commenting scheme seen sometimes is three consecutive single
5710 quotes (@code{'''}) at the beginning of a line. This works, but
5711 @code{gtroff} gives a warning about an undefined macro (namely
5712 @code{''}), which is harmless, but irritating.
5716 To avoid all this, @code{gtroff} has a new comment mechanism using the
5717 @code{\#} escape. This escape works the same as @code{\"} except that
5718 the newline is also ignored:
5737 @Defreq {ig, [@Var{end}]}
5738 Ignore all input until @code{gtroff} encounters the macro named
5739 @code{.}@var{end} on a line by itself (or @code{..} if @var{end} is not
5740 specified). This is useful for commenting out large blocks of text:
5745 This is part of a large block
5746 of text that has been
5747 temporarily(?) commented out.
5749 We can restore it simply by removing
5750 the .ig request and the ".." at the
5753 More text text text...
5760 text text text@dots{} More text text text@dots{}
5764 Note that the commented-out block of text does not
5767 The input is read in copy-mode; auto-incremented registers @emph{are}
5768 affected (@pxref{Auto-increment}).
5772 @c =====================================================================
5774 @node Registers, Manipulating Filling and Adjusting, Embedded Commands, gtroff Reference
5778 Numeric variables in @code{gtroff} are called @dfn{registers}. There
5779 are a number of built-in registers, supplying anything from the date to
5780 details of formatting parameters.
5782 @xref{Identifiers}, for details on register identifiers.
5785 * Setting Registers::
5786 * Interpolating Registers::
5788 * Assigning Formats::
5789 * Built-in Registers::
5792 @c ---------------------------------------------------------------------
5794 @node Setting Registers, Interpolating Registers, Registers, Registers
5795 @subsection Setting Registers
5796 @cindex setting registers (@code{nr}, @code{\R})
5797 @cindex registers, setting (@code{nr}, @code{\R})
5799 Define or set registers using the @code{nr} request or the
5802 @DefreqList {nr, ident value}
5803 @DefescListEnd {\\R, ', ident value, '}
5804 Set number register @var{ident} to @var{value}. If @var{ident}
5805 doesn't exist, @code{gtroff} creates it.
5807 The argument to @code{\R} usually has to be enclosed in quotes.
5808 @xref{Escapes}, for details on parameter delimiting characters.
5810 The @code{\R} escape doesn't produce an input token in @code{gtroff};
5811 with other words, it vanishes completely after @code{gtroff} has
5815 For example, the following two lines are equivalent:
5818 .nr a (((17 + (3 * 4))) % 4)
5819 \R'a (((17 + (3 * 4))) % 4)'
5823 Both @code{nr} and @code{\R} have two additional special forms to
5824 increment or decrement a register.
5826 @DefreqList {nr, ident @t{+}@Var{value}}
5827 @DefreqItem {nr, ident @t{-}@Var{value}}
5828 @DefescItem {\\R, ', ident @t{+}value, '}
5829 @DefescListEnd {\\R, ', ident @t{-}value, '}
5830 Increment (decrement) register @var{ident} by @var{value}.
5839 @cindex negating register values
5840 To assign the negated value of a register to another register, some care
5841 must be taken to get the desired result:
5855 The surrounding parentheses prevent the interpretation of the minus sign
5856 as a decrementing operator. An alternative is to start the assignment
5872 @cindex removing number register (@code{rr})
5873 @cindex number register, removing (@code{rr})
5874 @cindex register, removing (@code{rr})
5875 Remove number register @var{ident}. If @var{ident} doesn't exist, the
5879 @Defreq {rnn, ident1 ident2}
5880 @cindex renaming number register (@code{rnn})
5881 @cindex number register, renaming (@code{rnn})
5882 @cindex register, renaming (@code{rnn})
5883 Rename number register @var{ident1} to @var{ident2}. If either
5884 @var{ident1} or @var{ident2} doesn't exist, the request is ignored.
5887 @Defreq {aln, ident1 ident2}
5888 @cindex alias, number register, creating (@code{aln})
5889 @cindex creating alias, for number register (@code{aln})
5890 @cindex number register, creating alias (@code{aln})
5891 @cindex register, creating alias (@code{aln})
5892 Create an alias @var{ident1} for a number register @var{ident2}. The
5893 new name and the old name are exactly equivalent. If @var{ident1} is
5894 undefined, a warning of type @samp{reg} is generated, and the request
5895 is ignored. @xref{Debugging}, for information about warnings.
5898 @c ---------------------------------------------------------------------
5900 @node Interpolating Registers, Auto-increment, Setting Registers, Registers
5901 @subsection Interpolating Registers
5902 @cindex interpolating registers (@code{\n})
5903 @cindex registers, interpolating (@code{\n})
5905 Numeric registers can be accessed via the @code{\n} escape.
5907 @DefescList {\\n, , i, }
5908 @DefescItem {\\n, @Lparen{}, id, }
5909 @DefescListEnd {\\n, @Lbrack{}, ident, @Rbrack{}}
5910 @cindex nested assignments
5911 @cindex assignments, nested
5912 @cindex indirect assignments
5913 @cindex assignments, indirect
5914 Interpolate number register with name @var{ident} (one-character
5915 name@tie{}@var{i}, two-character name @var{id}). This means that the value
5916 of the register is expanded in-place while @code{gtroff} is parsing the
5917 input line. Nested assignments (also called indirect assignments) are
5939 @c ---------------------------------------------------------------------
5941 @node Auto-increment, Assigning Formats, Interpolating Registers, Registers
5942 @subsection Auto-increment
5943 @cindex auto-increment
5944 @cindex increment, automatic
5946 Number registers can also be auto-incremented and auto-decremented.
5947 The increment or decrement value can be specified with a third
5948 argument to the @code{nr} request or @code{\R} escape.
5950 @Defreq {nr, ident value incr}
5951 @cindex @code{\R}, difference to @code{nr}
5952 Set number register @var{ident} to @var{value}; the increment for
5953 auto-incrementing is set to @var{incr}. Note that the @code{\R}
5954 escape doesn't support this notation.
5957 To activate auto-incrementing, the escape @code{\n} has a special
5960 @DefescList {\\n, +, i, }
5961 @DefescItem {\\n, -, i, }
5962 @DefescItem {\\n, @Lparen{}+, id, }
5963 @DefescItem {\\n, @Lparen{}-, id, }
5964 @DefescItem {\\n, +@Lparen{}, id, }
5965 @DefescItem {\\n, -@Lparen{}, id, }
5966 @DefescItem {\\n, @Lbrack{}+, ident, @Rbrack{}}
5967 @DefescItem {\\n, @Lbrack{}-, ident, @Rbrack{}}
5968 @DefescItem {\\n, +@Lbrack{}, ident, @Rbrack{}}
5969 @DefescListEnd {\\n, -@Lbrack{}, ident, @Rbrack{}}
5970 Before interpolating, increment or decrement @var{ident}
5971 (one-character name@tie{}@var{i}, two-character name @var{id}) by the
5972 auto-increment value as specified with the @code{nr} request (or the
5973 @code{\R} escape). If no auto-increment value has been specified,
5974 these syntax forms are identical to @code{\n}.
5983 \n+a, \n+a, \n+a, \n+a, \n+a
5985 \n-(xx, \n-(xx, \n-(xx, \n-(xx, \n-(xx
5987 \n+[foo], \n+[foo], \n+[foo], \n+[foo], \n+[foo]
5995 -5, -10, -15, -20, -25
5999 @cindex increment value without changing the register
6000 @cindex value, incrementing without changing the register
6001 To change the increment value without changing the value of a register
6002 (@var{a} in the example), the following can be used:
6008 @c ---------------------------------------------------------------------
6010 @node Assigning Formats, Built-in Registers, Auto-increment, Registers
6011 @subsection Assigning Formats
6012 @cindex assigning formats (@code{af})
6013 @cindex formats, assigning (@code{af})
6015 When a register is used in the text of an input file (as opposed to
6016 part of an expression), it is textually replaced (or interpolated)
6017 with a representation of that number. This output format can be
6018 changed to a variety of formats (numbers, Roman numerals, etc.). This
6019 is done using the @code{af} request.
6021 @Defreq {af, ident format}
6022 Change the output format of a number register. The first argument
6023 @var{ident} is the name of the number register to be changed, and the
6024 second argument @var{format} is the output format. The following
6025 output formats are available:
6029 Decimal arabic numbers. This is the default format: 0, 1, 2,
6033 Decimal numbers with as many digits as specified. So, @samp{00} would
6034 result in printing numbers as 01, 02, 03,@tie{}@enddots{}
6036 In fact, any digit instead of zero will do; @code{gtroff} only counts
6037 how many digits are specified. As a consequence, @code{af}'s default
6038 format @samp{1} could be specified as @samp{0} also (and exactly this is
6039 returned by the @code{\g} escape, see below).
6042 @cindex Roman numerals
6043 @cindex numerals, Roman
6044 Upper-case Roman numerals: 0, I, II, III, IV,@tie{}@enddots{}
6047 Lower-case Roman numerals: 0, i, ii, iii, iv,@tie{}@enddots{}
6050 Upper-case letters: 0, A, B, C, @dots{},@tie{}Z, AA, AB,@tie{}@enddots{}
6053 Lower-case letters: 0, a, b, c, @dots{},@tie{}z, aa, ab,@tie{}@enddots{}
6056 Omitting the number register format causes a warning of type
6057 @samp{missing}. @xref{Debugging}, for more details. Specifying a
6058 nonexistent format causes an error.
6060 The following example produces @samp{10, X, j, 010}:
6064 .af a 1 \" the default format
6074 @cindex Roman numerals, maximum and minimum
6075 @cindex maximum values of Roman numerals
6076 @cindex minimum values of Roman numerals
6077 The largest number representable for the @samp{i} and @samp{I} formats
6078 is 39999 (or @minus{}39999); @acronym{UNIX} @code{troff} uses @samp{z}
6079 and @samp{w} to represent 10000 and 5000 in Roman numerals, and so does
6080 @code{gtroff}. Currently, the correct glyphs of Roman numeral five
6081 thousand and Roman numeral ten thousand (Unicode code points
6082 @code{U+2182} and @code{U+2181}, respectively) are not available.
6084 If @var{ident} doesn't exist, it is created.
6086 @cindex read-only register, changing format
6087 @cindex changing format, and read-only registers
6088 Changing the output format of a read-only register causes an error. It
6089 is necessary to first copy the register's value to a writeable register,
6090 then apply the @code{af} request to this other register.
6093 @DefescList {\\g, , i, }
6094 @DefescItem {\\g, @Lparen{}, id, }
6095 @DefescListEnd {\\g, @Lbrack{}, ident, @Rbrack{}}
6096 @cindex format of register (@code{\g})
6097 @cindex register, format (@code{\g})
6098 Return the current format of the specified register @var{ident}
6099 (one-character name@tie{}@var{i}, two-character name @var{id}). For
6100 example, @samp{\ga} after the previous example would produce the
6101 string @samp{000}. If the register hasn't been defined yet, nothing
6105 @c ---------------------------------------------------------------------
6107 @node Built-in Registers, , Assigning Formats, Registers
6108 @subsection Built-in Registers
6109 @cindex built-in registers
6110 @cindex registers, built-in
6112 The following lists some built-in registers which are not described
6113 elsewhere in this manual. Any register which begins with a @samp{.} is
6114 read-only. A complete listing of all built-in registers can be found in
6115 @ref{Register Index}.
6119 @cindex current input file name register (@code{.F})
6120 @cindex input file name, current, register (@code{.F})
6122 This string-valued register returns the current input file name.
6125 @cindex horizontal resolution register (@code{.H})
6126 @cindex resolution, horizontal, register (@code{.H})
6128 Horizontal resolution in basic units.
6134 @cindex mode, unsafe
6135 If @code{gtroff} is called with the @option{-U} command line option, the
6136 number register @code{.U} is set to@tie{}1, and zero otherwise.
6137 @xref{Groff Options}.
6140 @cindex vertical resolution register (@code{.V})
6141 @cindex resolution, vertical, register (@code{.V})
6143 Vertical resolution in basic units.
6146 @cindex seconds, current time (@code{seconds})
6147 @cindex time, current, seconds (@code{seconds})
6148 @cindex current time, seconds (@code{seconds})
6150 The number of seconds after the minute, normally in the range@tie{}0
6151 to@tie{}59, but can be up to@tie{}61 to allow for leap seconds. Initialized
6152 at start-up of @code{gtroff}.
6155 @cindex minutes, current time (@code{minutes})
6156 @cindex time, current, minutes (@code{minutes})
6157 @cindex current time, minutes (@code{minutes})
6159 The number of minutes after the hour, in the range@tie{}0 to@tie{}59.
6160 Initialized at start-up of @code{gtroff}.
6163 @cindex hours, current time (@code{hours})
6164 @cindex time, current, hours (@code{hours})
6165 @cindex current time, hours (@code{hours})
6167 The number of hours past midnight, in the range@tie{}0 to@tie{}23.
6168 Initialized at start-up of @code{gtroff}.
6171 @cindex day of the week register (@code{dw})
6172 @cindex date, day of the week register (@code{dw})
6174 Day of the week (1-7).
6177 @cindex day of the month register (@code{dy})
6178 @cindex date, day of the month register (@code{dy})
6180 Day of the month (1-31).
6183 @cindex month of the year register (@code{mo})
6184 @cindex date, month of the year register (@code{mo})
6186 Current month (1-12).
6189 @cindex date, year register (@code{year}, @code{yr})
6190 @cindex year, current, register (@code{year}, @code{yr})
6196 The current year minus@tie{}1900. Unfortunately, the documentation of
6197 @acronym{UNIX} Version@tie{}7's @code{troff} had a year@tie{}2000 bug: It
6198 incorrectly claimed that @code{yr} contains the last two digits of the
6199 year. That claim has never been true of either @acronym{AT&T}
6200 @code{troff} or GNU @code{troff}. Old @code{troff} input that looks
6204 '\" The following line stopped working after 1999
6205 This document was formatted in 19\n(yr.
6209 can be corrected as follows:
6212 This document was formatted in \n[year].
6216 or, to be portable to older @code{troff} versions, as follows:
6220 This document was formatted in \n(y4.
6227 @cindex input line number register (@code{.c}, @code{c.})
6228 @cindex line number, input, register (@code{.c}, @code{c.})
6229 The current @emph{input} line number. Register @samp{.c} is read-only,
6230 whereas @samp{c.} (a @code{gtroff} extension) is writable also,
6231 affecting both @samp{.c} and @samp{c.}.
6235 @cindex output line number register (@code{ln})
6236 @cindex line number, output, register (@code{ln})
6237 The current @emph{output} line number after a call to the @code{nm}
6238 request to activate line numbering.
6240 @xref{Miscellaneous}, for more information about line numbering.
6244 @cindex major version number register (@code{.x})
6245 @cindex version number, major, register (@code{.x})
6246 The major version number. For example, if the version number
6247 is 1.03 then @code{.x} contains@tie{}@samp{1}.
6251 @cindex minor version number register (@code{.y})
6252 @cindex version number, minor, register (@code{.y})
6253 The minor version number. For example, if the version number
6254 is 1.03 then @code{.y} contains@tie{}@samp{03}.
6258 @cindex revision number register (@code{.Y})
6259 The revision number of @code{groff}.
6263 @cindex process ID of @code{gtroff} register (@code{$$})
6264 @cindex @code{gtroff}, process ID register (@code{$$})
6265 The process ID of @code{gtroff}.
6269 @cindex @code{gtroff}, identification register (@code{.g})
6270 @cindex GNU-specific register (@code{.g})
6271 Always@tie{}1. Macros should use this to determine whether they are
6272 running under GNU @code{troff}.
6276 @cindex @acronym{ASCII} approximation output register (@code{.A})
6277 If the command line option @option{-a} is used to produce an
6278 @acronym{ASCII} approximation of the output, this is set to@tie{}1, zero
6279 otherwise. @xref{Groff Options}.
6283 This register is set to@tie{}1 (and to@tie{}0 otherwise) if the current
6284 page is actually being printed, i.e., if the @option{-o} option is being
6285 used to only print selected pages. @xref{Groff Options}, for more
6290 If @code{gtroff} is called with the @option{-T} command line option, the
6291 number register @code{.T} is set to@tie{}1, and zero otherwise.
6292 @xref{Groff Options}.
6296 @cindex output device name string register (@code{.T})
6297 A single read-write string register which contains the current output
6298 device (for example, @samp{latin1} or @samp{ps}). This is the only
6299 string register defined by @code{gtroff}.
6303 @c =====================================================================
6305 @node Manipulating Filling and Adjusting, Manipulating Hyphenation, Registers, gtroff Reference
6306 @section Manipulating Filling and Adjusting
6307 @cindex manipulating filling and adjusting
6308 @cindex filling and adjusting, manipulating
6309 @cindex adjusting and filling, manipulating
6310 @cindex justifying text
6311 @cindex text, justifying
6315 @cindex @code{bp} request, causing implicit linebreak
6316 @cindex @code{ce} request, causing implicit linebreak
6317 @cindex @code{cf} request, causing implicit linebreak
6318 @cindex @code{fi} request, causing implicit linebreak
6319 @cindex @code{fl} request, causing implicit linebreak
6320 @cindex @code{in} request, causing implicit linebreak
6321 @cindex @code{nf} request, causing implicit linebreak
6322 @cindex @code{rj} request, causing implicit linebreak
6323 @cindex @code{sp} request, causing implicit linebreak
6324 @cindex @code{ti} request, causing implicit linebreak
6325 @cindex @code{trf} request, causing implicit linebreak
6326 Various ways of causing @dfn{breaks} were given in @ref{Implicit Line
6327 Breaks}. The @code{br} request likewise causes a break. Several
6328 other requests also cause breaks, but implicitly. These are
6329 @code{bp}, @code{ce}, @code{cf}, @code{fi}, @code{fl}, @code{in},
6330 @code{nf}, @code{rj}, @code{sp}, @code{ti}, and @code{trf}.
6333 Break the current line, i.e., the input collected so far is emitted
6336 If the no-break control character is used, @code{gtroff} suppresses
6347 Initially, @code{gtroff} fills and adjusts text to both margins.
6348 Filling can be disabled via the @code{nf} request and re-enabled with
6349 the @code{fi} request.
6353 @cindex fill mode (@code{fi})
6354 @cindex mode, fill (@code{fi})
6355 Activate fill mode (which is the default). This request implicitly
6356 enables adjusting; it also inserts a break in the text currently being
6357 filled. The read-only number register @code{.u} is set to@tie{}1.
6359 The fill mode status is associated with the current environment
6360 (@pxref{Environments}).
6362 See @ref{Line Control}, for interaction with the @code{\c} escape.
6366 @cindex no-fill mode (@code{nf})
6367 @cindex mode, no-fill (@code{nf})
6368 Activate no-fill mode. Input lines are output as-is, retaining line
6369 breaks and ignoring the current line length. This command implicitly
6370 disables adjusting; it also causes a break. The number register
6371 @code{.u} is set to@tie{}0.
6373 The fill mode status is associated with the current environment
6374 (@pxref{Environments}).
6376 See @ref{Line Control}, for interaction with the @code{\c} escape.
6379 @DefreqList {ad, [@Var{mode}]}
6383 Activation and deactivation of adjusting is done implicitly with
6384 calls to the @code{fi} or @code{nf} requests.
6386 @var{mode} can have one of the following values:
6390 @cindex ragged-right
6391 Adjust text to the left margin. This produces what is traditionally
6392 called ragged-right text.
6396 Adjust text to the right margin, producing ragged-left text.
6399 @cindex centered text
6400 @cindex @code{ce} request, difference to @samp{.ad@tie{}c}
6401 Center filled text. This is different to the @code{ce} request which
6402 only centers text without filling.
6406 Justify to both margins. This is the default used by @code{gtroff}.
6409 Finally, @var{mode} can be the numeric argument returned by the @code{.j}
6412 With no argument, @code{gtroff} adjusts lines in the same way it did
6413 before adjusting was deactivated (with a call to @code{na}, for
6425 .ad \" back to centering
6427 .ad \n[ad] \" back to right justifying
6430 @cindex adjustment mode register (@code{.j})
6431 The current adjustment mode is available in the read-only number
6432 register @code{.j}; it can be stored and subsequently used to set
6435 The adjustment mode status is associated with the current environment
6436 (@pxref{Environments}).
6440 Disable adjusting. This request won't change the current adjustment
6441 mode: A subsequent call to @code{ad} uses the previous adjustment
6444 The adjustment mode status is associated with the current environment
6445 (@pxref{Environments}).
6449 @DefescListEnd {\\p, , , }
6450 Adjust the current line and cause a break.
6452 In most cases this produces very ugly results since @code{gtroff}
6453 doesn't have a sophisticated paragraph building algorithm (as @TeX{}
6454 have, for example); instead, @code{gtroff} fills and adjusts a paragraph
6458 This is an uninteresting sentence.
6459 This is an uninteresting sentence.\p
6460 This is an uninteresting sentence.
6467 This is an uninteresting sentence. This is an
6468 uninteresting sentence.
6469 This is an uninteresting sentence.
6473 @DefreqList {ss, word_space_size [@Var{sentence_space_size}]}
6475 @DefregListEnd {.sss}
6476 @cindex word space size register (@code{.ss})
6477 @cindex size of word space register (@code{.ss})
6478 @cindex space between words register (@code{.ss})
6479 @cindex sentence space size register (@code{.sss})
6480 @cindex size of sentence space register (@code{.sss})
6481 @cindex space between sentences register (@code{.sss})
6482 Change the size of a space between words. It takes its units as one
6483 twelfth of the space width parameter for the current font.
6484 Initially both the @var{word_space_size} and @var{sentence_space_size}
6485 are@tie{}12. In fill mode, the values specify the minimum distance.
6489 If two arguments are given to the @code{ss} request, the second
6490 argument sets the sentence space size. If the second argument is not
6491 given, sentence space size is set to @var{word_space_size}. The
6492 sentence space size is used in two circumstances: If the end of a
6493 sentence occurs at the end of a line in fill mode, then both an
6494 inter-word space and a sentence space are added; if two spaces follow
6495 the end of a sentence in the middle of a line, then the second space
6496 is a sentence space. If a second argument is never given to the
6497 @code{ss} request, the behaviour of @acronym{UNIX} @code{troff} is the
6498 same as that exhibited by GNU @code{troff}. In GNU @code{troff}, as
6499 in @acronym{UNIX} @code{troff}, a sentence should always be followed
6500 by either a newline or two spaces.
6502 The read-only number registers @code{.ss} and @code{.sss} hold the
6503 values of the parameters set by the first and second arguments of the
6506 The word space and sentence space values are associated with the current
6507 environment (@pxref{Environments}).
6509 Contrary to @acronym{AT&T} @code{troff}, this request is @emph{not}
6510 ignored if a TTY output device is used; the given values are then
6511 rounded down to a multiple of@tie{}12 (@pxref{Implementation Differences}).
6513 The request is ignored if there is no parameter.
6515 @cindex discardable horizontal space
6516 @cindex space, discardable, horizontal
6517 @cindex horizontal discardable space
6518 Another useful application of the @code{ss} request is to insert
6519 discardable horizontal space, i.e., space which is discarded at a line
6520 break. For example, paragraph-style footnotes could be separated this
6525 1.\ This is the first footnote.\c
6529 2.\ This is the second footnote.
6536 1. This is the first footnote. 2. This
6537 is the second footnote.
6541 Note that the @code{\h} escape produces unbreakable space.
6544 @DefreqList {ce, [@Var{nnn}]}
6545 @DefregListEnd {.ce}
6546 @cindex centering lines (@code{ce})
6547 @cindex lines, centering (@code{ce})
6548 Center text. While the @w{@samp{.ad c}} request also centers text,
6549 it fills the text as well. @code{ce} does not fill the
6550 text it affects. This request causes a break. The number of lines
6551 still to be centered is associated with the current environment
6552 (@pxref{Environments}).
6554 The following example demonstrates the differences.
6560 This is a small text fragment which shows the differences
6561 between the `.ce' and the `.ad c' request.
6565 This is a small text fragment which shows the differences
6566 between the `.ce' and the `.ad c' request.
6570 And here the result:
6573 This is a small text fragment which
6574 shows the differences
6575 between the `.ce' and the `.ad c' request.
6577 This is a small text fragment which
6578 shows the differences between the `.ce'
6579 and the `.ad c' request.
6582 With no arguments, @code{ce} centers the next line of text. @var{nnn}
6583 specifies the number of lines to be centered. If the argument is zero
6584 or negative, centering is disabled.
6586 The basic length for centering text is the line length (as set with the
6587 @code{ll} request) minus the indentation (as set with the @code{in}
6588 request). Temporary indentation is ignored.
6590 As can be seen in the previous example, it is a common idiom to turn
6591 on centering for a large number of lines, and to turn off centering
6592 after text to be centered. This is useful for any request which takes
6593 a number of lines as an argument.
6595 The @code{.ce} read-only number register contains the number of lines
6596 remaining to be centered, as set by the @code{ce} request.
6599 @DefreqList {rj, [@Var{nnn}]}
6600 @DefregListEnd {.rj}
6601 @cindex justifying text (@code{rj})
6602 @cindex text, justifying (@code{rj})
6603 @cindex right-justifying (@code{rj})
6604 Justify unfilled text to the right margin. Arguments are identical to
6605 the @code{ce} request. The @code{.rj} read-only number register is
6606 the number of lines to be right-justified as set by the @code{rj}
6607 request. This request causes a break. The number of lines still to be
6608 right-justified is associated with the current environment
6609 (@pxref{Environments}).
6613 @c =====================================================================
6615 @node Manipulating Hyphenation, Manipulating Spacing, Manipulating Filling and Adjusting, gtroff Reference
6616 @section Manipulating Hyphenation
6617 @cindex manipulating hyphenation
6618 @cindex hyphenation, manipulating
6621 Here a description of requests which influence hyphenation.
6623 @DefreqList {hy, [@Var{mode}]}
6624 @DefregListEnd {.hy}
6625 Enable hyphenation. The request has an optional numeric argument,
6626 @var{mode}, to restrict hyphenation if necessary:
6630 The default argument if @var{mode} is omitted. Hyphenate without
6631 restrictions. This is also the start-up value of @code{gtroff}.
6634 Do not hyphenate the last word on a page or column.
6637 Do not hyphenate the last two characters of a word.
6640 Do not hyphenate the first two characters of a word.
6643 Values in the previous table are additive. For example, the
6644 value@tie{}12 causes @code{gtroff} to neither hyphenate the last
6645 two nor the first two characters of a word.
6647 @cindex hyphenation restrictions register (@code{.hy})
6648 The current hyphenation restrictions can be found in the read-only
6649 number register @samp{.hy}.
6651 The hyphenation mode is associated with the current environment
6652 (@pxref{Environments}).
6656 Disable hyphenation (i.e., set the hyphenation mode to zero). Note
6657 that the hyphenation mode of the last call to @code{hy} is not
6660 The hyphenation mode is associated with the current environment
6661 (@pxref{Environments}).
6664 @DefreqList {hlm, [@Var{nnn}]}
6666 @DefregListEnd {.hlc}
6667 @cindex explicit hyphen (@code{\%})
6668 @cindex hyphen, explicit (@code{\%})
6669 @cindex consecutive hyphenated lines (@code{hlm})
6670 @cindex lines, consecutive hyphenated (@code{hlm})
6671 @cindex hyphenated lines, consecutive (@code{hlm})
6672 Set the maximum number of consecutive hyphenated lines to @var{nnn}.
6673 If this number is negative, there is no maximum. The default value
6674 is@tie{}@minus{}1 if @var{nnn} is omitted. This value is associated
6675 with the current environment (@pxref{Environments}). Only lines
6676 output from a given environment count towards the maximum associated
6677 with that environment. Hyphens resulting from @code{\%} are counted;
6678 explicit hyphens are not.
6680 The current setting of @code{hlm} is available in the @code{.hlm}
6681 read-only number register. Also the number of immediately preceding
6682 consecutive hyphenated lines are available in the read-only number
6683 register @samp{.hlc}.
6686 @Defreq {hw, word1 word2 @dots{}}
6687 Define how @var{word1}, @var{word2}, etc.@: are to be hyphenated. The
6688 words must be given with hyphens at the hyphenation points. For
6696 Besides the space character, any character whose hyphenation code value
6697 is zero can be used to separate the arguments of @code{hw} (see the
6698 documentation for the @code{hcode} request below for more information).
6699 In addition, this request can be used more than once.
6701 Hyphenation exceptions specified with the @code{hw} request are
6702 associated with the current hyphenation language; it causes an error
6703 if there is no current hyphenation language.
6705 This request is ignored if there is no parameter.
6707 In old versions of @code{troff} there was a limited amount of space to
6708 store such information; fortunately, with @code{gtroff}, this is no
6709 longer a restriction.
6712 @DefescList {\\%, , , }
6713 @deffnx Escape @t{\:}
6718 @esindex \@r{<colon>}
6720 @cindex hyphenation character (@code{\%})
6721 @cindex character, hyphenation (@code{\%})
6722 @cindex disabling hyphenation (@code{\%})
6723 @cindex hyphenation, disabling (@code{\%})
6724 To tell @code{gtroff} how to hyphenate words on the fly, use the
6725 @code{\%} escape, also known as the @dfn{hyphenation character}.
6726 Preceding a word with this character prevents it from being
6727 hyphenated; putting it inside a word indicates to @code{gtroff} that
6728 the word may be hyphenated at that point. Note that this mechanism
6729 only affects that one occurrence of the word; to change the
6730 hyphenation of a word for the entire document, use the @code{hw}
6733 The @code{\:} escape inserts a zero-width break point
6734 (that is, the word breaks but without adding a hyphen).
6737 ... check the /var/log/\:httpd/\:access_log file ...
6740 @cindex @code{\X}, followed by @code{\%}
6741 @cindex @code{\Y}, followed by @code{\%}
6742 @cindex @code{\%}, following @code{\X} or @code{\Y}
6743 Note that @code{\X} and @code{\Y} start a word, that is, the @code{\%}
6744 escape in (say) @w{@samp{\X'...'\%foobar}} and
6745 @w{@samp{\Y'...'\%foobar}} no longer prevents hyphenation but inserts
6746 a hyphenation point at the beginning of @samp{foobar}; most likely
6747 this isn't what you want to do.
6750 @Defreq {hc, [@Var{char}]}
6751 Change the hyphenation character to @var{char}. This character then
6752 works the same as the @code{\%} escape, and thus, no longer appears in
6753 the output. Without an argument, @code{hc} resets the hyphenation
6754 character to be @code{\%} (the default) only.
6756 The hyphenation character is associated with the current environment
6757 (@pxref{Environments}).
6760 @DefreqList {hpf, pattern_file}
6761 @DefreqItem {hpfa, pattern_file}
6762 @DefreqListEnd {hpfcode, a b [c d @dots{}]}
6763 @cindex hyphenation patterns (@code{hpf})
6764 @cindex patterns for hyphenation (@code{hpf})
6765 Read in a file of hyphenation patterns. This file is searched for in
6766 the same way as @file{@var{name}.tmac} (or @file{tmac.@var{name}}) is
6767 searched for if the @option{-m@var{name}} option is specified.
6769 It should have the same format as (simple) @TeX{} patterns files.
6770 More specifically, the following scanning rules are implemented.
6774 A percent sign starts a comment (up to the end of the line)
6775 even if preceded by a backslash.
6778 No support for `digraphs' like @code{\$}.
6781 @code{^^@var{xx}} (@var{x} is 0-9 or a-f) and @code{^^@var{x}} (character
6782 code of @var{x} in the range 0-127) are recognized; other use of @code{^}
6789 @code{hpf} checks for the expression @code{\patterns@{@dots{}@}}
6790 (possibly with whitespace before and after the braces).
6791 Everything between the braces is taken as hyphenation patterns.
6792 Consequently, @code{@{} and @code{@}} are not allowed in patterns.
6795 Similarly, @code{\hyphenation@{@dots{}@}} gives a list of hyphenation
6799 @code{\endinput} is recognized also.
6802 For backwards compatibility, if @code{\patterns} is missing,
6803 the whole file is treated as a list of hyphenation patterns
6804 (only recognizing the @code{%} character as the start of a comment).
6807 If no @code{hpf} request is specified (either in the document or in a
6808 macro package), @code{gtroff} won't hyphenate at all.
6810 The @code{hpfa} request appends a file of patterns to the current list.
6812 The @code{hpfcode} request defines mapping values for character codes in
6813 hyphenation patterns. @code{hpf} or @code{hpfa} then apply the mapping
6814 (after reading the patterns) before replacing or appending them to
6815 the current list of patterns. Its arguments are pairs of character codes
6816 -- integers from 0 to@tie{}255. The request maps character code@tie{}@var{a}
6817 to code@tie{}@var{b}, code@tie{}@var{c} to code@tie{}@var{d}, and so on. You
6818 can use character codes which would be invalid otherwise.
6824 The set of hyphenation patterns is associated with the current language
6825 set by the @code{hla} request. The @code{hpf} request is usually
6826 invoked by the @file{troffrc} or @file{troffrc-end} file; by default,
6827 @file{troffrc} loads hyphenation patterns and exceptions for American
6828 English (in files @file{hyphen.us} and @file{hyphenex.us}).
6830 A second call to @code{hpf} (for the same language) will replace the
6831 hyphenation patterns with the new ones.
6833 Invoking @code{hpf} causes an error if there is no current hyphenation
6837 @Defreq {hcode, c1 code1 [c2 code2 @dots{}]}
6838 @cindex hyphenation code (@code{hcode})
6839 @cindex code, hyphenation (@code{hcode})
6840 Set the hyphenation code of character @var{c1} to @var{code1}, that of
6841 @var{c2} to @var{code2}, etc. A hyphenation code must be a single
6842 input character (not a special character) other than a digit or a
6845 To make hyphenation work, hyphenation codes must be set up. At
6846 start-up, groff only assigns hyphenation codes to the letters
6847 @samp{a}-@samp{z} (mapped to themselves) and to the letters
6848 @samp{A}-@samp{Z} (mapped to @samp{a}-@samp{z}); all other hyphenation
6849 codes are set to zero. Normally, hyphenation patterns contain only
6850 lowercase letters which should be applied regardless of case. With
6851 other words, the words `FOO' and `Foo' should be hyphenated exactly the
6852 same way as the word `foo' is hyphenated, and this is what @code{hcode}
6853 is good for. Words which contain other letters won't be hyphenated
6854 properly if the corresponding hyphenation patterns actually do contain
6855 them. For example, the following @code{hcode} requests are necessary to
6856 assign hyphenation codes to the letters @samp{ÄäÖöÜüß} (this is needed
6866 Without those assignments, groff treats German words like
6867 @w{`Kindergärten'} (the plural form of `kindergarten') as two
6868 substrings @w{`kinderg'} and @w{`rten'} because the hyphenation code
6869 of the umlaut@tie{}a is zero by default. There is a German
6870 hyphenation pattern which covers @w{`kinder'}, so groff finds the
6871 hyphenation `kin-der'. The other two hyphenation points
6872 (`kin-der-gär-ten') are missed.
6874 This request is ignored if it has no parameter.
6877 @DefreqList {hym, [@Var{length}]}
6878 @DefregListEnd {.hym}
6879 @cindex hyphenation margin (@code{hym})
6880 @cindex margin for hyphenation (@code{hym})
6881 @cindex @code{ad} request, and hyphenation margin
6882 Set the (right) hyphenation margin to @var{length}. If the current
6883 adjustment mode is not @samp{b} or @samp{n}, the line is not
6884 hyphenated if it is shorter than @var{length}. Without an argument,
6885 the hyphenation margin is reset to its default value, which is@tie{}0.
6886 The default scaling indicator for this request is @samp{m}. The
6887 hyphenation margin is associated with the current environment
6888 (@pxref{Environments}).
6890 A negative argument resets the hyphenation margin to zero, emitting
6891 a warning of type @samp{range}.
6893 @cindex hyphenation margin register (@code{.hym})
6894 The current hyphenation margin is available in the @code{.hym} read-only
6898 @DefreqList {hys, [@Var{hyphenation_space}]}
6899 @DefregListEnd {.hys}
6900 @cindex hyphenation space (@code{hys})
6901 @cindex @code{ad} request, and hyphenation space
6902 Set the hyphenation space to @var{hyphenation_space}. If the current
6903 adjustment mode is @samp{b} or @samp{n}, don't hyphenate the line
6904 if it can be justified by adding no more than @var{hyphenation_space}
6905 extra space to each word space. Without argument, the hyphenation
6906 space is set to its default value, which is@tie{}0. The default
6907 scaling indicator for this request is @samp{m}. The hyphenation
6908 space is associated with the current environment
6909 (@pxref{Environments}).
6911 A negative argument resets the hyphenation space to zero, emitting a
6912 warning of type @samp{range}.
6914 @cindex hyphenation space register (@code{.hys})
6915 The current hyphenation space is available in the @code{.hys} read-only
6919 @Defreq {shc, [@Var{glyph}]}
6920 @cindex soft hyphen character, setting (@code{shc})
6921 @cindex character, soft hyphen, setting (@code{shc})
6922 @cindex glyph, soft hyphen (@code{hy})
6923 @cindex soft hyphen glyph (@code{hy})
6924 @cindex @code{char} request, and soft hyphen character
6925 @cindex @code{tr} request, and soft hyphen character
6926 Set the @dfn{soft hyphen character} to @var{glyph}.@footnote{@dfn{Soft
6927 hyphen character} is a misnomer since it is an output glyph.} If the
6928 argument is omitted, the soft hyphen character is set to the default
6929 glyph @code{\(hy} (this is the start-up value of @code{gtroff} also).
6930 The soft hyphen character is the glyph that is inserted when a word is
6931 hyphenated at a line break. If the soft hyphen character does not
6932 exist in the font of the character immediately preceding a potential
6933 break point, then the line is not broken at that point. Neither
6934 definitions (specified with the @code{char} request) nor translations
6935 (specified with the @code{tr} request) are considered when finding the
6936 soft hyphen character.
6939 @DefreqList {hla, language}
6940 @DefregListEnd {.hla}
6941 @cindex @code{hpf} request, and hyphenation language
6942 @cindex @code{hw} request, and hyphenation language
6945 Set the current hyphenation language to the string @var{language}.
6946 Hyphenation exceptions specified with the @code{hw} request and
6947 hyphenation patterns specified with the @code{hpf} and @code{hpfa}
6948 requests are both associated with the current hyphenation language.
6949 The @code{hla} request is usually invoked by the @file{troffrc} or the
6950 @file{troffrc-end} files; @file{troffrc} sets the default language to
6953 @cindex hyphenation language register (@code{.hla})
6954 The current hyphenation language is available as a string in the
6955 read-only number register @samp{.hla}.
6958 .ds curr_language \n[.hla]
6965 @c =====================================================================
6967 @node Manipulating Spacing, Tabs and Fields, Manipulating Hyphenation, gtroff Reference
6968 @section Manipulating Spacing
6969 @cindex manipulating spacing
6970 @cindex spacing, manipulating
6972 @Defreq {sp, [@Var{distance}]}
6973 Space downwards @var{distance}. With no argument it advances
6974 1@tie{}line. A negative argument causes @code{gtroff} to move up the page
6975 the specified distance. If the argument is preceded by a @samp{|}
6976 then @code{gtroff} moves that distance from the top of the page. This
6977 request causes a line break. The default scaling indicator is @samp{v}.
6979 If a vertical trap is sprung during execution of @code{sp}, the amount of
6980 vertical space after the trap is discarded. For example, this
7008 @cindex @code{sp} request, and traps
7009 @cindex discarded space in traps
7010 @cindex space, discarded, in traps
7011 @cindex traps, and discarded space
7012 The amount of discarded space is available in the number register
7015 To protect @code{sp} against vertical traps, use the @code{vpt} request:
7024 @DefreqList {ls, [@Var{nnn}]}
7026 @cindex double-spacing (@code{ls})
7027 Output @w{@var{nnn}@minus{}1} blank lines after each line of text.
7028 With no argument, @code{gtroff} uses the previous value before the
7029 last @code{ls} call.
7032 .ls 2 \" This causes double-spaced output
7033 .ls 3 \" This causes triple-spaced output
7034 .ls \" Again double-spaced
7037 The line spacing is associated with the current environment
7038 (@pxref{Environments}).
7040 @cindex line spacing register (@code{.L})
7041 The read-only number register @code{.L} contains the current line
7045 @xref{Changing Type Sizes}, for the requests @code{vs} and @code{pvs}
7046 as alternatives to @code{ls}.
7048 @DefescList {\\x, ', spacing, '}
7050 Sometimes, extra vertical spacing is only needed occasionally, e.g.@:
7051 to allow space for a tall construct (like an equation). The @code{\x}
7052 escape does this. The escape is given a numerical argument, usually
7053 enclosed in quotes (like @samp{\x'3p'}); the default scaling indicator
7054 is @samp{v}. If this number is positive extra vertical space is
7055 inserted below the current line. A negative number adds space above.
7056 If this escape is used multiple times on the same line, the maximum of
7059 @xref{Escapes}, for details on parameter delimiting characters.
7061 @cindex extra post-vertical line space register (@code{.a})
7062 The @code{.a} read-only number register contains the most recent
7063 (nonnegative) extra vertical line space.
7065 Using @code{\x} can be necessary in combination with the @code{\b}
7066 escape, as the following example shows.
7069 This is a test with the \[rs]b escape.
7071 This is a test with the \[rs]b escape.
7073 This is a test with \b'xyz'\x'-1m'\x'1m'.
7075 This is a test with the \[rs]b escape.
7077 This is a test with the \[rs]b escape.
7084 This is a test with the \b escape.
7085 This is a test with the \b escape.
7087 This is a test with y.
7089 This is a test with the \b escape.
7090 This is a test with the \b escape.
7096 @DefregListEnd {.ns}
7097 @cindex @code{sp} request, and no-space mode
7098 @cindex no-space mode (@code{ns})
7099 @cindex mode, no-space (@code{ns})
7100 @cindex blank lines, disabling
7101 @cindex lines, blank, disabling
7102 Enable @dfn{no-space mode}. In this mode, spacing (either via
7103 @code{sp} or via blank lines) is disabled. The @code{bp} request to
7104 advance to the next page is also disabled, except if it is accompanied
7105 by a page number (see @ref{Page Control}, for more information). This
7106 mode ends when actual text is output or the @code{rs} request is
7107 encountered which ends no-space mode. The read-only number register
7108 @code{.ns} is set to@tie{}1 as long as no-space mode is active.
7110 This request is useful for macros that conditionally
7111 insert vertical space before the text starts
7112 (for example, a paragraph macro could insert some space
7113 except when it is the first paragraph after a section header).
7117 @c =====================================================================
7119 @node Tabs and Fields, Character Translations, Manipulating Spacing, gtroff Reference
7120 @section Tabs and Fields
7121 @cindex tabs, and fields
7122 @cindex fields, and tabs
7124 @cindex @acronym{EBCDIC} encoding of a tab
7125 A tab character (@acronym{ASCII} char@tie{}9, @acronym{EBCDIC}
7126 char@tie{}5) causes a horizontal movement to the next tab stop (much
7127 like it did on a typewriter).
7130 @cindex tab character, non-interpreted (@code{\t})
7131 @cindex character, tab, non-interpreted (@code{\t})
7132 This escape is a non-interpreted tab character. In copy mode
7133 (@pxref{Copy-in Mode}), @code{\t} is the same as a real tab character.
7136 @DefreqList {ta, [@Var{n1} @Var{n2} @dots{} @Var{nn} @t{T} @Var{r1} @Var{r2} @dots{} @Var{rn}]}
7137 @DefregListEnd {.tabs}
7138 Change tab stop positions. This request takes a series of tab
7139 specifiers as arguments (optionally divided into two groups with the
7140 letter @samp{T}) which indicate where each tab stop is to be
7141 (overriding any previous settings).
7143 Tab stops can be specified absolutely, i.e., as the distance from the
7144 left margin. For example, the following sets 6@tie{}tab stops every
7148 .ta 1i 2i 3i 4i 5i 6i
7151 Tab stops can also be specified using a leading @samp{+}
7152 which means that the specified tab stop is set relative to
7153 the previous tab stop. For example, the following is equivalent to the
7157 .ta 1i +1i +1i +1i +1i +1i
7160 @code{gtroff} supports an extended syntax to specify repeat values after
7161 the @samp{T} mark (these values are always taken as relative) -- this is
7162 the usual way to specify tabs set at equal intervals. The following is,
7163 yet again, the same as the previous examples. It does even more since
7164 it defines an infinite number of tab stops separated by one inch.
7170 Now we are ready to interpret the full syntax given at the beginning:
7171 Set tabs at positions @var{n1}, @var{n2}, @dots{}, @var{nn} and then set
7172 tabs at @var{nn}+@var{r1}, @var{nn}+@var{r2}, @dots{}, @var{nn}+@var{rn}
7173 and then at @var{nn}+@var{rn}+@var{r1}, @var{nn}+@var{rn}+@var{r2},
7174 @dots{}, @var{nn}+@var{rn}+@var{rn}, and so on.
7176 Example: @samp{4c +6c T 3c 5c 2c} is equivalent to @samp{4c 10c 13c 18c
7177 20c 23c 28c 30c @dots{}}.
7179 The material in each tab column (i.e., the column between two tab stops)
7180 may be justified to the right or left or centered in the column. This
7181 is specified by appending @samp{R}, @samp{L}, or @samp{C} to the tab
7182 specifier. The default justification is @samp{L}. Example:
7192 The default unit of the @code{ta} request is @samp{m}.
7195 A tab stop is converted into a non-breakable horizontal movement which
7196 can be neither stretched nor squeezed. For example,
7205 creates a single line which is a bit longer than 10@tie{}inches (a string
7206 is used to show exactly where the tab characters are). Now consider the
7216 @code{gtroff} first converts the tab stops of the line into unbreakable
7217 horizontal movements, then splits the line after the second @samp{b}
7218 (assuming a sufficiently short line length). Usually, this isn't what
7222 Superfluous tabs (i.e., tab characters which do not correspond to a tab
7223 stop) are ignored except the first one which delimits the characters
7224 belonging to the last tab stop for right-justifying or centering.
7225 Consider the following example
7229 .ds ZZ foo\tbar\tfoobar
7230 .ds ZZZ foo\tbar\tfoo\tbar
7241 which produces the following output:
7250 The first line right-justifies the second `foo' relative to the tab
7251 stop. The second line right-justifies `foobar'. The third line finally
7252 right-justifies only `foo' because of the additional tab character which
7253 marks the end of the string belonging to the last defined tab stop.
7256 Tab stops are associated with the current environment
7257 (@pxref{Environments}).
7260 Calling @code{ta} without an argument removes all tab stops.
7263 @cindex tab stops, for TTY output devices
7264 The start-up value of @code{gtroff} is @w{@samp{T 0.8i}}.
7267 @cindex tab settings register (@code{.tabs})
7268 The read-only number register @code{.tabs} contains a string
7269 representation of the current tab settings suitable for use as an
7270 argument to the @code{ta} request.
7273 .ds tab-string \n[.tabs]
7278 @cindex @code{.S} register, Plan@tie{}9 alias for @code{.tabs}
7279 @cindex @code{.tabs} register, Plan@tie{}9 alias (@code{.S})
7280 The @code{troff} version of the Plan@tie{}9 operating system uses
7281 register @code{.S} for the same purpose.
7284 @Defreq {tc, [@Var{fill-glyph}]}
7285 @cindex tab repetition character (@code{tc})
7286 @cindex character, tab repetition (@code{tc})
7287 @cindex glyph, tab repetition (@code{tc})
7288 Normally @code{gtroff} fills the space to the next tab stop with
7289 whitespace. This can be changed with the @code{tc} request. With no
7290 argument @code{gtroff} reverts to using whitespace, which is the
7291 default. The value of this @dfn{tab repetition character} is
7292 associated with the current environment
7293 (@pxref{Environments}).@footnote{@dfn{Tab repetition character} is a
7294 misnomer since it is an output glyph.}
7297 @DefreqList {linetabs, n}
7298 @DefregListEnd {.linetabs}
7299 @cindex tab, line-tabs mode
7300 @cindex line-tabs mode
7301 @cindex mode, line-tabs
7302 If @var{n} is missing or not zero, enable @dfn{line-tabs} mode,
7303 or disable it otherwise (the default).
7304 In line-tabs mode, @code{gtroff} computes tab distances
7305 relative to the (current) output line instead of the input line.
7307 For example, the following code:
7320 in normal mode, results in the output
7327 in line-tabs mode, the same code outputs
7333 Line-tabs mode is associated with the current environment.
7334 The read-only register @code{.linetabs} is set to@tie{}1 if in line-tabs
7335 mode, and 0 in normal mode.
7343 @c ---------------------------------------------------------------------
7345 @node Leaders, Fields, Tabs and Fields, Tabs and Fields
7349 Sometimes it may may be desirable to use the @code{tc} request to fill a
7350 particular tab stop with a given glyph (for example dots in a table
7351 of contents), but also normal tab stops on the rest of the line. For
7352 this @code{gtroff} provides an alternate tab mechanism, called
7353 @dfn{leaders} which does just that.
7355 @cindex leader character
7356 A leader character (character code@tie{}1) behaves similarly to a tab
7357 character: It moves to the next tab stop. The only difference is that
7358 for this movement, the fill glyph defaults to a period character and
7362 @cindex leader character, non-interpreted (@code{\a})
7363 @cindex character, leader, non-interpreted (@code{\a})
7364 This escape is a non-interpreted leader character. In copy mode
7365 (@pxref{Copy-in Mode}), @code{\a} is the same as a real leader
7369 @Defreq {lc, [@Var{fill-glyph}]}
7370 @cindex leader repetition character (@code{lc})
7371 @cindex character, leader repetition (@code{lc})
7372 @cindex glyph, leader repetition (@code{lc})
7373 Declare the @dfn{leader repetition character}.@footnote{@dfn{Leader
7374 repetition character} is a misnomer since it is an output glyph.}
7375 Without an argument, leaders act the same as tabs (i.e., using
7376 whitespace for filling). @code{gtroff}'s start-up value is a dot
7377 (@samp{.}). The value of the leader repetition character is
7378 associated with the current environment (@pxref{Environments}).
7381 @cindex table of contents
7382 @cindex contents, table of
7383 For a table of contents, to name an example, tab stops may be defined so
7384 that the section number is one tab stop, the title is the second with
7385 the remaining space being filled with a line of dots, and then the page
7386 number slightly separated from the dots.
7389 .ds entry 1.1\tFoo\a\t12
7399 1.1 Foo.......................................... 12
7402 @c ---------------------------------------------------------------------
7404 @node Fields, , Leaders, Tabs and Fields
7408 @cindex field delimiting character (@code{fc})
7409 @cindex delimiting character, for fields (@code{fc})
7410 @cindex character, field delimiting (@code{fc})
7411 @cindex field padding character (@code{fc})
7412 @cindex padding character, for fields (@code{fc})
7413 @cindex character, field padding (@code{fc})
7414 @dfn{Fields} are a more general way of laying out tabular data. A field
7415 is defined as the data between a pair of @dfn{delimiting characters}.
7416 It contains substrings which are separated by @dfn{padding characters}.
7417 The width of a field is the distance on the @emph{input} line from the
7418 position where the field starts to the next tab stop. A padding
7419 character inserts stretchable space similar to @TeX{}'s @code{\hss}
7420 command (thus it can even be negative) to make the sum of all substring
7421 lengths plus the stretchable space equal to the field width. If more
7422 than one padding character is inserted, the available space is evenly
7423 distributed among them.
7425 @Defreq {fc, [@Var{delim-char} [@Var{padding-char}]]}
7426 Define a delimiting and a padding character for fields. If the latter
7427 is missing, the padding character defaults to a space character. If
7428 there is no argument at all, the field mechanism is disabled (which is
7429 the default). Note that contrary to e.g.@: the tab repetition
7430 character, delimiting and padding characters are @emph{not} associated
7431 to the current environment (@pxref{Environments}).
7444 and here the result:
7453 @c =====================================================================
7455 @node Character Translations, Troff and Nroff Mode, Tabs and Fields, gtroff Reference
7456 @section Character Translations
7457 @cindex character translations
7458 @cindex translations of characters
7460 @cindex control character, changing (@code{cc})
7461 @cindex character, control, changing (@code{cc})
7462 @cindex no-break control character, changing (@code{c2})
7463 @cindex character, no-break control, changing (@code{c2})
7464 @cindex control character, no-break, changing (@code{c2})
7465 The control character (@samp{.}) and the no-break control character
7466 (@samp{'}) can be changed with the @code{cc} and @code{c2} requests,
7469 @Defreq {cc, [@Var{c}]}
7470 Set the control character to@tie{}@var{c}. With no argument the default
7471 control character @samp{.} is restored. The value of the control
7472 character is associated with the current environment
7473 (@pxref{Environments}).
7476 @Defreq {c2, [@Var{c}]}
7477 Set the no-break control character to@tie{}@var{c}. With no argument the
7478 default control character @samp{'} is restored. The value of the
7479 no-break control character is associated with the current environment
7480 (@pxref{Environments}).
7484 @cindex disabling @code{\} (@code{eo})
7485 @cindex @code{\}, disabling (@code{eo})
7486 Disable the escape mechanism completely. After executing this
7487 request, the backslash character @samp{\} no longer starts an escape
7490 This request can be very helpful in writing macros since it is not
7491 necessary then to double the escape character. Here an example:
7494 .\" This is a simplified version of the
7495 .\" .BR request from the man macro package
7499 . while (\n[.$] >= 2) \@{\
7500 . as result \fB\$1\fR\$2
7503 . if \n[.$] .as result \fB\$1
7511 @Defreq {ec, [@Var{c}]}
7512 @cindex escape character, changing (@code{ec})
7513 @cindex character, escape, changing (@code{ec})
7514 Set the escape character to@tie{}@var{c}. With no argument the default
7515 escape character @samp{\} is restored. It can be also used to
7516 re-enable the escape mechanism after an @code{eo} request.
7518 Note that changing the escape character globally will likely break
7519 macro packages since @code{gtroff} has no mechanism to `intern' macros,
7520 i.e., to convert a macro definition into an internal form which is
7521 independent of its representation (@TeX{} has this mechanism).
7522 If a macro is called, it is executed literally.
7526 @DefreqListEnd {ecr, }
7527 The @code{ecs} request saves the current escape character
7528 in an internal register.
7529 Use this request in combination with the @code{ec} request to
7530 temporarily change the escape character.
7532 The @code{ecr} request restores the escape character
7533 saved with @code{ecs}.
7534 Without a previous call to @code{ecs}, this request
7535 sets the escape character to @code{\}.
7538 @DefescList {\\\\, , , }
7539 @DefescItem {\\e, , , }
7540 @DefescListEnd {\\E, , , }
7541 Print the current escape character (which is the backslash character
7542 @samp{\} by default).
7544 @code{\\} is a `delayed' backslash; more precisely, it is the default
7545 escape character followed by a backslash, which no longer has special
7546 meaning due to the leading escape character. It is @emph{not} an escape
7547 sequence in the usual sense! In any unknown escape sequence
7548 @code{\@var{X}} the escape character is ignored and @var{X} is printed.
7549 But if @var{X} is equal to the current escape character, no warning is
7552 As a consequence, only at top-level or in a diversion a backslash glyph is
7553 printed; in copy-in mode, it expands to a single backslash which then
7554 combines with the following character to an escape sequence.
7556 The @code{\E} escape differs from @code{\e} by printing an escape
7557 character that is not interpreted in copy mode.
7558 Use this to define strings with escapes that work
7559 when used in copy mode (for example, as a macro argument).
7560 The following example defines strings to begin and end
7564 .ds @{ \v'-.3m'\s'\En[.s]*60/100'
7568 Another example to demonstrate the differences between the various escape
7569 sequences, using a strange escape character, @samp{-}.
7581 The result is surprising for most users, expecting @samp{1} since
7582 @samp{foo} is a valid identifier. What has happened? As mentioned
7583 above, the leading escape character makes the following character
7584 ordinary. Written with the default escape character the sequence
7585 @samp{--} becomes @samp{\-} -- this is the minus sign.
7587 If the escape character followed by itself is a valid escape sequence,
7588 only @code{\E} yields the expected result:
7601 Similar to @code{\\}, the sequence @code{\.} isn't a real escape sequence.
7602 As before, a warning message is suppressed if the escape character is
7603 followed by a dot, and the dot itself is printed.
7620 The first backslash is consumed while the macro is read, and the second
7621 is swallowed while exexuting macro @code{foo}.
7624 A @dfn{translation} is a mapping of an input character to an output
7625 glyph. The mapping occurs at output time, i.e., the input character
7626 gets assigned the metric information of the mapped output character
7627 right before input tokens are converted to nodes (@pxref{Gtroff
7628 Internals}, for more on this process).
7630 @DefreqList {tr, @Var{a}@Var{b}@Var{c}@Var{d}@dots{}}
7631 @DefreqListEnd {trin, @Var{a}@Var{b}@Var{c}@Var{d}@dots{}}
7632 Translate character @var{a} to glyph@tie{}@var{b}, character @var{c} to
7633 glyph@tie{}@var{d}, etc. If there is an odd number of arguments, the
7634 last one is translated to an unstretchable space (@w{@samp{\ }}).
7636 The @code{trin} request is identical to @code{tr},
7637 but when you unformat a diversion with @code{asciify}
7638 it ignores the translation.
7639 @xref{Diversions}, for details about the @code{asciify} request.
7645 @cindex @code{\(}, and translations
7646 @cindex @code{\[}, and translations
7647 @cindex @code{\'}, and translations
7648 @cindex @code{\`}, and translations
7649 @cindex @code{\-}, and translations
7650 @cindex @code{\_}, and translations
7651 @cindex @code{\C}, and translations
7652 @cindex @code{\N}, and translations
7653 @cindex @code{char} request, and translations
7654 @cindex special characters
7655 @cindex character, special
7656 @cindex numbered glyph (@code{\N})
7657 @cindex glyph, numbered (@code{\N})
7658 Special characters (@code{\(@var{xx}}, @code{\[@var{xxx}]},
7659 @code{\C'@var{xxx}'}, @code{\'}, @code{\`}, @code{\-}, @code{\_}),
7660 glyphs defined with the @code{char} request, and numbered glyphs
7661 (@code{\N'@var{xxx}'}) can be translated also.
7664 @cindex @code{\e}, and translations
7665 The @code{\e} escape can be translated also.
7668 @cindex @code{\%}, and translations
7669 @cindex @code{\~}, and translations
7670 Characters can be mapped onto the @code{\%} and @code{\~} escapes (but
7671 @code{\%} and @code{\~} can't be mapped onto another glyph).
7674 @cindex backspace character, and translations
7675 @cindex character, backspace, and translations
7676 @cindex leader character, and translations
7677 @cindex character, leader, and translations
7678 @cindex newline character, and translations
7679 @cindex character, newline, and translations
7680 @cindex tab character, and translations
7681 @cindex character, tab, and translations
7682 @cindex @code{\a}, and translations
7683 @cindex @code{\t}, and translations
7684 The following characters can't be translated: space (with one exception,
7685 see below), backspace, newline, leader (and @code{\a}), tab (and
7689 @cindex @code{shc} request, and translations
7690 Translations are not considered for finding the soft hyphen character
7691 set with the @code{shc} request.
7694 @cindex @code{\&}, and translations
7695 The pair @samp{@var{c}\&} (this is an arbitrary character@tie{}@var{c}
7696 followed by the zero width space character) maps this character to nothing.
7705 It is even possible to map the space character to nothing:
7714 As shown in the example, the space character can't be the first
7715 character/glyph pair as an argument of @code{tr}. Additionally, it is
7716 not possible to map the space character to any other glyph; requests
7717 like @w{@samp{.tr aa x}} undo @w{@samp{.tr aa \&}} instead.
7719 If justification is active, lines are justified in spite of the
7720 `empty' space character (but there is no minimal distance, i.e.@: the
7721 space character, between words).
7724 After an output glyph has been constructed (this happens at the
7725 moment immediately before the glyph is appended to an output
7726 glyph list, either by direct output, in a macro, diversion, or
7727 string), it is no longer affected by @code{tr}.
7730 Translating character to glyphs where one of them or both are
7731 undefined is possible also; @code{tr} does not check whether the
7732 entities in its argument do exist.
7734 @xref{Gtroff Internals}.
7737 @code{troff} no longer has a hard-coded dependency on @w{Latin-1};
7738 all @code{char@var{XXX}} entities have been removed from the font
7739 description files. This has a notable consequence which shows up in
7740 warnings like @code{can't find character with input code @var{XXX}}
7741 if the @code{tr} request isn't handled properly.
7743 Consider the following translation:
7750 This maps input character @code{é} onto glyph @code{É}, which is
7751 identical to glyph @code{char201}. But this glyph intentionally
7752 doesn't exist! Instead, @code{\[char201]} is treated as an input
7753 character entity and is by default mapped onto @code{\['E]}, and
7754 @code{gtroff} doesn't handle translations of translations.
7756 The right way to write the above translation is
7763 With other words, the first argument of @code{tr} should be an input
7764 character or entity, and the second one a glyph entity.
7767 Without an argument, the @code{tr} request is ignored.
7771 @Defreq {trnt, @Var{a}@Var{b}@Var{c}@Var{d}@dots{}}
7772 @cindex @code{\!}, and @code{trnt}
7773 @code{trnt} is the same as the @code{tr} request except that the
7774 translations do not apply to text that is transparently throughput
7775 into a diversion with @code{\!}. @xref{Diversions}, for more
7789 prints @samp{b} to the standard error stream; if @code{trnt} is used
7790 instead of @code{tr} it prints @samp{a}.
7794 @c =====================================================================
7796 @node Troff and Nroff Mode, Line Layout, Character Translations, gtroff Reference
7797 @section Troff and Nroff Mode
7803 Originally, @code{nroff} and @code{troff} were two separate programs,
7804 the former for TTY output, the latter for everything else. With GNU
7805 @code{troff}, both programs are merged into one executable, sending
7806 its output to a device driver (@code{grotty} for TTY devices,
7807 @code{grops} for @sc{PostScript}, etc.) which interprets the
7808 intermediate output of @code{gtroff}. For @acronym{UNIX} @code{troff}
7809 it makes sense to talk about @dfn{Nroff mode} and @dfn{Troff mode}
7810 since the differences are hardcoded. For GNU @code{troff}, this
7811 distinction is not appropriate because @code{gtroff} simply takes the
7812 information given in the font files for a particular device without
7813 handling requests specially if a TTY output device is used.
7815 Usually, a macro package can be used with all output devices.
7816 Nevertheless, it is sometimes necessary to make a distinction between
7817 TTY and non-TTY devices: @code{gtroff} provides two built-in
7818 conditions @samp{n} and @samp{t} for the @code{if}, @code{ie}, and
7819 @code{while} requests to decide whether @code{gtroff} shall behave
7820 like @code{nroff} or like @code{troff}.
7825 Make the @samp{t} built-in condition true (and the @samp{n} built-in
7826 condition false) for @code{if}, @code{ie}, and @code{while}
7827 conditional requests. This is the default if @code{gtroff}
7828 (@emph{not} @code{groff}) is started with the @option{-R} switch to
7829 avoid loading of the start-up files @file{troffrc} and
7830 @file{troffrc-end}. Without @option{-R}, @code{gtroff} stays in troff
7831 mode if the output device is not a TTY (e.g.@: `ps').
7836 Make the @samp{n} built-in condition true (and the @samp{t} built-in
7837 condition false) for @code{if}, @code{ie}, and @code{while}
7838 conditional requests. This is the default if @code{gtroff} uses a TTY
7839 output device; the code for switching to nroff mode is in the file
7840 @file{tty.tmac} which is loaded by the start-up file @code{troffrc}.
7843 @xref{Conditionals and Loops}, for more details on built-in
7847 @c =====================================================================
7849 @node Line Layout, Line Control, Troff and Nroff Mode, gtroff Reference
7850 @section Line Layout
7852 @cindex layout, line
7854 @cindex dimensions, line
7855 @cindex line dimensions
7856 The following drawing shows the dimensions which @code{gtroff} uses for
7857 placing a line of output onto the page. They are labeled with the
7858 request which manipulates each dimension.
7862 |<-----------ll------------>|
7863 +----+----+----------------------+----+
7865 +----+----+----------------------+----+
7867 |<--------paper width---------------->|
7871 These dimensions are:
7875 @cindex left margin (@code{po})
7876 @cindex margin, left (@code{po})
7877 @cindex page offset (@code{po})
7878 @cindex offset, page (@code{po})
7879 @dfn{Page offset} -- this is the leftmost position of text on the final
7880 output, defining the @dfn{left margin}.
7883 @cindex indentation (@code{in})
7884 @cindex line indentation (@code{in})
7885 @dfn{Indentation} -- this is the distance from the left margin where
7889 @cindex line length (@code{ll})
7890 @cindex length of line (@code{ll})
7891 @dfn{Line length} -- this is the distance from the left margin to right
7895 A simple demonstration:
7899 This is text without indentation.
7900 The line length has been set to 3\~inch.
7903 Now the left and right margins are both increased.
7906 Calling .in and .ll without parameters restore
7907 the previous values.
7913 This is text without indenta-
7914 tion. The line length has
7919 Calling .in and .ll without
7920 parameters restore the previ-
7924 @DefreqList {po, [@Var{offset}]}
7925 @DefreqItem {po, @t{+}@Var{offset}}
7926 @DefreqItem {po, @t{-}@Var{offset}}
7929 Set horizontal page offset to @var{offset} (or increment or decrement
7930 the current value by @var{offset}). Note that this request does not
7931 cause a break, so changing the page offset in the middle of text being
7932 filled may not yield the expected result. The initial value is
7933 1@dmn{i}. For TTY output devices, it is set to 0 in the startup file
7934 @file{troffrc}; the default scaling indicator is @samp{m} (and
7935 not @samp{v} as incorrectly documented in the original
7936 @acronym{UNIX} troff manual).
7938 The current page offset can be found in the read-only number register
7941 If @code{po} is called without an argument, the page offset is reset to
7942 the previous value before the last call to @code{po}.
7957 @DefreqList {in, [@Var{indent}]}
7958 @DefreqItem {in, @t{+}@Var{indent}}
7959 @DefreqItem {in, @t{-}@Var{indent}}
7961 Set indentation to @var{indent} (or increment or decrement the
7962 current value by @var{indent}). This request causes a break.
7963 Initially, there is no indentation.
7965 If @code{in} is called without an argument, the indentation is reset to
7966 the previous value before the last call to @code{in}. The default
7967 scaling indicator is @samp{m}.
7969 The indentation is associated with the current environment
7970 (@pxref{Environments}).
7972 If a negative indentation value is specified (which is not allowed),
7973 @code{gtroff} emits a warning of type @samp{range} and sets the
7974 indentation to zero.
7976 The effect of @code{in} is delayed until a partially collected line (if
7977 it exists) is output. A temporary indent value is reset to zero also.
7979 The current indentation (as set by @code{in}) can be found in the
7980 read-only number register @samp{.i}.
7983 @DefreqList {ti, offset}
7984 @DefreqItem {ti, @t{+}@Var{offset}}
7985 @DefreqItem {ti, @t{-}@Var{offset}}
7986 @DefregListEnd {.in}
7987 Temporarily indent the next output line by @var{offset}. If an
7988 increment or decrement value is specified, adjust the temporary
7989 indentation relative to the value set by the @code{in} request.
7991 This request causes a break; its value is associated with the current
7992 environment (@pxref{Environments}). The default scaling indicator
7993 is @samp{m}. A call of @code{ti} without an argument is ignored.
7995 If the total indentation value is negative (which is not allowed),
7996 @code{gtroff} emits a warning of type @samp{range} and sets the
7997 temporary indentation to zero. `Total indentation' is either
7998 @var{offset} if specified as an absolute value, or the temporary plus
7999 normal indentation, if @var{offset} is given as a relative value.
8001 The effect of @code{ti} is delayed until a partially collected line (if
8002 it exists) is output.
8004 The read-only number register @code{.in} is the indentation that applies
8005 to the current output line.
8007 The difference between @code{.i} and @code{.in} is that the latter takes
8008 into account whether a partially collected line still uses the old
8009 indentation value or a temporary indentation value is active.
8012 @DefreqList {ll, [@Var{length}]}
8013 @DefreqItem {ll, @t{+}@Var{length}}
8014 @DefreqItem {ll, @t{-}@Var{length}}
8016 @DefregListEnd {.ll}
8017 Set the line length to @var{length} (or increment or decrement the
8018 current value by @var{length}). Initially, the line length is set to
8019 6.5@dmn{i}. The effect of @code{ll} is delayed until a partially
8020 collected line (if it exists) is output. The default scaling
8021 indicator is @samp{m}.
8023 If @code{ll} is called without an argument, the line length is reset to
8024 the previous value before the last call to @code{ll}. If a negative
8025 line length is specified (which is not allowed), @code{gtroff} emits a
8026 warning of type @samp{range} and sets the line length to zero.
8028 The line length is associated with the current environment
8029 (@pxref{Environments}).
8031 @cindex line length register (@code{.l})
8032 The current line length (as set by @code{ll}) can be found in the
8033 read-only number register @samp{.l}. The read-only number register
8034 @code{.ll} is the line length that applies to the current output line.
8036 Similar to @code{.i} and @code{.in}, the difference between @code{.l}
8037 and @code{.ll} is that the latter takes into account whether a partially
8038 collected line still uses the old line length value.
8042 @c =====================================================================
8044 @node Line Control, Page Layout, Line Layout, gtroff Reference
8045 @section Line Control
8046 @cindex line control
8047 @cindex control, line
8049 It is important to understand how @code{gtroff} handles input and output
8052 Many escapes use positioning relative to the input line. For example,
8056 This is a \h'|1.2i'test.
8071 The main usage of this feature is to define macros which act exactly
8072 at the place where called.
8075 .\" A simple macro to underline a word
8077 . nop \\$1\l'|0\[ul]'
8082 In the above example, @samp{|0} specifies a negative distance from the
8083 current position (at the end of the just emitted argument @code{\$1}) back
8084 to the beginning of the input line. Thus, the @samp{\l} escape draws a
8085 line from right to left.
8087 @cindex input line continuation (@code{\})
8088 @cindex line, input, continuation (@code{\})
8089 @cindex continuation, input line (@code{\})
8090 @cindex output line, continuation (@code{\c})
8091 @cindex line, output, continuation (@code{\c})
8092 @cindex continuation, output line (@code{\c})
8093 @cindex interrupted line
8094 @cindex line, interrupted
8095 @code{gtroff} makes a difference between input and output line
8096 continuation; the latter is also called @dfn{interrupting} a line.
8098 @DefescList {\\@key{RET}, , ,}
8099 @DefescItem {\\c, , ,}
8100 @DefregListEnd{.int}
8101 Continue a line. @code{\@key{RET}} (this is a backslash at the end
8102 of a line immediately followed by a newline) works on the input level,
8103 suppressing the effects of the following newline in the input.
8108 @result{} This is a .test
8111 The @samp{|} operator is also affected.
8113 @cindex @code{\R}, after @code{\c}
8114 @code{\c} works on the output level. Anything after this escape on the
8115 same line is ignored, except @code{\R} which works as usual. Anything
8116 before @code{\c} on the same line will be appended to the current partial
8117 output line. The next non-command line after an interrupted line counts
8118 as a new input line.
8120 The visual results depend on whether no-fill mode is active.
8124 @cindex @code{\c}, and no-fill mode
8125 @cindex no-fill mode, and @code{\c}
8126 @cindex mode, no-fill, and @code{\c}
8127 If no-fill mode is active (using the @code{nf} request), the next input
8128 text line after @code{\c} will be handled as a continuation of the same
8135 @result{} This is a test.
8139 @cindex @code{\c}, and fill mode
8140 @cindex fill mode, and @code{\c}
8141 @cindex mode, fill, and @code{\c}
8142 If fill mode is active (using the @code{fi} request), a word interrupted
8143 with @code{\c} will be continued with the text on the next input text line,
8144 without an intervening space.
8149 @result{} This is a test.
8153 Note that an intervening control line which causes a break is stronger
8154 than @code{\c}, flushing out the current partial line in the usual way.
8156 @cindex interrupted line register (@code{.int})
8157 The @code{.int} register contains a positive value
8158 if the last output line was interrupted with @code{\c}; this is
8159 associated with the current environment (@pxref{Environments}).
8162 @c =====================================================================
8164 @node Page Layout, Page Control, Line Control, gtroff Reference
8165 @section Page Layout
8167 @cindex layout, page
8169 @code{gtroff} provides some very primitive operations for controlling
8172 @DefreqList {pl, [@Var{length}]}
8173 @DefreqItem {pl, @t{+}@Var{length}}
8174 @DefreqItem {pl, @t{-}@Var{length}}
8176 @cindex page length (@code{pl})
8177 @cindex length of page (@code{pl})
8178 Set the @dfn{page length} to @var{length} (or increment or decrement
8179 the current value by @var{length}). This is the length of the
8180 physical output page. The default scaling indicator is @samp{v}.
8182 @cindex page length register (@code{.p})
8183 The current setting can be found in the read-only number register
8188 @cindex bottom margin
8189 @cindex margin, bottom
8190 Note that this only specifies the size of the page, not the top and
8191 bottom margins. Those are not set by @code{gtroff} directly.
8192 @xref{Traps}, for further information on how to do this.
8194 Negative @code{pl} values are possible also, but not very useful: No
8195 trap is sprung, and each line is output on a single page (thus
8196 suppressing all vertical spacing).
8198 If no argument or an invalid argument is given, @code{pl} sets the page
8199 length to 11@dmn{i}.
8205 @code{gtroff} provides several operations which help in setting up top
8206 and bottom titles (or headers and footers).
8208 @Defreq {tl, @t{'}@Var{left}@t{'}@Var{center}@t{'}@Var{right}@t{'}}
8209 @cindex title line (@code{tl})
8210 @cindex three-part title (@code{tl})
8211 @cindex page number character (@code{%})
8212 Print a @dfn{title line}. It consists of three parts: a left
8213 justified portion, a centered portion, and a right justified portion.
8214 The argument separator @samp{'} can be replaced with any character not
8215 occurring in the title line. The @samp{%} character is replaced with
8216 the current page number. This character can be changed with the
8217 @code{pc} request (see below).
8219 Without argument, @code{tl} is ignored.
8225 A title line is not restricted to the top or bottom of a page.
8228 @code{tl} prints the title line immediately, ignoring a partially filled
8229 line (which stays untouched).
8232 It is not an error to omit closing delimiters. For example,
8233 @w{@samp{.tl /foo}} is equivalent to @w{@samp{.tl /foo///}}: It prints a
8234 title line with the left justified word @samp{foo}; the centered and
8235 right justfied parts are empty.
8238 @code{tl} accepts the same parameter delimiting characters as the
8239 @code{\A} escape; see @ref{Escapes}.
8243 @DefreqList {lt, [@Var{length}]}
8244 @DefreqItem {lt, @t{+}@Var{length}}
8245 @DefreqItem {lt, @t{-}@Var{length}}
8246 @DefregListEnd {.lt}
8247 @cindex length of title line (@code{lt})
8248 @cindex title line, length (@code{lt})
8249 @cindex title line length register (@code{.lt})
8250 The title line is printed using its own line length, which is
8251 specified (or incremented or decremented) with the @code{lt} request.
8252 Initially, the title line length is set to 6.5@dmn{i}. If a negative
8253 line length is specified (which is not allowed), @code{gtroff} emits a
8254 warning of type @samp{range} and sets the title line length to zero.
8255 The default scaling indicator is @samp{m}. If @code{lt} is called
8256 without an argument, the title length is reset to the previous value
8257 before the last call to @code{lt}.
8259 The current setting of this is available in the @code{.lt} read-only
8260 number register; it is associated with the current environment
8261 (@pxref{Environments}).
8264 @DefreqList {pn, page}
8265 @DefreqItem {pn, @t{+}@Var{page}}
8266 @DefreqItem {pn, @t{-}@Var{page}}
8267 @DefregListEnd {.pn}
8268 @cindex page number (@code{pn})
8269 @cindex number, page (@code{pn})
8270 Change (increase or decrease) the page number of the @emph{next} page.
8271 The only argument is the page number; the request is ignored without a
8274 The read-only number register @code{.pn} contains the number of the next
8275 page: either the value set by a @code{pn} request, or the number of the
8276 current page plus@tie{}1.
8279 @Defreq {pc, [@Var{char}]}
8280 @cindex changing the page number character (@code{pc})
8281 @cindex page number character, changing (@code{pc})
8283 Change the page number character (used by the @code{tl} request) to a
8284 different character. With no argument, this mechanism is disabled.
8285 Note that this doesn't affect the number register@tie{}@code{%}.
8291 @c =====================================================================
8293 @node Page Control, Fonts and Symbols, Page Layout, gtroff Reference
8294 @section Page Control
8295 @cindex page control
8296 @cindex control, page
8298 @DefreqList {bp, [@Var{page}]}
8299 @DefreqItem {bp, @t{+}@Var{page}}
8300 @DefreqItem {bp, @t{-}@Var{page}}
8302 @cindex new page (@code{bp})
8303 @cindex page, new (@code{bp})
8304 Stop processing the current page and move to the next page. This
8305 request causes a break. It can also take an argument to set
8306 (increase, decrease) the page number of the next page (which actually
8307 becomes the current page after @code{bp} has finished). The
8308 difference between @code{bp} and @code{pn} is that @code{pn} does not
8309 cause a break or actually eject a page. @xref{Page Layout}.
8312 .de newpage \" define macro
8314 'sp .5i \" vertical space
8315 .tl 'left top'center top'right top' \" title
8316 'sp .3i \" vertical space
8320 @cindex @code{bp} request, and top-level diversion
8321 @cindex top-level diversion, and @code{bp}
8322 @cindex diversion, top-level, and @code{bp}
8323 @code{bp} has no effect if not called within the top-level diversion
8324 (@pxref{Diversions}).
8326 @cindex page number register (@code{%})
8327 @cindex current page number (@code{%})
8328 The read-write register@tie{}@code{%} holds the current page number.
8330 The number register @code{.pe} is set to@tie{}1 while @code{bp} is
8331 active. @xref{Page Location Traps}.
8334 @Defreq {ne, [@Var{space}]}
8335 @cindex orphan lines, preventing with @code{ne}
8336 @cindex conditional page break (@code{ne})
8337 @cindex page break, conditional (@code{ne})
8338 It is often necessary to force a certain amount of space before a new
8339 page occurs. This is most useful to make sure that there is not a
8340 single @dfn{orphan} line left at the bottom of a page. The @code{ne}
8341 request ensures that there is a certain distance, specified by the
8342 first argument, before the next page is triggered (see @ref{Traps},
8343 for further information). The default scaling indicator for @code{ne}
8344 is @samp{v}; the default value of @var{space} is@tie{}1@dmn{v} if no
8347 For example, to make sure that no fewer than 2@tie{}lines get orphaned,
8348 do the following before each paragraph:
8355 @code{ne} will then automatically cause a page break if there is space
8359 @DefreqList {sv, [@Var{space}]}
8360 @DefreqListEnd {os, }
8361 @cindex @code{ne} request, comparison with @code{sv}
8362 @code{sv} is similar to the @code{ne} request; it reserves the
8363 specified amount of vertical space. If the desired amount of space
8364 exists before the next trap (or the bottom page boundary if no trap is
8365 set), the space is output immediately (ignoring a partially filled line
8366 which stays untouched). If there is not enough space, it is stored for
8367 later output via the @code{os} request. The default value is@tie{}1@dmn{v}
8368 if no argument is given; the default scaling indicator is @samp{v}.
8370 @cindex @code{sv} request, and no-space mode
8371 @cindex @code{os} request, and no-space mode
8372 Both @code{sv} and @code{os} ignore no-space mode. While the @code{sv}
8373 request allows negative values for @var{space}, @code{os} will ignore
8378 @cindex current vertical position (@code{nl})
8379 @cindex vertical position, current (@code{nl})
8380 @cindex position, vertical, current (@code{nl})
8381 This register contains the current vertical position. If the vertical
8382 position is zero and the top of page transition hasn't happened yet,
8383 @code{nl} is set to negative value. @code{gtroff} itself does this at
8384 the very beginning of a document before anything has been printed, but
8385 the main usage is to plant a header trap on a page if this page has
8388 Consider the following:
8420 Without resetting @code{nl} to a negative value, the just planted trap
8421 would be active beginning with the @emph{next} page, not the current
8424 @xref{Diversions}, for a comparison with the @code{.h} and @code{.d}
8428 @c =====================================================================
8430 @node Fonts and Symbols, Sizes, Page Control, gtroff Reference
8431 @section Fonts and Symbols
8434 @code{gtroff} can switch fonts at any point in the text.
8436 The basic set of fonts is @samp{R}, @samp{I}, @samp{B}, and @samp{BI}.
8437 These are Times Roman, Italic, Bold, and Bold Italic. For non-TTY
8438 devices, there is also at least one symbol font which contains various
8439 special symbols (Greek, mathematics).
8447 * Artificial Fonts::
8448 * Ligatures and Kerning::
8451 @c ---------------------------------------------------------------------
8453 @node Changing Fonts, Font Families, Fonts and Symbols, Fonts and Symbols
8454 @subsection Changing Fonts
8457 @DefreqList {ft, [@Var{font}]}
8458 @DefescItem {\\f, , f, }
8459 @DefescItem {\\f, @Lparen{}, fn, }
8460 @DefescItem {\\f, @Lbrack{}, font, @Rbrack{}}
8461 @DefregListEnd {.sty}
8462 @cindex changing fonts (@code{ft}, @code{\f})
8463 @cindex fonts, changing (@code{ft}, @code{\f})
8464 @cindex @code{sty} request, and changing fonts
8465 @cindex @code{fam} request, and changing fonts
8466 @cindex @code{\F}, and changing fonts
8470 The @code{ft} request and the @code{\f} escape change the current font
8471 to @var{font} (one-character name@tie{}@var{f}, two-character name
8474 If @var{font} is a style name (as set with the @code{sty} request or
8475 with the @code{styles} command in the @file{DESC} file), use it within
8476 the current font family (as set with the @code{fam} request, @code{\F}
8477 escape, or with the @code{family} command in the @file{DESC} file).
8479 @cindex previous font (@code{ft}, @code{\f[]}, @code{\fP})
8480 @cindex font, previous (@code{ft}, @code{\f[]}, @code{\fP})
8481 With no argument or using @samp{P} as an argument, @code{.ft} switches
8482 to the previous font. Use @code{\f[]} to do this with the escape. The
8483 old syntax forms @code{\fP} or @code{\f[P]} are also supported.
8485 Fonts are generally specified as upper-case strings, which are usually
8486 1@tie{}to 4 characters representing an abbreviation or acronym of the
8487 font name. This is no limitation, just a convention.
8489 The example below produces two identical lines.
8498 eggs, bacon, \fBspam\fP and sausage.
8501 Note that @code{\f} doesn't produce an input token in @code{gtroff}.
8502 As a consequence, it can be used in requests like @code{mc} (which
8503 expects a single character as an argument) to change the font on
8510 The current style name is available in the read-only number register
8511 @samp{.sty} (this is a string-valued register); if the current font
8512 isn't a style, the empty string is returned. It is associated with
8513 the current environment.
8515 @xref{Font Positions}, for an alternative syntax.
8518 @Defreq {ftr, f [@Var{g}]}
8519 @cindex @code{ft} request, and font translations
8520 @cindex @code{ul} request, and font translations
8521 @cindex @code{bd} request, and font translations
8522 @cindex @code{\f}, and font translations
8523 @cindex @code{cs} request, and font translations
8524 @cindex @code{tkf} request, and font translations
8525 @cindex @code{special} request, and font translations
8526 @cindex @code{fspecial} request, and font translations
8527 @cindex @code{fp} request, and font translations
8528 @cindex @code{sty} request, and font translations
8529 @cindex @code{if} request, and font translations
8530 @cindex @code{ie} request, and font translations
8531 @cindex @code{while} request, and font translations
8532 Translate font@tie{}@var{f} to font@tie{}@var{g}. Whenever a font
8533 named@tie{}@var{f} is referred to in a @code{\f} escape sequence,
8534 in the @code{F} and @code{S} conditional operators, or in the
8535 @code{ft}, @code{ul}, @code{bd}, @code{cs}, @code{tkf},
8536 @code{special}, @code{fspecial}, @code{fp}, or @code{sty} requests,
8537 font@tie{}@var{g} is used. If @var{g} is missing or equal to@tie{}@var{f}
8538 the translation is undone.
8541 @c ---------------------------------------------------------------------
8543 @node Font Families, Font Positions, Changing Fonts, Fonts and Symbols
8544 @subsection Font Families
8545 @cindex font families
8546 @cindex families, font
8548 @cindex styles, font
8550 Due to the variety of fonts available, @code{gtroff} has added the
8551 concept of @dfn{font families} and @dfn{font styles}. The fonts are
8552 specified as the concatenation of the font family and style. Specifying
8553 a font without the family part causes @code{gtroff} to use that style of
8556 @cindex PostScript fonts
8557 @cindex fonts, PostScript
8558 Currently, fonts for the devices @option{-Tps}, @option{-Tdvi},
8559 @option{-Tlj4}, @option{-Tlbp}, and the X11 fonts are set up to this
8560 mechanism. By default, @code{gtroff} uses the Times family with the four
8561 styles @samp{R}, @samp{I}, @samp{B}, and @samp{BI}.
8563 This way, it is possible to use the basic four fonts and to select a
8564 different font family on the command line (@pxref{Groff Options}).
8566 @DefreqList {fam, [@Var{family}]}
8568 @DefescItem {\\F, , f, }
8569 @DefescItem {\\F, @Lparen{}, fm, }
8570 @DefescItem {\\F, @Lbrack{}, family, @Rbrack{}}
8571 @DefregListEnd {.fn}
8572 @cindex changing font family (@code{fam}, @code{\F})
8573 @cindex font family, changing (@code{fam}, @code{\F})
8574 Switch font family to @var{family} (one-character name@tie{}@var{f},
8575 two-character name @var{fm}). If no argument is given, switch
8576 back to the previous font family. Use @code{\F[]} to do this with the
8577 escape. Note that @code{\FP} doesn't work; it selects font family
8580 The value at start-up is @samp{T}.
8581 The current font family is available in the read-only number register
8582 @samp{.fam} (this is a string-valued register); it is associated with
8583 the current environment.
8587 .fam H \" helvetica family
8588 spam, \" used font is family H + style R = HR
8589 .ft B \" family H + style B = font HB
8591 .fam T \" times family
8592 spam, \" used font is family T + style B = TB
8593 .ft AR \" font AR (not a style)
8595 .ft R \" family T + style R = font TR
8599 Note that @code{\F} doesn't produce an input token in @code{gtroff}.
8600 As a consequence, it can be used in requests like @code{mc} (which
8601 expects a single character as an argument) to change the font family on
8608 The @samp{.fn} register contains the current @dfn{real font name}
8609 of the current font.
8610 This is a string-valued register.
8611 If the current font is a style, the value of @code{\n[.fn]}
8612 is the proper concatenation of family and style name.
8615 @Defreq {sty, n style}
8616 @cindex changing font style (@code{sty})
8617 @cindex font style, changing (@code{sty})
8618 @cindex @code{cs} request, and font styles
8619 @cindex @code{bd} request, and font styles
8620 @cindex @code{tkf} request, and font styles
8621 @cindex @code{uf} request, and font styles
8622 @cindex @code{fspecial} request, and font styles
8623 Associate @var{style} with font position@tie{}@var{n}. A font position
8624 can be associated either with a font or with a style. The current
8625 font is the index of a font position and so is also either a font or a
8626 style. If it is a style, the font that is actually used is the font
8627 which name is the concatenation of the name of the current
8628 family and the name of the current style. For example, if the current
8629 font is@tie{}1 and font position@tie{}1 is associated with style
8630 @samp{R} and the current font family is @samp{T}, then font
8631 @samp{TR} will be used. If the current font is not a style, then the
8632 current family is ignored. If the requests @code{cs}, @code{bd},
8633 @code{tkf}, @code{uf}, or @code{fspecial} are applied to a style,
8634 they will instead be applied to the member of the current family
8635 corresponding to that style.
8637 @var{n}@tie{}must be a non-negative integer value.
8641 The default family can be set with the @option{-f} option
8642 (@pxref{Groff Options}). The @code{styles} command in the @file{DESC}
8643 file controls which font positions (if any) are initially associated
8644 with styles rather than fonts. For example, the default setting for
8645 @sc{PostScript} fonts
8661 @code{fam} and @code{\F} always check whether the current font position
8662 is valid; this can give surprising results if the current font position is
8663 associated with a style.
8665 In the following example, we want to access the @sc{PostScript} font
8666 @code{FooBar} from the font family @code{Foo}:
8671 @result{} warning: can't find font `FooR'
8675 The default font position at start-up is@tie{}1; for the
8676 @sc{PostScript} device, this is associated with style @samp{R}, so
8677 @code{gtroff} tries to open @code{FooR}.
8679 A solution to this problem is to use a dummy font like the following:
8682 .fp 0 dummy TR \" set up dummy font at position 0
8683 .sty \n[.fp] Bar \" register style `Bar'
8684 .ft 0 \" switch to font at position 0
8685 .fam Foo \" activate family `Foo'
8686 .ft Bar \" switch to font `FooBar'
8689 @xref{Font Positions}.
8692 @c ---------------------------------------------------------------------
8694 @node Font Positions, Using Symbols, Font Families, Fonts and Symbols
8695 @subsection Font Positions
8696 @cindex font positions
8697 @cindex positions, font
8699 For the sake of old phototypesetters and compatibility with old versions
8700 of @code{troff}, @code{gtroff} has the concept of font @dfn{positions},
8701 on which various fonts are mounted.
8703 @DefreqList {fp, pos font [@Var{external-name}]}
8705 @DefregListEnd {.fp}
8706 @cindex mounting font (@code{fp})
8707 @cindex font, mounting (@code{fp})
8708 Mount font @var{font} at position @var{pos} (which must be a
8709 non-negative integer). This numeric position can then be referred to
8710 with font changing commands. When @code{gtroff} starts it is using
8711 font position@tie{}1 (which must exist; position@tie{}0 is unused
8712 usually at start-up).
8714 @cindex font position register (@code{.f})
8715 The current font in use, as a font position, is available in the
8716 read-only number register @samp{.f}. This can be useful to remember the
8717 current font for later recall. It is associated with the current
8718 environment (@pxref{Environments}).
8721 .nr save-font \n[.f]
8723 ... text text text ...
8727 @cindex next free font position register (@code{.fp})
8728 The number of the next free font position is available in the read-only
8729 number register @samp{.fp}. This is useful when mounting a new font,
8733 .fp \n[.fp] NEATOFONT
8736 @pindex DESC@r{, and font mounting}
8737 Fonts not listed in the @file{DESC} file are automatically mounted on
8738 the next available font position when they are referenced. If a font
8739 is to be mounted explicitly with the @code{fp} request on an unused
8740 font position, it should be mounted on the first unused font position,
8741 which can be found in the @code{.fp} register. Although @code{gtroff}
8742 does not enforce this strictly, it is not allowed to mount a font at a
8743 position whose number is much greater (approx.@: 1000 positions) than
8744 that of any currently used position.
8746 The @code{fp} request has an optional third argument. This argument
8747 gives the external name of the font, which is used for finding the font
8748 description file. The second argument gives the internal name of the
8749 font which is used to refer to the font in @code{gtroff} after it has
8750 been mounted. If there is no third argument then the internal name is
8751 used as the external name. This feature makes it possible to use
8752 fonts with long names in compatibility mode.
8755 Both the @code{ft} request and the @code{\f} escape have alternative
8756 syntax forms to access font positions.
8758 @DefreqList {ft, nnn}
8759 @DefescItem {\\f, , n, }
8760 @DefescItem {\\f, @Lparen{}, nn, }
8761 @DefescListEnd {\\f, @Lbrack{}, nnn, @Rbrack{}}
8762 @cindex changing font position (@code{\f})
8763 @cindex font position, changing (@code{\f})
8764 @cindex @code{sty} request, and font positions
8765 @cindex @code{fam} request, and font positions
8766 @cindex @code{\F}, and font positions
8770 Change the current font position to @var{nnn} (one-digit
8771 position@tie{}@var{n}, two-digit position @var{nn}), which must be a
8772 non-negative integer.
8774 If @var{nnn} is associated with a style (as set with the @code{sty}
8775 request or with the @code{styles} command in the @file{DESC} file), use
8776 it within the current font family (as set with the @code{fam} request,
8777 the @code{\F} escape, or with the @code{family} command in the @file{DESC}
8784 .ft \" switch back to font 1
8788 this is font 1 again
8791 @xref{Changing Fonts}, for the standard syntax form.
8794 @c ---------------------------------------------------------------------
8796 @node Using Symbols, Special Fonts, Font Positions, Fonts and Symbols
8797 @subsection Using Symbols
8798 @cindex using symbols
8799 @cindex symbols, using
8804 A @dfn{glyph} is a graphical representation of a @dfn{character}.
8805 While a character is an abstract entity containing semantic
8806 information, a glyph is something which can be actually seen on screen
8807 or paper. It is possible that a character has multiple glyph
8808 representation forms (for example, the character `A' can be either
8809 written in a roman or an italic font, yielding two different glyphs);
8810 sometimes more than one character maps to a single glyph (this is a
8811 @dfn{ligature} -- the most common is `fi').
8814 @cindex special fonts
8817 @cindex @code{special} request, and glyph search order
8818 @cindex @code{fspecial} request, and glyph search order
8819 A @dfn{symbol} is simply a named glyph. Within @code{gtroff}, all
8820 glyph names of a particular font are defined in its font file. If the
8821 user requests a glyph not available in this font, @code{gtroff} looks
8822 up an ordered list of @dfn{special fonts}. By default, the
8823 @sc{PostScript} output device supports the two special fonts @samp{SS}
8824 (slanted symbols) and @samp{S} (symbols) (the former is looked up
8825 before the latter). Other output devices use different names for
8826 special fonts. Fonts mounted with the @code{fonts} keyword in the
8827 @file{DESC} file are globally available. To install additional
8828 special fonts locally (i.e.@: for a particular font), use the
8829 @code{fspecial} request.
8831 Here the exact rules how @code{gtroff} searches a given symbol:
8835 If the symbol has been defined with the @code{char} request, use it.
8836 This hides a symbol with the same name in the current font.
8839 Check the current font.
8842 If the symbol has been defined with the @code{fchar} request, use it.
8845 Check whether the current font has a font-specific list of special fonts;
8846 test all fonts in the order of appearance in the last @code{fspecial}
8847 call if appropriate.
8850 If the symbol has been defined with the @code{fschar} request for the
8851 current font, use it.
8854 Check all fonts in the order of appearance in the last @code{special}
8858 If the symbol has been defined with the @code{schar} request, use it.
8861 As a last resort, consult all fonts loaded up to now for special fonts
8862 and check them, starting with the lowest font number. Note that this can
8863 sometimes lead to surprising results since the @code{fonts} line in the
8864 @file{DESC} file often contains empty positions which are filled later
8865 on. For example, consider the following:
8872 This mounts font @code{foo} at font position@tie{}3. We assume that
8873 @code{FOO} is a special font, containing glyph @code{foo},
8874 and that no font has been loaded yet. The line
8881 makes font @code{BAZ} special only if font @code{BAR} is active. We
8882 further assume that @code{BAZ} is really a special font, i.e., the font
8883 description file contains the @code{special} keyword, and that it
8884 also contains glyph @code{foo} with a special shape fitting to font
8885 @code{BAR}. After executing @code{fspecial}, font @code{BAR} is loaded at
8886 font position@tie{}1, and @code{BAZ} at position@tie{}2.
8888 We now switch to a new font @code{XXX}, trying to access glyph @code{foo}
8889 which is assumed to be missing. There are neither font-specific special
8890 fonts for @code{XXX} nor any other fonts made special with the
8891 @code{special} request, so @code{gtroff} starts the search for special
8892 fonts in the list of already mounted fonts, with increasing font
8893 positions. Consequently, it finds @code{BAZ} before @code{FOO} even for
8894 @code{XXX} which is not the intended behaviour.
8897 @xref{Font Files}, and @ref{Special Fonts}, for more details.
8899 @cindex list of available glyphs (@cite{groff_char(7)} man page)
8900 @cindex available glyphs, list (@cite{groff_char(7)} man page)
8901 @cindex glyphs, available, list (@cite{groff_char(7)} man page)
8902 The list of available symbols is device dependent; see the
8903 @cite{groff_char(7)} man page for a complete list of all glyphs. For
8907 man -Tdvi groff_char > groff_char.dvi
8911 for a list using the default DVI fonts (not all versions of the
8912 @code{man} program support the @option{-T} option). If you want to
8913 use an additional macro package to change the used fonts, @code{groff}
8914 must be called directly:
8917 groff -Tdvi -mec -man groff_char.7 > groff_char.dvi
8920 @cindex composite glyph names
8921 @cindex glyph names, composite
8922 @cindex groff glyph list (GGL)
8923 @cindex GGL (groff glyph list)
8924 @cindex adobe glyph list (AGL)
8925 @cindex AGL (adobe glyph list)
8926 Glyph names not listed in groff_char(7) are derived algorithmically,
8927 using a simplified version of the Adobe Glyph List (AGL) algorithm
8928 which is described in
8929 @uref{http://partners.adobe.com@//asn@//tech@//type@//unicodegn.jsp}.
8930 The (frozen) set of glyph names which can't be derived algorithmically
8931 is called @dfn{groff glyph list (GGL)}.
8935 A glyph for Unicode character U+@var{XXXX}[@var{X}[@var{X}]] which is
8936 not a composite character will be named
8937 @code{u@var{XXXX}@r{[}@var{X}@r{[}@var{X}@r{]]}}. @var{X} must be an
8938 uppercase hexadecimal digit. Examples: @code{u1234}, @code{u008E},
8939 @code{u12DB8}. The largest Unicode value is 0x10FFFF. There must be at
8940 least four @code{X} digits; if necessary, add leading zeroes (after the
8941 @samp{u}). No zero padding is allowed for character codes greater than
8942 0xFFFF. Surrogates (i.e., Unicode values greater than 0xFFFF
8943 represented with character codes from the surrogate area U+D800-U+DFFF)
8944 are not allowed too.
8947 A glyph representing more than a single input character will be named
8950 @samp{u} @var{component1} @samp{_} @var{component2} @samp{_} @var{component3} @dots{}
8954 Example: @code{u0045_0302_0301}.
8956 For simplicity, all Unicode characters which are composites must be
8957 decomposed maximally (this is normalization form@tie{}D in the Unicode
8958 standard); for example, @code{u00CA_0301} is not a valid glyph name
8959 since U+00CA (@sc{latin capital letter e with circumflex}) can be
8960 further decomposed into U+0045 (@sc{latin capital letter e}) and U+0302
8961 (@sc{combining circumflex accent}). @code{u0045_0302_0301} is thus the
8962 glyph name for U+1EBE, @sc{latin capital letter e with circumflex and
8966 groff maintains a table to decompose all algorithmically derived glyph
8967 names which are composites itself. For example, @code{u0100} (@sc{latin
8968 letter a with macron}) will be automatically decomposed into
8969 @code{u0041_0304}. Additionally, a glyph name of the GGL is preferred
8970 to an algorithmically derived glyph name; groff also automatically does
8971 the mapping. Example: The glyph @code{u0045_0302} will be mapped to
8975 glyph names of the GGL can't be used in composite glyph names; for
8976 example, @code{^E_u0301} is invalid.
8979 @DefescList {\\, @Lparen{}, nm, }
8980 @DefescItem {\\, @Lbrack{}, name, @Rbrack{}}
8981 @DefescListEnd {\\, @Lbrack{}, component1 component2 @dots{}, @Rbrack{}}
8982 Insert a symbol @var{name} (two-character name @var{nm}) or a composite
8983 glyph with component glyphs @var{component1}, @var{component2},
8984 @enddots{} There is no special syntax for one-character names -- the
8985 natural form @samp{\@var{n}} would collide with escapes.@footnote{Note
8986 that a one-character symbol is not the same as an input character, i.e.,
8987 the character @code{a} is not the same as @code{\[a]}. By default,
8988 @code{groff} defines only a single one-character symbol, @code{\[-]}; it
8989 is usually accessed as @code{\-}. On the other hand, @code{gtroff} has
8990 the special feature that @code{\[char@var{XXX}]} is the same as the
8991 input character with character code @var{XXX}. For example,
8992 @code{\[char97]} is identical to the letter @code{a} if @acronym{ASCII}
8993 encoding is active.}
8995 If @var{name} is undefined, a warning of type @samp{char} is generated,
8996 and the escape is ignored. @xref{Debugging}, for information about
8999 groff resolves @code{\[...]} with more than a single component as
9004 Any component which is found in the GGL will be converted to the
9005 @code{u@var{XXXX}} form.
9008 Any component @code{u@var{XXXX}} which is found in the list of
9009 decomposable glyphs will be decomposed.
9012 The resulting elements are then concatenated with @samp{_} inbetween,
9013 dropping the leading @samp{u} in all elements but the first.
9016 No check for the existence of any component (similar to @code{tr}
9017 request) will be done.
9023 @samp{A} maps to @code{u0041}, @samp{ho} maps to @code{u02DB}, thus the
9024 final glyph name would be @code{u0041_02DB}. Note this is not the
9025 expected result: The ogonek glyph @samp{ho} is a spacing ogonek, but for
9026 a proper composite a non-spacing ogonek (U+0328) is necessary. Looking
9027 into the file @file{composite.tmac} one can find @w{@samp{.composite ho
9028 u0328}} which changes the mapping of @samp{ho} while a composite glyph
9029 name is constructed, causing the final glyph name to be
9036 @samp{^E} maps to @code{u0045_0302}, thus the final glyph name is
9037 @code{u0045_0302_0301} in all forms (assuming proper calls of the
9038 @code{composite} request).
9041 It is not possible to define glyphs with names like @w{@samp{A ho}}
9042 within a groff font file. This is not really a limitation; instead, you
9043 have to define @code{u0041_0328}.
9046 @Defesc {\\C, ', xxx, '}
9047 @cindex named character (@code{\C})
9048 @cindex character, named (@code{\C})
9049 Typeset the glyph named @var{xxx}.@footnote{@code{\C} is actually a
9050 misnomer since it accesses an output glyph.} Normally it is more
9051 convenient to use @code{\[@var{xxx}]}, but @code{\C} has the advantage
9052 that it is compatible with newer versions of @acronym{AT&T}
9053 @code{troff} and is available in compatibility mode.
9056 @Defreq {composite, from to}
9057 @pindex composite.tmac
9058 Map glyph name @var{from} to glyph name @var{to} if it is used in
9059 @code{\[...]} with more than one component. See above for examples.
9061 This mapping is based on glyph names only; no check for the existence of
9062 either glyph is done.
9064 A set of default mappings for many accents can be found in the file
9065 @file{composite.tmac} which is loaded at start-up.
9068 @Defesc {\\N, ', n, '}
9069 @cindex numbered glyph (@code{\N})
9070 @cindex glyph, numbered (@code{\N})
9071 @cindex @code{char} request, used with @code{\N}
9073 Typeset the glyph with code@tie{}@var{n} in the current font
9074 (@code{n}@tie{}is @strong{not} the input character code). The
9075 number @var{n}@tie{}can be any non-negative decimal integer. Most devices
9076 only have glyphs with codes between 0 and@tie{}255; the Unicode
9077 output device uses codes in the range 0--65535. If the current
9078 font does not contain a glyph with that code, special fonts are
9079 @emph{not} searched. The @code{\N} escape sequence can be
9080 conveniently used in conjunction with the @code{char} request:
9083 .char \[phone] \f[ZD]\N'37'
9088 @cindex unnamed glyphs
9089 @cindex glyphs, unnamed
9090 The code of each glyph is given in the fourth column in the font
9091 description file after the @code{charset} command. It is possible to
9092 include unnamed glyphs in the font description file by using a
9093 name of @samp{---}; the @code{\N} escape sequence is the only way to
9096 No kerning is applied to glyphs accessed with @code{\N}.
9099 Some escape sequences directly map onto special glyphs.
9102 This is a backslash followed by the apostrophe character, @acronym{ASCII}
9103 character @code{0x27} (@acronym{EBCDIC} character @code{0x7D}). The same
9104 as @code{\[aa]}, the acute accent.
9108 This is a backslash followed by @acronym{ASCII} character @code{0x60}
9109 (@acronym{EBCDIC} character @code{0x79} usually). The same as
9110 @code{\[ga]}, the grave accent.
9114 This is the same as @code{\[-]}, the minus sign in the current font.
9117 @Defreq {cflags, n c1 c2 @dots{}}
9118 @cindex glyph properties (@code{cflags})
9119 @cindex character properties (@code{cflags})
9120 @cindex properties of glyphs (@code{cflags})
9121 @cindex properties of characters (@code{cflags})
9122 Input characters and symbols have certain properties associated
9123 with it.@footnote{Note that the output glyphs themselves don't have
9124 such properties. For @code{gtroff}, a glyph is a numbered box with
9125 a given width, depth, and height, nothing else. All manipulations
9126 with the @code{cflags} request work on the input level.} These
9127 properties can be modified with the @code{cflags} request. The
9128 first argument is the sum of the desired flags and the remaining
9129 arguments are the characters or symbols to have those properties.
9130 It is possible to omit the spaces between the characters or symbols.
9134 @cindex end-of-sentence characters
9135 @cindex characters, end-of-sentence
9136 The character ends sentences (initially characters @samp{.?!} have this
9140 @cindex hyphenating characters
9141 @cindex characters, hyphenation
9142 Lines can be broken before the character (initially no characters have
9146 @cindex @code{hy} glyph, and @code{cflags}
9147 @cindex @code{em} glyph, and @code{cflags}
9148 Lines can be broken after the character (initially the character
9149 @samp{-} and the symbols @samp{\[hy]} and @samp{\[em]} have this property).
9152 @cindex overlapping characters
9153 @cindex characters, overlapping
9154 @cindex @code{ul} glyph, and @code{cflags}
9155 @cindex @code{rn} glyph, and @code{cflags}
9156 @cindex @code{ru} glyph, and @code{cflags}
9157 @cindex @code{radicalex} glyph, and @code{cflags}
9158 @cindex @code{sqrtex} glyph, and @code{cflags}
9159 The character overlaps horizontally if used as a horizontal line building
9160 element. Initially the symbols @samp{\[ul]}, @samp{\[rn]}, @samp{\[ru]},
9161 @samp{\[radicalex]}, and @samp{\[sqrtex]} have this property.
9164 @cindex @code{br} glyph, and @code{cflags}
9165 The character overlaps vertically if used as vertical line building element.
9166 Initially symbol @samp{\[br]} has this property.
9169 @cindex transparent characters
9170 @cindex character, transparent
9171 @cindex @code{"}, at end of sentence
9172 @cindex @code{'}, at end of sentence
9173 @cindex @code{)}, at end of sentence
9174 @cindex @code{]}, at end of sentence
9175 @cindex @code{*}, at end of sentence
9176 @cindex @code{dg} glyph, at end of sentence
9177 @cindex @code{rq} glyph, at end of sentence
9178 An end-of-sentence character followed by any number of characters with
9179 this property is treated as the end of a sentence if followed by a
9180 newline or two spaces; in other words the character is
9181 @dfn{transparent} for the purposes of end-of-sentence recognition --
9182 this is the same as having a zero space factor in @TeX{} (initially
9183 characters @samp{"')]*} and the symbols @samp{\[dg]} and @samp{\[rq]} have
9188 @DefreqList {char, g [@Var{string}]}
9189 @DefreqItem {fchar, g [@Var{string}]}
9190 @DefreqItem {fschar, f g [@Var{string}]}
9191 @DefreqListEnd {schar, g [@Var{string}]}
9192 @cindex defining character (@code{char})
9193 @cindex defining fallback character (@code{fchar}, @code{fschar}, @code{schar})
9194 @cindex character, defining (@code{char})
9195 @cindex character, defining fallback (@code{fchar}, @code{fschar}, @code{schar})
9196 @cindex fallback character, defining (@code{fchar}, @code{fschar}, @code{schar})
9197 @cindex creating new characters (@code{char})
9198 @cindex defining symbol (@code{char})
9199 @cindex symbol, defining (@code{char})
9200 @cindex defining glyph (@code{char})
9201 @cindex glyph, defining (@code{char})
9202 @cindex escape character, while defining glyph
9203 @cindex character, escape, while defining glyph
9204 @cindex @code{tr} request, and glyph definitions
9205 @cindex @code{cp} request, and glyph definitions
9206 @cindex @code{rc} request, and glyph definitions
9207 @cindex @code{lc} request, and glyph definitions
9208 @cindex @code{\l}, and glyph definitions
9209 @cindex @code{\L}, and glyph definitions
9210 @cindex @code{\&}, and glyph definitions
9211 @cindex @code{\e}, and glyph definitions
9212 @cindex @code{hcode} request, and glyph definitions
9213 Define a new glyph@tie{}@var{g} to be @var{string} (which can be
9214 empty).@footnote{@code{char} is a misnomer since an output glyph is
9215 defined.} Every time glyph@tie{}@var{g} needs to be printed,
9216 @var{string} is processed in a temporary environment and the result is
9217 wrapped up into a single object. Compatibility mode is turned off and
9218 the escape character is set to @samp{\} while @var{string} is being
9219 processed. Any emboldening, constant spacing or track kerning is
9220 applied to this object rather than to individual characters in
9223 A glyph defined by these requests can be used just
9224 like a normal glyph provided by the output device. In particular,
9225 other characters can be translated to it with the @code{tr} or
9226 @code{trin} requests; it can be made the leader character by the
9227 @code{lc} request; repeated patterns can be drawn with the glyph
9228 using the @code{\l} and @code{\L} escape sequences; words containing
9229 the glyph can be hyphenated correctly if the @code{hcode} request
9230 is used to give the glyph's symbol a hyphenation code.
9232 There is a special anti-recursion feature: Use of @code{g} within
9233 the glyph's definition is handled like normal characters and symbols
9234 not defined with @code{char}.
9236 Note that the @code{tr} and @code{trin} requests take precedence if
9237 @code{char} accesses the same symbol.
9251 The @code{fchar} request defines a fallback glyph:
9252 @code{gtroff} only checks for glyphs defined with @code{fchar}
9253 if it cannot find the glyph in the current font.
9254 @code{gtroff} carries out this test before checking special fonts.
9256 @code{fschar} defines a fallback glyph for font@tie{}@var{f}: @code{gtroff}
9257 checks for glyphs defined with @code{fschar} after the list of fonts
9258 declared as font-specific special fonts with the @code{fspecial} request,
9259 but before the list of fonts declared as global special fonts with the
9260 @code{special} request.
9262 Finally, the @code{schar} request defines a global fallback glyph:
9263 @code{gtroff} checks for glyphs defined with @code{schar} after the list
9264 of fonts declared as global special fonts with the @code{special} request,
9265 but before the already mounted special fonts.
9267 @xref{Using Symbols}, for a detailed description of the glyph
9268 searching mechanism in @code{gtroff}.
9271 @DefreqList {rchar, c1 c2 @dots{}}
9272 @DefreqListEnd {rfschar, f c1 c2 @dots{}}
9273 @cindex removing glyph definition (@code{rchar}, @code{rfschar})
9274 @cindex glyph, removing definition (@code{rchar}, @code{rfschar})
9275 @cindex fallback glyph, removing definition (@code{rchar}, @code{rfschar})
9276 Remove the definitions of glyphs @var{c1}, @var{c2},@tie{}@enddots{}
9277 This undoes the effect of a @code{char}, @code{fchar}, or
9278 @code{schar} request.
9280 It is possible to omit the whitespace between arguments.
9282 The request @code{rfschar} removes glyph definitions defined with
9283 @code{fschar} for glyph@tie{}f.
9286 @xref{Special Characters}.
9288 @c ---------------------------------------------------------------------
9290 @node Special Fonts, Artificial Fonts, Using Symbols, Fonts and Symbols
9291 @subsection Special Fonts
9292 @cindex special fonts
9293 @cindex fonts, special
9295 Special fonts are those that @code{gtroff} searches
9296 when it cannot find the requested glyph in the current font.
9297 The Symbol font is usually a special font.
9299 @code{gtroff} provides the following two requests to add more special
9300 fonts. @xref{Using Symbols}, for a detailed description of the glyph
9301 searching mechanism in @code{gtroff}.
9303 Usually, only non-TTY devices have special fonts.
9305 @DefreqList {special, [@Var{s1} @Var{s2} @dots{}]}
9306 @DefreqListEnd {fspecial, f [@Var{s1} @Var{s2} @dots{}]}
9309 Use the @code{special} request to define special fonts. Initially, this
9312 Use the @code{fspecial} request to designate special fonts only when
9313 font@tie{}@var{f} is active. Initially, this list is empty.
9315 Previous calls to @code{special} or @code{fspecial} are overwritten;
9316 without arguments, the particular list of special fonts is set to empty.
9317 Special fonts are searched in the order they appear as arguments.
9319 All fonts which appear in a call to @code{special} or @code{fspecial} are
9322 @xref{Using Symbols}, for the exact search order of glyphs.
9325 @c ---------------------------------------------------------------------
9327 @node Artificial Fonts, Ligatures and Kerning, Special Fonts, Fonts and Symbols
9328 @subsection Artificial Fonts
9329 @cindex artificial fonts
9330 @cindex fonts, artificial
9332 There are a number of requests and escapes for artificially creating
9333 fonts. These are largely vestiges of the days when output devices
9334 did not have a wide variety of fonts, and when @code{nroff} and
9335 @code{troff} were separate programs. Most of them are no longer
9336 necessary in GNU @code{troff}. Nevertheless, they are supported.
9338 @DefescList {\\H, ', height, '}
9339 @DefescItem {\\H, ', @t{+}height, '}
9340 @DefescItem {\\H, ', @t{-}height, '}
9341 @DefregListEnd {.height}
9342 @cindex changing the font height (@code{\H})
9343 @cindex font height, changing (@code{\H})
9344 @cindex height, font, changing (@code{\H})
9345 Change (increment, decrement) the height of the current font, but not
9346 the width. If @var{height} is zero, restore the original height.
9347 Default scaling indicator is @samp{z}.
9349 The read-only number register @code{.height} contains the font height as
9352 Currently, only the @option{-Tps} device supports this feature.
9354 Note that @code{\H} doesn't produce an input token in @code{gtroff}.
9355 As a consequence, it can be used in requests like @code{mc} (which
9356 expects a single character as an argument) to change the font on
9363 In compatibility mode, @code{gtroff} behaves differently: If an
9364 increment or decrement is used, it is always taken relative to the
9365 current point size and not relative to the previously selected font
9370 \H'+5'test \H'+5'test
9374 prints the word @samp{test} twice with the same font height (five
9375 points larger than the current font size).
9378 @DefescList {\\S, ', slant, '}
9379 @DefregListEnd {.slant}
9380 @cindex changing the font slant (@code{\S})
9381 @cindex font slant, changing (@code{\S})
9382 @cindex slant, font, changing (@code{\S})
9383 Slant the current font by @var{slant} degrees. Positive values slant
9384 to the right. Only integer values are possible.
9386 The read-only number register @code{.slant} contains the font slant as
9389 Currently, only the @option{-Tps} device supports this feature.
9391 Note that @code{\S} doesn't produce an input token in @code{gtroff}.
9392 As a consequence, it can be used in requests like @code{mc} (which
9393 expects a single character as an argument) to change the font on
9400 This request is incorrectly documented in the original @acronym{UNIX}
9401 troff manual; the slant is always set to an absolute value.
9404 @Defreq {ul, [@Var{lines}]}
9405 @cindex underlining (@code{ul})
9406 The @code{ul} request normally underlines subsequent lines if a TTY
9407 output device is used. Otherwise, the lines are printed in italics
9408 (only the term `underlined' is used in the following). The single
9409 argument is the number of input lines to be underlined; with no
9410 argument, the next line is underlined. If @var{lines} is zero or
9411 negative, stop the effects of @code{ul} (if it was active). Requests
9412 and empty lines do not count for computing the number of underlined
9413 input lines, even if they produce some output like @code{tl}. Lines
9414 inserted by macros (e.g.@: invoked by a trap) do count.
9416 At the beginning of @code{ul}, the current font is stored and the
9417 underline font is activated. Within the span of a @code{ul} request,
9418 it is possible to change fonts, but after the last line affected by
9419 @code{ul} the saved font is restored.
9421 This number of lines still to be underlined is associated with the
9422 current environment (@pxref{Environments}). The underline font can be
9423 changed with the @code{uf} request.
9425 @c XXX @xref should be changed to grotty
9427 @c @xref{Troff and Nroff Mode}, for a discussion how underlining is
9428 @c implemented in for TTY output devices, and which problems can arise.
9430 The @code{ul} request does not underline spaces.
9433 @Defreq {cu, [@Var{lines}]}
9434 @cindex continuous underlining (@code{cu})
9435 @cindex underlining, continuous (@code{cu})
9436 The @code{cu} request is similar to @code{ul} but underlines spaces as
9437 well (if a TTY output device is used).
9441 @cindex underline font (@code{uf})
9442 @cindex font for underlining (@code{uf})
9443 Set the underline font (globally) used by @code{ul} and @code{cu}. By
9444 default, this is the font at position@tie{}2. @var{font} can be either
9445 a non-negative font position or the name of a font.
9448 @DefreqList {bd, font [@Var{offset}]}
9449 @DefreqItem {bd, font1 font2 [@Var{offset}]}
9451 @cindex imitating bold face (@code{bd})
9452 @cindex bold face, imitating (@code{bd})
9453 Artificially create a bold font by printing each glyph twice,
9456 Two syntax forms are available.
9460 Imitate a bold font unconditionally. The first argument specifies the
9461 font to embolden, and the second is the number of basic units, minus
9462 one, by which the two glyphs are offset. If the second argument is
9463 missing, emboldening is turned off.
9465 @var{font} can be either a non-negative font position or the name of a
9468 @var{offset} is available in the @code{.b} read-only register if a
9469 special font is active; in the @code{bd} request, its default unit is
9472 @cindex @code{fspecial} request, and imitating bold
9474 @cindex embolding of special fonts
9475 @cindex special fonts, emboldening
9477 Imitate a bold form conditionally. Embolden @var{font1} by
9478 @var{offset} only if font @var{font2} is the current font. This
9479 command can be issued repeatedly to set up different emboldening
9480 values for different current fonts. If the second argument is
9481 missing, emboldening is turned off for this particular current font.
9483 This affects special fonts only (either set up with the @code{special}
9484 command in font files or with the @code{fspecial} request).
9488 @Defreq {cs, font [@Var{width} [@Var{em-size}]]}
9489 @cindex constant glyph space mode (@code{cs})
9490 @cindex mode for constant glyph space (@code{cs})
9491 @cindex glyph, constant space
9492 @cindex @code{ps} request, and constant glyph space mode
9493 Switch to and from @dfn{constant glyph space mode}. If activated, the
9494 width of every glyph is @math{@var{width}/36} ems. The em size is
9495 given absolutely by @var{em-size}; if this argument is missing, the em
9496 value is taken from the current font size (as set with the @code{ps}
9497 request) when the font is effectively in use. Without second and
9498 third argument, constant glyph space mode is deactivated.
9500 Default scaling indicator for @var{em-size} is @samp{z}; @var{width} is
9504 @c ---------------------------------------------------------------------
9506 @node Ligatures and Kerning, , Artificial Fonts, Fonts and Symbols
9507 @subsection Ligatures and Kerning
9508 @cindex ligatures and kerning
9509 @cindex kerning and ligatures
9511 Ligatures are groups of characters that are run together, i.e, producing
9512 a single glyph. For example, the letters `f' and `i' can form a
9513 ligature `fi' as in the word `file'. This produces a cleaner look
9514 (albeit subtle) to the printed output. Usually, ligatures are not
9515 available in fonts for TTY output devices.
9517 Most @sc{PostScript} fonts support the fi and fl ligatures. The C/A/T
9518 typesetter that was the target of @acronym{AT&T} @code{troff} also
9519 supported `ff', `ffi', and `ffl' ligatures. Advanced typesetters or
9520 `expert' fonts may include ligatures for `ft' and `ct', although GNU
9521 @code{troff} does not support these (yet).
9523 Only the current font is checked for ligatures and kerns; neither special
9524 fonts nor entities defined with the @code{char} request (and its siblings)
9525 are taken into account.
9527 @DefreqList {lg, [@Var{flag}]}
9528 @DefregListEnd {.lg}
9529 @cindex activating ligatures (@code{lg})
9530 @cindex ligatures, activating (@code{lg})
9531 @cindex ligatures enabled register (@code{.lg})
9532 Switch the ligature mechanism on or off; if the parameter is non-zero
9533 or missing, ligatures are enabled, otherwise disabled. Default is on.
9534 The current ligature mode can be found in the read-only number register
9535 @code{.lg} (set to 1 or@tie{}2 if ligatures are enabled, 0@tie{}otherwise).
9537 Setting the ligature mode to@tie{}2 enables the two-character ligatures
9538 (fi, fl, and ff) and disables the three-character ligatures (ffi and
9542 @dfn{Pairwise kerning} is another subtle typesetting mechanism that
9543 modifies the distance between a glyph pair to improve readability.
9544 In most cases (but not always) the distance is decreased.
9546 For example, compare the combination of the letters `V' and `A'. With
9547 kerning, `VA' is printed. Without kerning it appears as `V@w{}A'.
9549 Typewriter-like fonts and fonts for terminals where all glyphs
9550 have the same width don't use kerning.
9552 @DefreqList {kern, [@Var{flag}]}
9553 @DefregListEnd {.kern}
9554 @cindex activating kerning (@code{kern})
9555 @cindex kerning, activating (@code{kern})
9556 @cindex kerning enabled register (@code{.kern})
9557 Switch kerning on or off. If the parameter is non-zero or missing,
9558 enable pairwise kerning, otherwise disable it. The read-only number
9559 register @code{.kern} is set to@tie{}1 if pairwise kerning is enabled,
9562 @cindex zero width space character (@code{\&})
9563 @cindex character, zero width space (@code{\&})
9564 @cindex space character, zero width (@code{\&})
9565 If the font description file contains pairwise kerning information,
9566 glyphs from that font are kerned. Kerning between two glyphs
9567 can be inhibited by placing @code{\&} between them: @samp{V\&A}.
9569 @xref{Font File Format}.
9572 @cindex track kerning
9573 @cindex kerning, track
9574 @dfn{Track kerning} expands or reduces the space between glyphs.
9575 This can be handy, for example, if you need to squeeze a long word
9576 onto a single line or spread some text to fill a narrow column. It
9577 must be used with great care since it is usually considered bad
9578 typography if the reader notices the effect.
9580 @Defreq {tkf, f s1 n1 s2 n2}
9581 @cindex activating track kerning (@code{tkf})
9582 @cindex track kerning, activating (@code{tkf})
9583 Enable track kerning for font@tie{}@var{f}. If the current font
9584 is@tie{}@var{f} the width of every glyph is increased by an amount
9585 between @var{n1} and @var{n2} (@var{n1}, @var{n2} can be negative); if
9586 the current point size is less than or equal to @var{s1} the width is
9587 increased by @var{n1}; if it is greater than or equal to @var{s2} the
9588 width is increased by @var{n2}; if the point size is greater than or
9589 equal to @var{s1} and less than or equal to @var{s2} the increase in
9590 width is a linear function of the point size.
9592 The default scaling indicator is @samp{z} for @var{s1} and @var{s2},
9593 @samp{p} for @var{n1} and @var{n2}.
9595 Note that the track kerning amount is added even to the rightmost glyph
9596 in a line; for large values it is thus recommended to increase the line
9597 length by the same amount to compensate it.
9600 Sometimes, when typesetting letters of different fonts, more or less
9601 space at such boundaries are needed. There are two escapes to help
9605 @cindex italic correction (@code{\/})
9606 @cindex correction, italic (@code{\/})
9607 @cindex correction between italic and roman glyph (@code{\/}, @code{\,})
9608 @cindex roman glyph, correction after italic glyph (@code{\/})
9609 @cindex italic glyph, correction before roman glyph (@code{\/})
9610 @cindex glyph, italic correction (@code{\/})
9611 Increase the width of the preceding glyph so that the spacing
9612 between that glyph and the following glyph is correct if the
9613 following glyph is a roman glyph. For example, if an
9614 italic@tie{}@code{f} is immediately followed by a roman right
9615 parenthesis, then in many fonts the top right portion of the@tie{}@code{f}
9616 overlaps the top left of the right parenthesis. Use this escape
9617 sequence whenever an italic glyph is immediately followed by a
9618 roman glyph without any intervening space. This small amount of
9619 space is also called @dfn{italic correction}.
9622 @c can't use @Example...@endExample here
9626 @result{} {@it f}@r{)}
9628 @result{} @i{f}@r{)}
9634 @Defesc {\\\,, , , }
9635 @cindex left italic correction (@code{\,})
9636 @cindex correction, left italic (@code{\,})
9637 @cindex glyph, left italic correction (@code{\,})
9638 @cindex roman glyph, correction before italic glyph (@code{\,})
9639 @cindex italic glyph, correction after roman glyph (@code{\,})
9640 Modify the spacing of the following glyph so that the spacing
9641 between that glyph and the preceding glyph is correct if the
9642 preceding glyph is a roman glyph. Use this escape sequence
9643 whenever a roman glyph is immediately followed by an italic
9644 glyph without any intervening space. In analogy to above, this
9645 space could be called @dfn{left italic correction}, but this term
9649 @c can't use @Example...@endExample here
9653 @result{} @r{q}@i{f}
9655 @result{} @r{q}@math{@ptexcomma}@i{f}
9662 Insert a zero-width character, which is invisible. Its intended use
9663 is to stop interaction of a character with its surrounding.
9667 It prevents the insertion of extra space after an end-of-sentence
9673 @result{} Test. Test.
9676 @result{} Test. Test.
9680 It prevents interpretation of a control character at the beginning of
9685 @result{} warning: `Test' not defined
9691 It prevents kerning between two glyphs.
9694 @c can't use @Example...@endExample here
9700 @result{} @r{V@w{}A}
9706 It is needed to map an arbitrary character to nothing in the @code{tr}
9707 request (@pxref{Character Translations}).
9712 This escape is similar to @code{\&} except that it behaves like a
9713 character declared with the @code{cflags} request to be transparent
9714 for the purposes of an end-of-sentence character.
9716 Its main usage is in macro definitions to protect against arguments
9717 starting with a control character.
9729 @result{}This is a test.' This is a test.
9733 @result{}This is a test.' This is a test.
9738 @c =====================================================================
9740 @node Sizes, Strings, Fonts and Symbols, gtroff Reference
9746 @cindex size of type
9747 @cindex vertical spacing
9748 @cindex spacing, vertical
9749 @code{gtroff} uses two dimensions with each line of text, type size
9750 and vertical spacing. The @dfn{type size} is approximately the height
9751 of the tallest glyph.@footnote{This is usually the parenthesis.
9752 Note that in most cases the real dimensions of the glyphs in a font
9753 are @emph{not} related to its type size! For example, the standard
9754 @sc{PostScript} font families `Times Roman', `Helvetica', and
9755 `Courier' can't be used together at 10@dmn{pt}; to get acceptable
9756 output, the size of `Helvetica' has to be reduced by one point, and
9757 the size of `Courier' must be increased by one point.} @dfn{Vertical
9758 spacing} is the amount of space @code{gtroff} allows for a line of
9759 text; normally, this is about 20%@tie{}larger than the current type
9760 size. Ratios smaller than this can result in hard-to-read text;
9761 larger than this, it spreads the text out more vertically (useful for
9762 term papers). By default, @code{gtroff} uses 10@tie{}point type on
9763 12@tie{}point spacing.
9766 The difference between type size and vertical spacing is known, by
9767 typesetters, as @dfn{leading} (this is pronounced `ledding').
9770 * Changing Type Sizes::
9771 * Fractional Type Sizes::
9774 @c ---------------------------------------------------------------------
9776 @node Changing Type Sizes, Fractional Type Sizes, Sizes, Sizes
9777 @subsection Changing Type Sizes
9779 @DefreqList {ps, [@Var{size}]}
9780 @DefreqItem {ps, @t{+}@Var{size}}
9781 @DefreqItem {ps, @t{-}@Var{size}}
9782 @DefescItem {\\s, , size, }
9784 @cindex changing type sizes (@code{ps}, @code{\s})
9785 @cindex type sizes, changing (@code{ps}, @code{\s})
9786 @cindex point sizes, changing (@code{ps}, @code{\s})
9787 Use the @code{ps} request or the @code{\s} escape to change (increase,
9788 decrease) the type size (in points). Specify @var{size} as either an
9789 absolute point size, or as a relative change from the current size.
9790 The size@tie{}0, or no argument, goes back to the previous size.
9792 Default scaling indicator of @code{size} is @samp{z}. If @code{size}
9793 is zero or negative, it is set to 1@dmn{u}.
9795 @cindex type size registers (@code{.s}, @code{.ps})
9796 @cindex point size registers (@code{.s}, @code{.ps})
9797 The read-only number register @code{.s} returns the point size in
9798 points as a decimal fraction. This is a string. To get the point
9799 size in scaled points, use the @code{.ps} register instead.
9801 @code{.s} is associated with the current environment
9802 (@pxref{Environments}).
9809 wink, wink, \s+2nudge, nudge,\s+8 say no more!
9813 The @code{\s} escape may be called in a variety of ways. Much like
9814 other escapes there must be a way to determine where the argument ends
9815 and the text begins. Any of the following forms are valid:
9819 Set the point size to @var{n}@tie{}points. @var{n}@tie{}must be either
9820 0 or in the range 4 to@tie{}39.
9824 Increase or decrease the point size by @var{n}@tie{}points.
9825 @var{n}@tie{}must be exactly one digit.
9828 Set the point size to @var{nn}@tie{}points. @var{nn} must be exactly
9835 Increase or decrease the point size by @var{nn}@tie{}points. @var{nn}
9836 must be exactly two digits.
9839 Note that @code{\s} doesn't produce an input token in @code{gtroff}.
9840 As a consequence, it can be used in requests like @code{mc} (which
9841 expects a single character as an argument) to change the font on
9848 @xref{Fractional Type Sizes}, for yet another syntactical form of
9849 using the @code{\s} escape.
9852 @Defreq {sizes, s1 s2 @dots{} sn [0]}
9853 Some devices may only have certain permissible sizes, in which case
9854 @code{gtroff} rounds to the nearest permissible size.
9855 The @file{DESC} file specifies which sizes are permissible for the device.
9857 Use the @code{sizes} request to change the permissible sizes
9858 for the current output device.
9859 Arguments are in scaled points;
9860 the @code{sizescale} line in the
9861 @file{DESC} file for the output device
9862 provides the scaling factor.
9863 For example, if the scaling factor is 1000,
9864 then the value 12000 is 12@tie{}points.
9866 Each argument can be a single point size (such as @samp{12000}),
9867 or a range of sizes (such as @samp{4000-72000}).
9868 You can optionally end the list with a zero.
9871 @DefreqList {vs, [@Var{space}]}
9872 @DefreqItem {vs, @t{+}@Var{space}}
9873 @DefreqItem {vs, @t{-}@Var{space}}
9875 @cindex changing vertical line spacing (@code{vs})
9876 @cindex vertical line spacing, changing (@code{vs})
9877 @cindex vertical line spacing register (@code{.v})
9878 Change (increase, decrease) the vertical spacing by @var{space}. The
9879 default scaling indicator is @samp{p}.
9881 If @code{vs} is called without an argument, the vertical spacing is
9882 reset to the previous value before the last call to @code{vs}.
9884 @cindex @code{.V} register, and @code{vs}
9885 @code{gtroff} creates a warning of type @samp{range} if @var{space} is
9886 negative; the vertical spacing is then set to smallest positive value,
9887 the vertical resolution (as given in the @code{.V} register).
9889 Note that @w{@samp{.vs 0}} isn't saved in a diversion since it doesn't
9890 result in a vertical motion. You explicitly have to repeat this command
9891 before inserting the diversion.
9893 The read-only number register @code{.v} contains the current vertical
9894 spacing; it is associated with the current environment
9895 (@pxref{Environments}).
9898 @cindex vertical line spacing, effective value
9899 The effective vertical line spacing consists of four components. Breaking
9900 a line causes the following actions (in the given order).
9904 @cindex extra pre-vertical line space (@code{\x})
9905 @cindex line space, extra pre-vertical (@code{\x})
9906 Move the current point vertically by the @dfn{extra pre-vertical line
9907 space}. This is the minimum value of all @code{\x} escapes with a
9908 negative argument in the current output line.
9911 Move the current point vertically by the vertical line spacing as set with
9912 the @code{vs} request.
9915 Output the current line.
9918 @cindex extra post-vertical line space (@code{\x})
9919 @cindex line space, extra post-vertical (@code{\x})
9920 Move the current point vertically by the @dfn{extra post-vertical line
9921 space}. This is the maximum value of all @code{\x} escapes with a
9922 positive argument in the line which has just been output.
9925 @cindex post-vertical line spacing
9926 @cindex line spacing, post-vertical (@code{pvs})
9927 Move the current point vertically by the @dfn{post-vertical line spacing}
9928 as set with the @code{pvs} request.
9931 @cindex double-spacing (@code{vs}, @code{pvs})
9932 It is usually better to use @code{vs} or @code{pvs} instead of @code{ls}
9933 to produce double-spaced documents: @code{vs} and @code{pvs} have a finer
9934 granularity for the inserted vertical space compared to @code{ls};
9935 furthermore, certain preprocessors assume single-spacing.
9937 @xref{Manipulating Spacing}, for more details on the @code{\x} escape
9938 and the @code{ls} request.
9940 @DefreqList {pvs, [@Var{space}]}
9941 @DefreqItem {pvs, @t{+}@Var{space}}
9942 @DefreqItem {pvs, @t{-}@Var{space}}
9943 @DefregListEnd {.pvs}
9944 @cindex @code{ls} request, alternative to (@code{pvs})
9945 @cindex post-vertical line spacing, changing (@code{pvs})
9946 @cindex post-vertical line spacing register (@code{.pvs})
9947 Change (increase, decrease) the post-vertical spacing by
9948 @var{space}. The default scaling indicator is @samp{p}.
9950 If @code{pvs} is called without an argument, the post-vertical spacing is
9951 reset to the previous value before the last call to @code{pvs}.
9953 @code{gtroff} creates a warning of type @samp{range} if @var{space} is
9954 zero or negative; the vertical spacing is then set to zero.
9956 The read-only number register @code{.pvs} contains the current
9957 post-vertical spacing; it is associated with the current environment
9958 (@pxref{Environments}).
9961 @c ---------------------------------------------------------------------
9963 @node Fractional Type Sizes, , Changing Type Sizes, Sizes
9964 @subsection Fractional Type Sizes
9965 @cindex fractional type sizes
9966 @cindex fractional point sizes
9967 @cindex type sizes, fractional
9968 @cindex point sizes, fractional
9969 @cindex sizes, fractional
9971 @cindex @code{s} unit
9972 @cindex unit, @code{s}
9973 @cindex @code{z} unit
9974 @cindex unit, @code{z}
9975 @cindex @code{ps} request, with fractional type sizes
9976 @cindex @code{cs} request, with fractional type sizes
9977 @cindex @code{tkf} request, with fractional type sizes
9978 @cindex @code{\H}, with fractional type sizes
9979 @cindex @code{\s}, with fractional type sizes
9980 A @dfn{scaled point} is equal to @math{1/@var{sizescale}} points,
9981 where @var{sizescale} is specified in the @file{DESC} file (1@tie{}by
9982 default). There is a new scale indicator @samp{z} which has the
9983 effect of multiplying by @var{sizescale}. Requests and escape
9984 sequences in @code{gtroff} interpret arguments that represent a point
9985 size as being in units of scaled points, but they evaluate each such
9986 argument using a default scale indicator of @samp{z}. Arguments
9987 treated in this way are the argument to the @code{ps} request, the
9988 third argument to the @code{cs} request, the second and fourth
9989 arguments to the @code{tkf} request, the argument to the @code{\H}
9990 escape sequence, and those variants of the @code{\s} escape sequence
9991 that take a numeric expression as their argument (see below).
9993 For example, suppose @var{sizescale} is@tie{}1000; then a scaled point
9994 is equivalent to a millipoint; the request @w{@samp{.ps 10.25}} is
9995 equivalent to @w{@samp{.ps 10.25z}} and thus sets the point size to
9996 10250@tie{}scaled points, which is equal to 10.25@tie{}points.
9998 @code{gtroff} disallows the use of the @samp{z} scale indicator in
9999 instances where it would make no sense, such as a numeric
10000 expression whose default scale indicator was neither @samp{u} nor
10001 @samp{z}. Similarly it would make
10002 no sense to use a scaling indicator other than @samp{z} or @samp{u} in a
10003 numeric expression whose default scale indicator was @samp{z}, and so
10004 @code{gtroff} disallows this as well.
10006 There is also new scale indicator @samp{s} which multiplies by the
10007 number of units in a scaled point. So, for example, @samp{\n[.ps]s} is
10008 equal to @samp{1m}. Be sure not to confuse the @samp{s} and @samp{z}
10012 A read-only number register returning the point size in scaled points.
10014 @code{.ps} is associated with the current environment
10015 (@pxref{Environments}).
10019 @DefregListEnd {.sr}
10020 @cindex last-requested point size registers (@code{.psr}, @code{.sr})
10021 @cindex point size registers, last-requested (@code{.psr}, @code{.sr})
10022 @cindex @code{.ps} register, in comparison with @code{.psr}
10023 @cindex @code{.s} register, in comparison with @code{.sr}
10024 The last-requested point size in scaled points is contained in the
10025 @code{.psr} read-only number register. The last requested point size
10026 in points as a decimal fraction can be found in @code{.sr}. This is a
10027 string-valued read-only number register.
10029 Note that the requested point sizes are device-independent, whereas
10030 the values returned by the @code{.ps} and @code{.s} registers are not.
10031 For example, if a point size of 11@dmn{pt} is requested, and a
10032 @code{sizes} request (or a @code{sizescale} line in a @file{DESC} file)
10033 specifies 10.95@dmn{pt} instead, this value is actually used.
10035 Both registers are associated with the current environment
10036 (@pxref{Environments}).
10039 The @code{\s} escape has the following syntax for working with
10040 fractional type sizes:
10045 Set the point size to @var{n}@tie{}scaled points; @var{n}@tie{}is a numeric
10046 expression with a default scale indicator of @samp{z}.
10049 @itemx \s[-@var{n}]
10050 @itemx \s+[@var{n}]
10051 @itemx \s-[@var{n}]
10052 @itemx \s'+@var{n}'
10053 @itemx \s'-@var{n}'
10054 @itemx \s+'@var{n}'
10055 @itemx \s-'@var{n}'
10056 Increase or or decrease the point size by @var{n}@tie{}scaled points;
10057 @var{n}@tie{}is a numeric expression with a default scale indicator of
10064 @c =====================================================================
10066 @node Strings, Conditionals and Loops, Sizes, gtroff Reference
10070 @code{gtroff} has string variables, which are entirely for user
10071 convenience (i.e.@: there are no built-in strings exept @code{.T}, but
10072 even this is a read-write string variable).
10074 @DefreqList {ds, name [@Var{string}]}
10075 @DefreqItem {ds1, name [@Var{string}]}
10076 @DefescItem {\\*, , n, }
10077 @DefescItem {\\*, @Lparen{}, nm, }
10078 @DefescListEnd {\\*, @Lbrack{}, name arg1 arg2 @dots{}, @Rbrack{}}
10079 @cindex string interpolation (@code{\*})
10080 @cindex string expansion (@code{\*})
10081 @cindex interpolation of strings (@code{\*})
10082 @cindex expansion of strings (@code{\*})
10083 @cindex string arguments
10084 @cindex arguments, of strings
10085 Define and access a string variable @var{name} (one-character
10086 name@tie{}@var{n}, two-character name @var{nm}). If @var{name} already
10087 exists, @code{ds} overwrites the previous definition. Only the syntax form
10088 using brackets can take arguments which are handled identically to
10089 macro arguments; the single exception is that a closing bracket as an
10090 argument must be enclosed in double quotes. @xref{Request and Macro
10091 Arguments}, and @ref{Parameters}.
10096 .ds foo a \\$1 test
10098 This is \*[foo nice].
10099 @result{} This is a nice test.
10102 The @code{\*} escape @dfn{interpolates} (expands in-place) a
10103 previously-defined string variable. To be more precise, the stored
10104 string is pushed onto the input stack which is then parsed by
10105 @code{gtroff}. Similar to number registers, it is possible to nest
10106 strings, i.e. string variables can be called within string variables.
10108 If the string named by the @code{\*} escape does not exist, it is
10109 defined as empty, and a warning of type @samp{mac} is emitted (see
10110 @ref{Debugging}, for more details).
10112 @cindex comments, with @code{ds}
10113 @cindex @code{ds} request, and comments
10114 @strong{Caution:} Unlike other requests, the second argument to the
10115 @code{ds} request takes up the entire line including trailing spaces.
10116 This means that comments on a line with such a request can introduce
10117 unwanted space into a string.
10120 .ds UX \s-1UNIX\s0\u\s-3tm\s0\d \" UNIX trademark
10124 Instead the comment should be put on another line or have the comment
10125 escape adjacent with the end of the string.
10128 .ds UX \s-1UNIX\s0\u\s-3tm\s0\d\" UNIX trademark
10131 @cindex trailing quotes
10132 @cindex quotes, trailing
10133 @cindex leading spaces with @code{ds}
10134 @cindex spaces with @code{ds}
10135 @cindex @code{ds} request, and leading spaces
10136 To produce leading space the string can be started with a double
10137 quote. No trailing quote is needed; in fact, any trailing quote is
10138 included in your string.
10141 .ds sign " Yours in a white wine sauce,
10144 @cindex multi-line strings
10145 @cindex strings, multi-line
10146 @cindex newline character, in strings, escaping
10147 @cindex escaping newline characters, in strings
10148 Strings are not limited to a single line of text. A string can span
10149 several lines by escaping the newlines with a backslash. The
10150 resulting string is stored @emph{without} the newlines.
10153 .ds foo lots and lots \
10154 of text are on these \
10158 It is not possible to have real newlines in a string. To put a single
10159 double quote character into a string, use two consecutive double quote
10162 The @code{ds1} request turns off compatibility mode
10163 while interpreting a string. To be more precise, a @dfn{compatibility
10164 save} input token is inserted at the beginning of the string, and a
10165 @dfn{compatibility restore} input token at the end.
10169 .ds aa The value of xxx is \\n[xxx].
10170 .ds1 bb The value of xxx ix \\n[xxx].
10175 @result{} warning: number register `[' not defined
10176 @result{} The value of xxx is 0xxx].
10178 @result{} The value of xxx ix 12345.
10181 @cindex name space, common, of macros, diversions, and strings
10182 @cindex common name space of macros, diversions, and strings
10183 @cindex macros, shared name space with strings and diversions
10184 @cindex strings, shared name space with macros and diversions
10185 @cindex diversions, shared name space with macros and strings
10186 Strings, macros, and diversions (and boxes) share the same name space.
10187 Internally, even the same mechanism is used to store them. This has
10188 some interesting consequences. For example, it is possible to call a
10189 macro with string syntax and vice versa.
10196 @result{} This is a funny test.
10198 .ds yyy a funny test
10201 @result{} This is a funny test.
10204 Diversions and boxes can be also called with string syntax.
10206 Another consequence is that you can copy one-line diversions or boxes
10214 .ds yyy This is \*[xxx]\c
10216 @result{} @r{This is a }@i{test}.
10220 As the previous example shows, it is possible to store formatted
10221 output in strings. The @code{\c} escape prevents the insertion of an
10222 additional blank line in the output.
10224 Copying diversions longer than a single output line produces
10225 unexpected results.
10234 .ds yyy This is \*[xxx]\c
10236 @result{} test This is a funny.
10239 Usually, it is not predictable whether a diversion contains one or
10240 more output lines, so this mechanism should be avoided. With
10241 @acronym{UNIX} @code{troff}, this was the only solution to strip off a
10242 final newline from a diversion. Another disadvantage is that the
10243 spaces in the copied string are already formatted, making them
10244 unstretchable. This can cause ugly results.
10246 @cindex stripping final newline in diversions
10247 @cindex diversion, stripping final newline
10248 @cindex final newline, stripping in diversions
10249 @cindex newline, final, stripping in diversions
10250 @cindex horizontal space, unformatting
10251 @cindex space, horizontal, unformatting
10252 @cindex unformatting horizontal space
10253 A clean solution to this problem is available in GNU @code{troff},
10254 using the requests @code{chop} to remove the final newline of a
10255 diversion, and @code{unformat} to make the horizontal spaces
10268 @result{} This is a funny test.
10271 @xref{Gtroff Internals}, for more information.
10274 @DefreqList {as, name [@Var{string}]}
10275 @DefreqListEnd {as1, name [@Var{string}]}
10276 @cindex appending to a string (@code{as})
10277 @cindex string, appending (@code{as})
10278 The @code{as} request is similar to @code{ds} but appends @var{string}
10279 to the string stored as @var{name} instead of redefining it. If
10280 @var{name} doesn't exist yet, it is created.
10283 .as sign " with shallots, onions and garlic,
10286 The @code{as1} request is similar to @code{as}, but compatibility mode
10287 is switched off while the appended string is interpreted. To be more
10288 precise, a @dfn{compatibility save} input token is inserted at the
10289 beginning of the appended string, and a @dfn{compatibility restore}
10290 input token at the end.
10293 Rudimentary string manipulation routines are given with the next two
10296 @Defreq {substring, str n1 [@Var{n2}]}
10297 @cindex substring (@code{substring})
10298 Replace the string named @var{str} with the substring
10299 defined by the indices @var{n1} and@tie{}@var{n2}. The first character
10300 in the string has index@tie{}0. If @var{n2} is omitted, it is taken to
10301 be equal to the string's length. If the index value @var{n1} or
10302 @var{n2} is negative, it is counted from the end of the
10303 string, going backwards: The last character has index@tie{}@minus{}1, the
10304 character before the last character has index@tie{}@minus{}2, etc.
10308 .substring xxx 1 -4
10314 @Defreq {length, reg str}
10315 @cindex length of a string (@code{length})
10316 @cindex string, length of (@code{length})
10317 Compute the number of characters of @var{str} and return it in the
10318 number register @var{reg}. If @var{reg} doesn't exist, it is created.
10319 @code{str} is read in copy mode.
10322 .ds xxx abcd\h'3i'efgh
10323 .length yyy \*[xxx]
10329 @Defreq {rn, xx yy}
10330 @cindex renaming request (@code{rn})
10331 @cindex request, renaming (@code{rn})
10332 @cindex renaming macro (@code{rn})
10333 @cindex macro, renaming (@code{rn})
10334 @cindex renaming string (@code{rn})
10335 @cindex string, renaming (@code{rn})
10336 @cindex renaming diversion (@code{rn})
10337 @cindex diversion, renaming (@code{rn})
10338 Rename the request, macro, diversion, or string @var{xx} to @var{yy}.
10342 @cindex removing request (@code{rm})
10343 @cindex request, removing (@code{rm})
10344 @cindex removing macro (@code{rm})
10345 @cindex macro, removing (@code{rm})
10346 @cindex removing string (@code{rm})
10347 @cindex string, removing (@code{rm})
10348 @cindex removing diversion (@code{rm})
10349 @cindex diversion, removing (@code{rm})
10350 Remove the request, macro, diversion, or string @var{xx}. @code{gtroff}
10351 treats subsequent invocations as if the object had never been defined.
10354 @Defreq {als, new old}
10355 @cindex alias, string, creating (@code{als})
10356 @cindex alias, macro, creating (@code{als})
10357 @cindex alias, diversion, creating (@code{als})
10358 @cindex creating alias, for string (@code{als})
10359 @cindex creating alias, for macro (@code{als})
10360 @cindex creating alias, for diversion (@code{als})
10361 @cindex string, creating alias (@code{als})
10362 @cindex macro, creating alias (@code{als})
10363 @cindex diversion, creating alias (@code{als})
10364 Create an alias named @var{new} for the request, string, macro, or
10365 diversion object named @var{old}. The new name and the old name are
10366 exactly equivalent (it is similar to a hard rather than a soft
10367 link). If @var{old} is undefined, @code{gtroff} generates a warning of
10368 type @samp{mac} and ignores the request.
10372 Remove (chop) the last character from the macro, string, or diversion
10373 named @var{xx}. This is useful for removing the newline from the end
10374 of diversions that are to be interpolated as strings. This command
10375 can be used repeatedly; see @ref{Gtroff Internals}, for details on
10376 nodes inserted additionally by @code{gtroff}.
10379 @xref{Identifiers}, and @ref{Comments}.
10382 @c =====================================================================
10384 @node Conditionals and Loops, Writing Macros, Strings, gtroff Reference
10385 @section Conditionals and Loops
10386 @cindex conditionals and loops
10387 @cindex loops and conditionals
10390 * Operators in Conditionals::
10395 @c ---------------------------------------------------------------------
10397 @node Operators in Conditionals, if-else, Conditionals and Loops, Conditionals and Loops
10398 @subsection Operators in Conditionals
10400 @cindex @code{if} request, operators to use with
10401 @cindex @code{while} request, operators to use with
10402 In @code{if} and @code{while} requests, there are several more
10403 operators available:
10408 True if the current page is even or odd numbered (respectively).
10411 True if the document is being processed in nroff mode (i.e., the
10412 @code{.nroff} command has been issued).
10415 True if the document is being processed in troff mode (i.e., the
10416 @code{.troff} command has been issued).
10419 Always false. This condition is for compatibility with other
10420 @code{troff} versions only (identifying a @code{-Tversatec} device).
10422 @item '@var{xxx}'@var{yyy}'
10423 True if the string @var{xxx} is equal to the string @var{yyy}. Other
10424 characters can be used in place of the single quotes; the same set of
10425 delimiters as for the @code{\D} escape is used (@pxref{Escapes}).
10426 @code{gtroff} formats the strings before being compared:
10437 The resulting motions, glyph sizes, and fonts have to
10438 match,@footnote{The created output nodes must be identical.
10439 @xref{Gtroff Internals}.} and not the individual motion, size, and
10440 font requests. In the previous example, @samp{|} and @samp{\fR|\fP}
10441 both result in a roman @samp{|} glyph with the same point size and
10442 at the same location on the page, so the strings are equal. If
10443 @samp{.ft@tie{}I} had been added before the @samp{.ie}, the result
10444 would be ``false'' because (the first) @samp{|} produces an italic
10445 @samp{|} rather than a roman one.
10448 True if there is a number register named @var{xxx}.
10451 True if there is a string, macro, diversion, or request named @var{xxx}.
10454 True if there is a color named @var{xxx}.
10457 True if there is a glyph @var{g} available@footnote{The name of this
10458 conditional operator is a misnomer since it tests names of output
10459 glyphs.}; @var{g} is either an @acronym{ASCII} character or a special
10460 character (@code{\(@var{gg}} or @code{\[@var{ggg}]}); the condition
10461 is also true if @var{g} has been defined by the @code{char} request.
10464 True if a font named @var{font} exists. @var{font} is handled as if it was
10465 opened with the @code{ft} request (this is, font translation and styles are
10466 applied), without actually mounting it.
10468 This test doesn't load the complete font but only its header to verify
10471 @item S @var{style}
10472 True if style @var{style} has been registered. Font translation is applied.
10475 Note that these operators can't be combined with other operators like
10476 @samp{:} or @samp{&}; only a leading @samp{!} (without whitespace
10477 between the exclamation mark and the operator) can be used to negate
10489 A whitespace after @samp{!} always evaluates to zero (this bizarre
10490 behaviour is due to compatibility with @acronym{UNIX} @code{troff}).
10498 @result{} r xxx true
10501 It is possible to omit the whitespace before the argument to the
10502 @samp{r}, @samp{d}, and @samp{c} operators.
10504 @xref{Expressions}.
10506 @c ---------------------------------------------------------------------
10508 @node if-else, while, Operators in Conditionals, Conditionals and Loops
10509 @subsection if-else
10512 @code{gtroff} has if-then-else constructs like other languages, although
10513 the formatting can be painful.
10515 @Defreq {if, expr anything}
10517 Evaluate the expression @var{expr}, and executes @var{anything} (the
10518 remainder of the line) if @var{expr} evaluates to a value greater than
10519 zero (true). @var{anything} is interpreted as though it was on a line
10520 by itself (except that leading spaces are swallowed).
10521 @xref{Expressions}, for more info.
10526 .if ((\n[xxx] == 1) & (\n[yyy] == 2)) true
10531 @Defreq{nop, anything}
10532 Executes @var{anything}.
10533 This is similar to @code{.if@tie{}1}.
10536 @DefreqList {ie, expr anything}
10537 @DefreqListEnd {el, anything}
10538 Use the @code{ie} and @code{el} requests to write an if-then-else.
10539 The first request is the `if' part and the latter is the `else' part.
10542 .ie n .ls 2 \" double-spacing in nroff
10543 .el .ls 1 \" single-spacing in troff
10547 @c there is a bug in makeinfo <= 4.1a: you can't have `@{' as an argument
10550 @c and in 4.2 you still can't use @{ in macros.
10552 @c @DefescList {\@{, , , }
10553 @c @DefescListEnd {\@}, , , }
10554 @deffn Escape @t{\@{}
10555 @deffnx Escape @t{\@}}
10558 @cindex begin of conditional block (@code{\@{})
10559 @cindex end of conditional block (@code{\@}})
10560 @cindex conditional block, begin (@code{\@{})
10561 @cindex conditional block, end (@code{\@}})
10562 @cindex block, conditional, begin (@code{\@{})
10563 @cindex block, condititional, end (@code{\@}})
10564 In many cases, an if (or if-else) construct needs to execute more than
10565 one request. This can be done using the @code{\@{} and @code{\@}}
10566 escapes. The following example shows the possible ways to use these
10567 escapes (note the position of the opening and closing braces).
10582 @xref{Expressions}.
10584 @c ---------------------------------------------------------------------
10586 @node while, , if-else, Conditionals and Loops
10590 @code{gtroff} provides a looping construct using the @code{while}
10591 request, which is used much like the @code{if} (and related) requests.
10593 @Defreq {while, expr anything}
10594 Evaluate the expression @var{expr}, and repeatedly execute
10595 @var{anything} (the remainder of the line) until @var{expr} evaluates
10600 .while (\na < 9) \@{\
10604 @result{} 1, 2, 3, 4, 5, 6, 7, 8, 9, 10
10609 @cindex @code{de} request, and @code{while}
10612 The body of a @code{while} request is treated like the body of a
10613 @code{de} request: @code{gtroff} temporarily stores it in a macro
10614 which is deleted after the loop has been exited. It can considerably
10615 slow down a macro if the body of the @code{while} request (within the
10616 macro) is large. Each time the macro is executed, the @code{while}
10617 body is parsed and stored again as a temporary macro.
10622 . while (\\n[num] > 0) \@{\
10623 . \" many lines of code
10629 @cindex recursive macros
10630 @cindex macros, recursive
10632 The traditional and ofter better solution (@acronym{UNIX} @code{troff}
10633 doesn't have the @code{while} request) is to use a recursive macro
10634 instead which is parsed only once during its definition.
10638 . if (\\n[num] > 0) \@{\
10639 . \" many lines of code
10652 Note that the number of available recursion levels is set to@tie{}1000
10653 (this is a compile-time constant value of @code{gtroff}).
10656 The closing brace of a @code{while} body must end a line.
10661 . while (\n[a] < 10) \@{\
10664 @result{} unbalanced \@{ \@}
10670 @cindex @code{while} request, confusing with @code{br}
10671 @cindex @code{break} request, in a @code{while} loop
10672 @cindex @code{continue} request, in a @code{while} loop
10673 Break out of a @code{while} loop. Be sure not to confuse this with
10674 the @code{br} request (causing a line break).
10677 @Defreq {continue, }
10678 Finish the current iteration of a @code{while} loop, immediately
10679 restarting the next iteration.
10682 @xref{Expressions}.
10685 @c =====================================================================
10687 @node Writing Macros, Page Motions, Conditionals and Loops, gtroff Reference
10688 @section Writing Macros
10689 @cindex writing macros
10690 @cindex macros, writing
10692 A @dfn{macro} is a collection of text and embedded commands which can
10693 be invoked multiple times. Use macros to define common operations.
10695 @DefreqList {de, name [@Var{end}]}
10696 @DefreqItem {de1, name [@Var{end}]}
10697 @DefreqItem {dei, name [@Var{end}]}
10698 @DefreqListEnd {dei1, name [@Var{end}]}
10699 Define a new macro named @var{name}. @code{gtroff} copies subsequent
10700 lines (starting with the next one) into an internal buffer until it
10701 encounters the line @samp{..} (two dots). The optional second
10702 argument to @code{de} changes this to a macro to @samp{.@var{end}}.
10704 There can be whitespace after the first dot in the line containing the
10705 ending token (either @samp{.} or macro @samp{@var{end}}).
10707 Here a small example macro called @samp{P} which causes a break and
10708 inserts some vertical space. It could be used to separate paragraphs.
10717 The following example defines a macro within another. Remember that
10718 expansion must be protected twice; once for reading the macro and
10719 once for executing.
10722 \# a dummy macro to avoid a warning
10728 . nop \f[B]Hallo \\\\$1!\f[]
10734 @result{} @b{Hallo Joe!}
10738 Since @code{\f} has no expansion, it isn't necessary to protect its
10739 backslash. Had we defined another macro within @code{bar} which takes
10740 a parameter, eight backslashes would be necessary before @samp{$1}.
10742 The @code{de1} request turns off compatibility mode
10743 while executing the macro. On entry, the current compatibility mode
10744 is saved and restored at exit.
10750 The value of xxx is \\n[xxx].
10753 The value of xxx ix \\n[xxx].
10759 @result{} warning: number register `[' not defined
10760 @result{} The value of xxx is 0xxx].
10762 @result{} The value of xxx ix 12345.
10765 The @code{dei} request defines a macro indirectly.
10766 That is, it expands strings whose names
10767 are @var{name} or @var{end} before performing the append.
10784 The @code{dei1} request is similar to @code{dei} but with compatibility
10785 mode switched off during execution of the defined macro.
10787 If compatibility mode is on, @code{de} (and @code{dei}) behave similar to
10788 @code{de1} (and @code{dei1}): A `compatibility save' token is inserted at
10789 the beginning, and a `compatibility restore' token at the end, with
10790 compatibility mode switched on during execution. @xref{Gtroff Internals},
10791 for more information on switching compatibility mode on and off in a
10795 Using @file{trace.tmac}, you can trace calls to @code{de} and @code{de1}.
10797 Note that macro identifiers are shared with identifiers for strings and
10801 @DefreqList {am, name [@Var{end}]}
10802 @DefreqItem {am1, name [@Var{end}]}
10803 @DefreqItem {ami, name [@Var{end}]}
10804 @DefreqListEnd {ami1, name [@Var{end}]}
10805 @cindex appending to a macro (@code{am})
10806 @cindex macro, appending (@code{am})
10807 Works similarly to @code{de} except it appends onto the macro named
10808 @var{name}. So, to make the previously defined @samp{P} macro actually
10809 do indented instead of block paragraphs, add the necessary code to the
10810 existing macro like this:
10818 The @code{am1} request turns off compatibility mode
10819 while executing the appended macro piece. To be more precise, a
10820 @dfn{compatibility save} input token is inserted at the beginning of
10821 the appended code, and a @dfn{compatibility restore} input token at
10824 The @code{ami} request appends indirectly,
10825 meaning that @code{gtroff} expands strings whose names
10826 are @var{name} or @var{end} before performing the append.
10828 The @code{ami1} request is similar to @code{ami} but compatibility mode
10829 is switched off during execution of the defined macro.
10832 Using @file{trace.tmac}, you can trace calls to @code{am} and @code{am1}.
10835 @xref{Strings}, for the @code{als} request to rename a macro.
10837 The @code{de}, @code{am}, @code{di}, @code{da}, @code{ds}, and
10838 @code{as} requests (together with its variants) only create a new object
10839 if the name of the macro, diversion or string diversion is currently
10840 undefined or if it is defined to be a request; normally they modify the
10841 value of an existing object.
10843 @Defreq {return, [@Var{anything}]}
10844 Exit a macro, immediately returning to the caller.
10846 If called with an argument, exit twice, namely the current macro and the
10847 macro one level higher. This is used to define a wrapper macro for
10848 @code{return} in @file{trace.tmac}.
10856 @c ---------------------------------------------------------------------
10858 @node Copy-in Mode, Parameters, Writing Macros, Writing Macros
10859 @subsection Copy-in Mode
10860 @cindex copy-in mode
10861 @cindex mode, copy-in
10863 @cindex @code{\n}, when reading text for a macro
10864 @cindex @code{\$}, when reading text for a macro
10865 @cindex @code{\*}, when reading text for a macro
10866 @cindex @code{\\}, when reading text for a macro
10867 @cindex \@key{RET}, when reading text for a macro
10868 When @code{gtroff} reads in the text for a macro, string, or diversion,
10869 it copies the text (including request lines, but excluding escapes) into
10870 an internal buffer. Escapes are converted into an internal form,
10871 except for @code{\n}, @code{\$}, @code{\*}, @code{\\} and
10872 @code{\@key{RET}} which are evaluated and inserted into the text where
10873 the escape was located. This is known as @dfn{copy-in} mode or
10876 What this means is that you can specify when these escapes are to be
10877 evaluated (either at copy-in time or at the time of use) by insulating
10878 the escapes with an extra backslash. Compare this to the @code{\def}
10879 and @code{\edef} commands in @TeX{}.
10881 The following example prints the numbers 20 and@tie{}10:
10893 @c ---------------------------------------------------------------------
10895 @node Parameters, , Copy-in Mode, Writing Macros
10896 @subsection Parameters
10899 The arguments to a macro or string can be examined using a variety of
10903 @cindex number of arguments register (@code{.$})
10904 The number of arguments passed to a macro or string. This is a read-only
10907 Note that the @code{shift} request can change its value.
10910 Any individual argument can be retrieved with one of the following
10913 @DefescList {\\$, , n, }
10914 @DefescItem {\\$, @Lparen{}, nn, }
10915 @DefescListEnd {\\$, @Lbrack{}, nnn, @Rbrack{}}
10916 @cindex copy-in mode, and macro arguments
10917 @cindex macro, arguments (@code{\$})
10918 @cindex arguments, macro (@code{\$})
10919 Retrieve the @var{n}@dmn{th}, @var{nn}@dmn{th} or @var{nnn}@dmn{th}
10920 argument. As usual, the first form only accepts a single number
10921 (larger than zero), the second a two-digit number (larger or equal
10922 to@tie{}10), and the third any positive integer value (larger
10923 than zero). Macros and strings can have an unlimited number of arguments.
10924 Note that due to copy-in mode, use two backslashes on these in actual use
10925 to prevent interpolation until the macro is actually invoked.
10928 @Defreq {shift, [@Var{n}]}
10929 Shift the arguments 1@tie{}position, or as
10930 many positions as specified by its argument. After executing this
10931 request, argument@tie{}@var{i} becomes argument @math{@var{i}-@var{n}};
10932 arguments 1 to@tie{}@var{n} are no longer available. Shifting by
10933 negative amounts is currently undefined.
10935 The register @code{.$} is adjusted accordingly.
10938 @DefescList {\\$*, , , }
10939 @DefescListEnd {\\$@@, , , }
10940 In some cases it is convenient to use all of the arguments at once (for
10941 example, to pass the arguments along to another macro). The @code{\$*}
10942 escape concatenates all the arguments separated by spaces. A
10943 similar escape is @code{\$@@}, which concatenates all the
10944 arguments with each surrounded by double quotes, and separated by
10945 spaces. If not in compatibility mode, the input level of double quotes
10946 is preserved (see @ref{Request and Macro Arguments}).
10949 @Defesc {\\$0, , , }
10950 @cindex macro name register (@code{\$0})
10951 @cindex @code{als} request, and @code{\$0}
10952 The name used to invoke the current macro.
10953 The @code{als} request can make a macro have more than one name.
10958 . if \\n[error] \@{\
10959 . tm \\$0: Houston, we have a problem.
10964 .als foo generic-macro
10965 .als bar generic-macro
10969 @xref{Request and Macro Arguments}.
10972 @c =====================================================================
10974 @node Page Motions, Drawing Requests, Writing Macros, gtroff Reference
10975 @section Page Motions
10976 @cindex page motions
10977 @cindex motions, page
10979 @xref{Manipulating Spacing}, for a discussion of the main request for
10980 vertical motion, @code{sp}.
10982 @DefreqList {mk, [@Var{reg}]}
10983 @DefreqListEnd {rt, [@Var{dist}]}
10984 @cindex marking vertical page location (@code{mk})
10985 @cindex page location, vertical, marking (@code{mk})
10986 @cindex location, vertical, page, marking (@code{mk})
10987 @cindex vertical page location, marking (@code{mk})
10988 @cindex returning to marked vertical page location (@code{rt})
10989 @cindex page location, vertical, returning to marked (@code{rt})
10990 @cindex location, vertical, page, returning to marked (@code{rt})
10991 @cindex vertical page location, returning to marked (@code{rt})
10992 The request @code{mk} can be used to mark a location on a page, for
10993 movement to later. This request takes a register name as an argument
10994 in which to store the current page location. With no argument it
10995 stores the location in an internal register. The results of this can
10996 be used later by the @code{rt} or the @code{sp} request (or the
10999 The @code{rt} request returns @emph{upwards} to the location marked
11000 with the last @code{mk} request. If used with an argument, return to
11001 a position which distance from the top of the page is @var{dist} (no
11002 previous call to @code{mk} is necessary in this case). Default scaling
11003 indicator is @samp{v}.
11005 Here a primitive solution for a two-column macro.
11008 .nr column-length 1.5i
11010 .nr bottom-margin 1m
11017 . ll \\n[column-length]u
11018 . wh -\\n[bottom-margin]u 2c-trap
11025 . ie \\n[right-side] \@{\
11027 . po -(\\n[column-length]u + \\n[column-gap]u)
11029 . wh -\\n[bottom-margin]u
11032 . \" switch to right side
11034 . po +(\\n[column-length]u + \\n[column-gap]u)
11043 This is a small test which shows how the
11044 rt request works in combination with mk.
11047 Starting here, text is typeset in two columns.
11048 Note that this implementation isn't robust
11049 and thus not suited for a real two-column
11056 This is a small test which shows how the
11057 rt request works in combination with mk.
11059 Starting here, isn't robust
11060 text is typeset and thus not
11061 in two columns. suited for a
11062 Note that this real two-column
11063 implementation macro.
11067 The following escapes give fine control of movements about the page.
11069 @Defesc {\\v, ', e, '}
11070 @cindex vertical motion (@code{\v})
11071 @cindex motion, vertical (@code{\v})
11072 Move vertically, usually from the current location on the page (if no
11073 absolute position operator @samp{|} is used). The
11074 argument@tie{}@var{e} specifies the distance to move; positive is
11075 downwards and negative upwards. The default scaling indicator for this
11076 escape is @samp{v}. Beware, however, that @code{gtroff} continues text
11077 processing at the point where the motion ends, so you should always
11078 balance motions to avoid interference with text processing.
11080 @code{\v} doesn't trigger a trap. This can be quite useful; for example,
11081 consider a page bottom trap macro which prints a marker in the margin to
11082 indicate continuation of a footnote or something similar.
11085 There are some special-case escapes for vertical motion.
11087 @Defesc {\\r, , , }
11088 Move upwards@tie{}1@dmn{v}.
11091 @Defesc {\\u, , , }
11092 Move upwards@tie{}.5@dmn{v}.
11095 @Defesc {\\d, , , }
11096 Move down@tie{}.5@dmn{v}.
11099 @Defesc {\\h, ', e, '}
11100 @cindex inserting horizontal space (@code{\h})
11101 @cindex horizontal space (@code{\h})
11102 @cindex space, horizontal (@code{\h})
11103 @cindex horizontal motion (@code{\h})
11104 @cindex motion, horizontal (@code{\h})
11105 Move horizontally, usually from the current location (if no absolute
11106 position operator @samp{|} is used). The expression@tie{}@var{e}
11107 indicates how far to move: positive is rightwards and negative
11108 leftwards. The default scaling indicator for this escape is @samp{m}.
11110 This horizontal space is not discarded at the end of a line. To insert
11111 discardable space of a certain length use the @code{ss} request.
11114 There are a number of special-case escapes for horizontal motion.
11116 @Defesc {\\@key{SP}, , , }
11117 @cindex space, unbreakable
11118 @cindex unbreakable space
11119 An unbreakable and unpaddable (i.e.@: not expanded during filling)
11120 space. (Note: This is a backslash followed by a space.)
11123 @Defesc {\\~, , , }
11124 An unbreakable space that stretches like a normal inter-word space
11125 when a line is adjusted.
11128 @Defesc {\\|, , , }
11129 A 1/6@dmn{th} em space. Ignored for TTY output devices (rounded to
11133 @Defesc {\\^, , , }
11134 A 1/12@dmn{th} em space. Ignored for TTY output devices (rounded to
11138 @Defesc {\\0, , , }
11139 @cindex space, width of a digit (@code{\0})
11140 @cindex digit width space (@code{\0})
11141 A space the size of a digit.
11144 The following string sets the @TeX{} logo:
11147 .ds TeX T\h'-.1667m'\v'.224m'E\v'-.224m'\h'-.125m'X
11150 @DefescList {\\w, ', text, '}
11157 @DefregListEnd {skw}
11158 @cindex width escape (@code{\w})
11159 Return the width of the specified @var{text} in basic units.
11160 This allows horizontal movement based on the width of some
11161 arbitrary text (e.g.@: given as an argument to a macro).
11164 The length of the string `abc' is \w'abc'u.
11165 @result{} The length of the string `abc' is 72u.
11168 Font changes may occur in @var{text} which don't affect current
11171 After use, @code{\w} sets several registers:
11176 The highest and lowest point of the baseline, respectively, in @var{text}.
11180 Like the @code{st} and @code{sb} registers, but takes account of the
11181 heights and depths of glyphs. With other words, this gives the
11182 highest and lowest point of @var{text}. Values below the baseline are
11186 Defines the kinds of glyphs occurring in @var{text}:
11190 only short glyphs, no descenders or tall glyphs.
11193 at least one descender.
11196 at least one tall glyph.
11199 at least one each of a descender and a tall glyph.
11203 The amount of horizontal space (possibly negative) that should be added
11204 to the last glyph before a subscript.
11207 How far to right of the center of the last glyph in the @code{\w}
11208 argument, the center of an accent from a roman font should be placed
11213 @DefescList {\\k, , p, }
11214 @DefescItem {\\k, @Lparen{}, ps, }
11215 @DefescListEnd {\\k, @Lbrack{}, position, @Rbrack{}}
11216 @cindex saving horizontal input line position (@code{\k})
11217 @cindex horizontal input line position, saving (@code{\k})
11218 @cindex input line position, horizontal, saving (@code{\k})
11219 @cindex position, horizontal input line, saving (@code{\k})
11220 @cindex line, input, horizontal position, saving (@code{\k})
11221 Store the current horizontal position in the @emph{input} line in
11222 number register with name @var{position} (one-character name@tie{}@var{p},
11223 two-character name @var{ps}). Use this, for example, to return to the
11224 beginning of a string for highlighting or other decoration.
11228 @cindex horizontal input line position register (@code{hp})
11229 @cindex input line, horizontal position, register (@code{hp})
11230 @cindex position, horizontal, in input line, register (@code{hp})
11231 @cindex line, input, horizontal position, register (@code{hp})
11232 The current horizontal position at the input line.
11236 @cindex horizontal output line position register (@code{.k})
11237 @cindex output line, horizontal position, register (@code{.k})
11238 @cindex position, horizontal, in output line, register (@code{.k})
11239 @cindex line, output, horizontal position, register (@code{.k})
11240 A read-only number register containing the current horizontal output
11241 position (relative to the current indentation).
11244 @Defesc {\\o, ', abc, '}
11245 @cindex overstriking glyphs (@code{\o})
11246 @cindex glyphs, overstriking (@code{\o})
11247 Overstrike glyphs @var{a}, @var{b}, @var{c}, @dots{}; the glyphs
11248 are centered, and the resulting spacing is the largest width of the
11252 @Defesc {\\z, , g, , }
11253 @cindex zero-width printing (@code{\z}, @code{\Z})
11254 @cindex printing, zero-width (@code{\z}, @code{\Z})
11255 Print glyph @var{g} with zero width, i.e., without spacing. Use
11256 this to overstrike glyphs left-aligned.
11259 @Defesc {\\Z, ', anything, '}
11260 @cindex zero-width printing (@code{\z}, @code{\Z})
11261 @cindex printing, zero-width (@code{\z}, @code{\Z})
11262 Print @var{anything}, then restore the horizontal and vertical position.
11263 The argument may not contain tabs or leaders.
11265 The following is an example of a strike-through macro:
11270 \Z@@\v'-.25m'\l'\\n[ww]u'@@\\$1
11275 an actual emergency!
11280 @c =====================================================================
11282 @node Drawing Requests, Traps, Page Motions, gtroff Reference
11283 @section Drawing Requests
11284 @cindex drawing requests
11285 @cindex requests for drawing
11287 @code{gtroff} provides a number of ways to draw lines and other figures
11288 on the page. Used in combination with the page motion commands (see
11289 @ref{Page Motions}, for more info), a wide variety of figures can be
11290 drawn. However, for complex drawings these operations can be quite
11291 cumbersome, and it may be wise to use graphic preprocessors like
11292 @code{gpic} or @code{ggrn}. @xref{gpic}, and @ref{ggrn}, for more
11295 All drawing is done via escapes.
11297 @DefescList {\\l, ', l, '}
11298 @DefescListEnd {\\l, ', lg, '}
11299 @cindex drawing horizontal lines (@code{\l})
11300 @cindex horizontal line, drawing (@code{\l})
11301 @cindex line, horizontal, drawing (@code{\l})
11302 Draw a line horizontally. @var{l} is the length of the line to be
11303 drawn. If it is positive, start the line at the current location and
11304 draw to the right; its end point is the new current location. Negative
11305 values are handled differently: The line starts at the current location
11306 and draws to the left, but the current location doesn't move.
11308 @var{l} can also be specified absolutely (i.e.@: with a leading
11309 @samp{|}) which draws back to the beginning of the input line.
11310 Default scaling indicator is @samp{m}.
11312 @cindex underscore glyph (@code{\[ru]})
11313 @cindex glyph, underscore (@code{\[ru]})
11314 @cindex line drawing glyph
11315 @cindex glyph, for line drawing
11316 The optional second parameter@tie{}@var{g} is a glyph to draw the line
11317 with. If this second argument is not specified, @code{gtroff} uses
11318 the underscore glyph, @code{\[ru]}.
11320 @cindex zero width space character (@code{\&})
11321 @cindex character, zero width space (@code{\&})
11322 @cindex space character, zero width (@code{\&})
11323 To separate the two arguments (to prevent @code{gtroff} from
11324 interpreting a drawing glyph as a scaling indicator if the glyph is
11325 represented by a single character) use @code{\&}.
11327 Here a small useful example:
11331 \[br]\\$*\[br]\l'|0\[rn]'\l'|0\[ul]'
11336 Note that this works by outputting a box rule (a vertical line), then
11337 the text given as an argument and then another box rule. Finally, the
11338 line drawing escapes both draw from the current location to the
11339 beginning of the @emph{input} line -- this works because the line
11340 length is negative, not moving the current point.
11343 @DefescList {\\L, ', l, '}
11344 @DefescListEnd {\\L, ', lg, '}
11345 @cindex drawing vertical lines (@code{\L})
11346 @cindex vertical line drawing (@code{\L})
11347 @cindex line, vertical, drawing (@code{\L})
11348 @cindex line drawing glyph
11349 @cindex glyph for line drawing
11350 @cindex box rule glyph (@code{\[br]})
11351 @cindex glyph, box rule (@code{\[br]})
11352 Draw vertical lines. Its parameters are
11353 similar to the @code{\l} escape, except that the default scaling
11354 indicator is @samp{v}. The movement is downwards for positive values,
11355 and upwards for negative values. The default glyph is the box rule
11356 glyph, @code{\[br]}. As with the vertical motion escapes, text
11357 processing blindly continues where the line ends.
11360 This is a \L'3v'test.
11364 Here the result, produced with @code{grotty}.
11374 @Defesc {\\D, ', command arg @dots{}, '}
11375 The @code{\D} escape provides a variety of drawing functions.
11376 Note that on character devices, only vertical and horizontal lines are
11377 supported within @code{grotty}; other devices may only support a subset
11378 of the available drawing functions.
11380 The default scaling indicator for all subcommands of @code{\D} is
11381 @samp{m} for horizontal distances and @samp{v} for vertical ones.
11382 Exceptions are @w{@code{\D'f @dots{}'}} and @w{@code{\D't @dots{}'}}
11383 which use @code{u} as the default, and @w{@code{\D'F@var{x} @dots{}'}}
11384 which arguments are treated similar to the @code{defcolor} request.
11387 @item \D'l @var{dx} @var{dy}'
11388 @cindex line, drawing (@w{@code{\D'l @dots{}'}})
11389 @cindex drawing a line (@w{@code{\D'l @dots{}'}})
11390 Draw a line from the current location to the relative point specified by
11391 (@var{dx},@var{dy}), where positive values mean down and right,
11392 respectively. The end point of the line is the new current location.
11394 The following example is a macro for creating a box around a text string;
11395 for simplicity, the box margin is taken as a fixed value, 0.2@dmn{m}.
11401 \h'-.2m'\v'(.2m - \\n[rsb]u)'\
11402 \D'l 0 -(\\n[rst]u - \\n[rsb]u + .4m)'\
11403 \D'l (\\n[@@wd]u + .4m) 0'\
11404 \D'l 0 (\\n[rst]u - \\n[rsb]u + .4m)'\
11405 \D'l -(\\n[@@wd]u + .4m) 0'\
11406 \h'.2m'\v'-(.2m - \\n[rsb]u)'\
11413 First, the width of the string is stored in register @code{@@wd}. Then,
11414 four lines are drawn to form a box, properly offset by the box margin.
11415 The registers @code{rst} and @code{rsb} are set by the @code{\w} escape,
11416 containing the largest height and depth of the whole string.
11418 @item \D'c @var{d}'
11419 @cindex circle, drawing (@w{@code{\D'c @dots{}'}})
11420 @cindex drawing a circle (@w{@code{\D'c @dots{}'}})
11421 Draw a circle with a diameter of@tie{}@var{d} with the leftmost point at the
11422 current position. After drawing, the current location is positioned at the
11423 rightmost point of the circle.
11425 @item \D'C @var{d}'
11426 @cindex circle, solid, drawing (@w{@code{\D'C @dots{}'}})
11427 @cindex drawing a solid circle (@w{@code{\D'C @dots{}'}})
11428 @cindex solid circle, drawing (@w{@code{\D'C @dots{}'}})
11429 Draw a solid circle with the same parameters and behaviour as an outlined
11430 circle. No outline is drawn.
11432 @item \D'e @var{x} @var{y}'
11433 @cindex drawing an ellipse (@w{@code{\D'e @dots{}'}})
11434 @cindex ellipse, drawing (@w{@code{\D'e @dots{}'}})
11435 Draw an ellipse with a horizontal diameter of @var{x} and a vertical
11436 diameter of @var{y} with the leftmost point at the current position.
11437 After drawing, the current location is positioned at the rightmost point of
11440 @item \D'E @var{x} @var{y}'
11441 @cindex ellipse, solid, drawing (@w{@code{\D'E @dots{}'}})
11442 @cindex drawing a solid ellipse (@w{@code{\D'E @dots{}'}})
11443 @cindex solid ellipse, drawing (@w{@code{\D'E @dots{}'}})
11444 Draw a solid ellipse with the same parameters and behaviour as an
11445 outlined ellipse. No outline is drawn.
11447 @item \D'a @var{dx1} @var{dy1} @var{dx2} @var{dy2}'
11448 @cindex arc, drawing (@w{@code{\D'a @dots{}'}})
11449 @cindex drawing an arc (@w{@code{\D'a @dots{}'}})
11450 Draw an arc clockwise from the current location through the two
11451 specified relative locations (@var{dx1},@var{dy1}) and
11452 (@var{dx2},@var{dy2}). The coordinates of the first point are relative
11453 to the current position, and the coordinates of the second point are
11454 relative to the first point. After drawing, the current position is moved
11455 to the final point of the arc.
11457 @item \D'~ @var{dx1} @var{dy1} @var{dx2} @var{dy2} @dots{}'
11458 @cindex drawing a spline (@w{@code{\D'~ @dots{}'}})
11459 @cindex spline, drawing (@w{@code{\D'~ @dots{}'}})
11460 Draw a spline from the current location to the relative point
11461 (@var{dx1},@var{dy1}) and then to (@var{dx2},@var{dy2}), and so on.
11462 The current position is moved to the terminal point of the drawn curve.
11464 @item \D'f @var{n}'
11465 @cindex gray shading (@w{@code{\D'f @dots{}'}})
11466 @cindex shading filled objects (@w{@code{\D'f @dots{}'}})
11467 Set the shade of gray to be used for filling solid objects to@tie{}@var{n};
11468 @var{n}@tie{}must be an integer between 0 and@tie{}1000, where 0
11469 corresponds solid white and 1000 to solid black, and values in between
11470 correspond to intermediate shades of gray. This applies only to solid
11471 circles, solid ellipses, and solid polygons. By default, a level of
11474 Despite of being silly, the current point is moved horizontally to the
11475 right by@tie{}@var{n}.
11477 @cindex @w{@code{\D'f @dots{}'}} and horizontal resolution
11478 Don't use this command! It has the serious drawback that it will be
11479 always rounded to the next integer multiple of the horizontal resolution
11480 (the value of the @code{hor} keyword in the @file{DESC} file). Use
11481 @code{\M} (@pxref{Colors}) or @w{@code{\D'Fg @dots{}'}} instead.
11483 @item \D'p @var{dx1} @var{dy1} @var{dx2} @var{dy2} @dots{}'
11484 @cindex drawing a polygon (@w{@code{\D'p @dots{}'}})
11485 @cindex polygon, drawing (@w{@code{\D'p @dots{}'}})
11486 Draw a polygon from the current location to the relative position
11487 (@var{dx1},@var{dy1}) and then to (@var{dx2},@var{dy2}) and so on.
11488 When the specified data points are exhausted, a line is drawn back
11489 to the starting point. The current position is changed by adding the
11490 sum of all arguments with odd index to the actual horizontal position and
11491 the even ones to the vertical position.
11493 @item \D'P @var{dx1} @var{dy1} @var{dx2} @var{dy2} @dots{}'
11494 @cindex polygon, solid, drawing (@w{@code{\D'P @dots{}'}})
11495 @cindex drawing a solid polygon (@w{@code{\D'P @dots{}'}})
11496 @cindex solid polygon, drawing (@w{@code{\D'P @dots{}'}})
11497 Draw a solid polygon with the same parameters and behaviour as an
11498 outlined polygon. No outline is drawn.
11500 Here a better variant of the box macro to fill the box with some color.
11501 Note that the box must be drawn before the text since colors in
11502 @code{gtroff} are not transparent; the filled polygon would hide the
11509 \h'-.2m'\v'(.2m - \\n[rsb]u)'\
11511 \D'P 0 -(\\n[rst]u - \\n[rsb]u + .4m) \
11512 (\\n[@@wd]u + .4m) 0 \
11513 0 (\\n[rst]u - \\n[rsb]u + .4m) \
11514 -(\\n[@@wd]u + .4m) 0'\
11515 \h'.2m'\v'-(.2m - \\n[rsb]u)'\
11522 @item \D't @var{n}'
11523 @cindex line thickness (@w{@code{\D't @dots{}'}})
11524 @cindex thickness of lines (@w{@code{\D't @dots{}'}})
11525 Set the current line thickness to @var{n}@tie{}machine units. A value of
11526 zero selects the smallest available line thickness. A negative value
11527 makes the line thickness proportional to the current point size (this is
11528 the default behaviour of @acronym{AT&T} @code{troff}).
11530 Despite of being silly, the current point is moved horizontally to the
11531 right by@tie{}@var{n}.
11533 @item \D'F@var{scheme} @var{color_components}'
11534 @cindex unnamed fill colors (@code{\D'F@dots{}'})
11535 @cindex fill colors, unnamed (@code{\D'F@dots{}'})
11536 @cindex colors, fill, unnamed (@code{\D'F@dots{}'})
11537 Change current fill color. @var{scheme} is a single letter denoting the
11538 color scheme: @samp{r} (rgb), @samp{c} (cmy), @samp{k} (cmyk), @samp{g}
11539 (gray), or @samp{d} (default color). The color components use exactly
11540 the same syntax as in the @code{defcolor} request (@pxref{Colors}); the
11541 command @code{\D'Fd'} doesn't take an argument.
11543 @emph{No} position changing!
11549 \D'Fg .3' \" same gray as \D'f 700'
11550 \D'Fr #0000ff' \" blue
11554 @xref{Graphics Commands}.
11556 @Defesc {\\b, ', string, '}
11557 @cindex pile, glyph (@code{\b})
11558 @cindex glyph pile (@code{\b})
11559 @cindex stacking glyphs (@code{\b})
11560 @dfn{Pile} a sequence of glyphs vertically, and center it vertically
11561 on the current line. Use it to build large brackets and braces.
11563 Here an example how to create a large opening brace:
11566 \b'\[lt]\[bv]\[lk]\[bv]\[lb]'
11569 @cindex @code{\b}, limitations
11570 @cindex limitations of @code{\b} escape
11571 The first glyph is on the top, the last glyph in @var{string} is
11572 at the bottom. Note that @code{gtroff} separates the glyphs
11573 vertically by 1@dmn{m}, and the whole object is centered 0.5@dmn{m}
11574 above the current baseline; the largest glyph width is used as the
11575 width for the whole object. This rather unflexible positioning
11576 algorithm doesn't work with @option{-Tdvi} since the bracket pieces vary
11577 in height for this device. Instead, use the @code{eqn} preprocessor.
11579 @xref{Manipulating Spacing}, how to adjust the vertical spacing with
11580 the @code{\x} escape.
11584 @c =====================================================================
11586 @node Traps, Diversions, Drawing Requests, gtroff Reference
11590 @dfn{Traps} are locations, which, when reached, call a specified
11591 macro. These traps can occur at a given location on the page, at a
11592 given location in the current diversion, at a blank line,
11593 after a certain number of input lines, or at the end of input.
11595 @cindex planting a trap
11596 @cindex trap, planting
11597 Setting a trap is also called @dfn{planting}.
11598 @cindex trap, springing
11599 @cindex springing a trap
11600 It is also said that a trap is @dfn{sprung} if the associated macro
11604 * Page Location Traps::
11605 * Diversion Traps::
11606 * Input Line Traps::
11607 * Blank Line Traps::
11608 * End-of-input Traps::
11611 @c ---------------------------------------------------------------------
11613 @node Page Location Traps, Diversion Traps, Traps, Traps
11614 @subsection Page Location Traps
11615 @cindex page location traps
11616 @cindex traps, page location
11618 @dfn{Page location traps} perform an action when @code{gtroff}
11619 reaches or passes a certain vertical location on the page. Page
11620 location traps have a variety of purposes, including:
11624 setting headers and footers
11627 setting body text in multiple columns
11633 @DefreqList {vpt, flag}
11634 @DefregListEnd {.vpt}
11635 @cindex enabling vertical position traps (@code{vpt})
11636 @cindex vertical position traps, enabling (@code{vpt})
11637 @cindex vertical position trap enable register (@code{.vpt})
11638 Enable vertical position traps if @var{flag} is non-zero, or disables
11639 them otherwise. Vertical position traps are traps set by the @code{wh}
11640 or @code{dt} requests. Traps set by the @code{it} request are not
11641 vertical position traps. The parameter that controls whether vertical
11642 position traps are enabled is global. Initially vertical position traps
11643 are enabled. The current setting of this is available in the
11644 @code{.vpt} read-only number register.
11646 Note that a page can't be ejected if @code{vpt} is set to zero.
11649 @Defreq {wh, dist [@Var{macro}]}
11650 Set a page location trap. Non-negative values for @var{dist} set
11651 the trap relative to the top of the page; negative values set
11652 the trap relative to the bottom of the page. Default scaling
11653 indicator is @samp{v}.
11655 @var{macro} is the name of the macro to execute when the
11656 trap is sprung. If @var{macro} is missing, remove the first trap
11657 (if any) at @var{dist}.
11659 @cindex page headers
11660 @cindex page footers
11663 The following is a simple example of how many macro packages
11664 set headers and footers.
11667 .de hd \" Page header
11673 .de fo \" Page footer
11679 .wh 0 hd \" trap at top of the page
11680 .wh -1i fo \" trap one inch from bottom
11683 A trap at or below the bottom of the page is ignored; it can be made
11684 active by either moving it up or increasing the page length so that the
11685 trap is on the page.
11687 It is possible to have more than one trap at the same location; to do so,
11688 the traps must be defined at different locations, then moved together with
11689 the @code{ch} request; otherwise the second trap would replace the first
11690 one. Earlier defined traps hide later defined traps if moved to the same
11691 position (the many empty lines caused by the @code{bp} request are omitted
11692 in the following example):
11725 @cindex distance to next trap register (@code{.t})
11726 @cindex trap, distance, register (@code{.t})
11727 A read-only number register holding the distance to the next trap.
11729 If there are no traps between the current position and the bottom of the
11730 page, it contains the distance to the page bottom. In a diversion, the
11731 distance to the page bottom is infinite (the returned value is the biggest
11732 integer which can be represented in @code{groff}) if there are no diversion
11736 @Defreq {ch, macro [@Var{dist}]}
11737 @cindex changing trap location (@code{ch})
11738 @cindex trap, changing location (@code{ch})
11739 Change the location of a trap.
11740 The first argument is the name of the macro to be invoked at
11741 the trap, and the second argument is the new location for the trap
11742 (note that the parameters are specified in opposite order as in the
11743 @code{wh} request). This is useful for building up footnotes in a
11744 diversion to allow more space at the bottom of the page for them.
11746 Default scaling indicator for @var{dist} is @samp{v}. If @var{dist}
11747 is missing, the trap is removed.
11753 ... (simplified) footnote example ...
11759 The read-only number register @code{.ne} contains the amount of space
11760 that was needed in the last @code{ne} request that caused a trap to be
11761 sprung. Useful in conjunction with the @code{.trunc} register.
11762 @xref{Page Control}, for more information.
11764 Since the @code{.ne} register is only set by traps it doesn't make
11765 much sense to use it outside of trap macros.
11769 @cindex @code{ne} request, and the @code{.trunc} register
11770 @cindex truncated vertical space register (@code{.trunc})
11771 A read-only register containing the amount of vertical space truncated
11772 by the most recently sprung vertical position trap, or, if the trap was
11773 sprung by an @code{ne} request, minus the amount of vertical motion
11774 produced by the @code{ne} request. In other words, at the point a trap
11775 is sprung, it represents the difference of what the vertical position
11776 would have been but for the trap, and what the vertical position
11779 Since the @code{.trunc} register is only set by traps it doesn't make
11780 much sense to use it outside of trap macros.
11784 @cindex @code{bp} request, and traps (@code{.pe})
11785 @cindex traps, sprung by @code{bp} request (@code{.pe})
11786 @cindex page ejecting register (@code{.pe})
11787 A read-only register which is set to@tie{}1 while a page is ejected with
11788 the @code{bp} request (or by the end of input).
11790 Outside of traps this register is always zero. In the following example,
11791 only the second call to@tie{}@code{x} is caused by @code{bp}.
11812 @cindex diversions, and traps
11813 @cindex traps, and diversions
11814 An important fact to consider while designing macros is that diversions and
11815 traps do not interact normally. For example, if a trap invokes a header
11816 macro (while outputting a diversion) which tries to change the font on the
11817 current page, the effect will not be visible before the diversion has
11818 completely been printed (except for input protected with @code{\!} or
11819 @code{\?}) since the data in the diversion is already formatted. In most
11820 cases, this is not the expected behaviour.
11822 @c ---------------------------------------------------------------------
11824 @node Diversion Traps, Input Line Traps, Page Location Traps, Traps
11825 @subsection Diversion Traps
11826 @cindex diversion traps
11827 @cindex traps, diversion
11829 @Defreq {dt, [@Var{dist} @Var{macro}]}
11830 @cindex @code{.t} register, and diversions
11831 @cindex setting diversion trap (@code{dt})
11832 @cindex diversion trap, setting (@code{dt})
11833 @cindex trap, diversion, setting (@code{dt})
11834 Set a trap @emph{within} a diversion.
11835 @var{dist} is the location of the trap
11836 (identical to the @code{wh} request; default scaling indicator is
11837 @samp{v}) and @var{macro} is the name of the macro to be invoked.
11838 If called without arguments, the diversion trap is removed.
11840 Note that there exists only a single diversion trap.
11842 The number register @code{.t} still works within diversions.
11843 @xref{Diversions}, for more information.
11846 @c ---------------------------------------------------------------------
11848 @node Input Line Traps, Blank Line Traps, Diversion Traps, Traps
11849 @subsection Input Line Traps
11850 @cindex input line traps
11851 @cindex traps, input line
11853 @DefreqList {it, n macro}
11854 @DefreqItem {itc, n macro}
11855 @cindex setting input line trap (@code{it})
11856 @cindex input line trap, setting (@code{it})
11857 @cindex trap, input line, setting (@code{it})
11858 Set an input line trap.
11859 @var{n}@tie{}is the number of lines of input which may be read before
11860 springing the trap, @var{macro} is the macro to be invoked.
11861 Request lines are not counted as input lines.
11863 For example, one possible use is to have a macro which prints the
11864 next @var{n}@tie{}lines in a bold font.
11877 @cindex input line traps and interrupted lines (@code{itc})
11878 @cindex interrupted lines and input line traps (@code{itc})
11879 @cindex traps, input line, and interrupted lines (@code{itc})
11880 @cindex lines, interrupted, and input line traps (@code{itc})
11881 The @code{itc} request is identical
11882 except that an interrupted text line (ending with @code{\c})
11883 is not counted as a separate line.
11885 Both requests are associated with the current environment
11886 (@pxref{Environments}); switching to another environment disables the
11887 current input trap, and going back reactivates it, restoring the number
11888 of already processed lines.
11891 @c ---------------------------------------------------------------------
11893 @node Blank Line Traps, End-of-input Traps, Input Line Traps, Traps
11894 @subsection Blank Line Traps
11895 @cindex blank line traps
11896 @cindex traps, blank line
11898 @Defreq {blm, macro}
11899 @cindex blank line macro (@code{blm})
11900 Set a blank line trap.
11901 @code{gtroff} executes @var{macro} when it encounters a blank line in
11905 @c ---------------------------------------------------------------------
11907 @node End-of-input Traps, , Blank Line Traps, Traps
11908 @subsection End-of-input Traps
11909 @cindex end-of-input traps
11910 @cindex traps, end-of-input
11912 @Defreq {em, macro}
11913 @cindex setting end-of-input trap (@code{em})
11914 @cindex end-of-input trap, setting (@code{em})
11915 @cindex trap, end-of-input, setting (@code{em})
11916 @cindex end-of-input macro (@code{em})
11917 @cindex macro, end-of-input (@code{em})
11918 Set a trap at the end of input. @var{macro} is executed after the
11919 last line of the input file has been processed.
11921 For example, if the document had to have a section at the bottom of the
11922 last page for someone to approve it, the @code{em} request could be
11928 . sp |(\\n[.t] - 6v)
11942 @c =====================================================================
11944 @node Diversions, Environments, Traps, gtroff Reference
11945 @section Diversions
11948 In @code{gtroff} it is possible to @dfn{divert} text into a named
11949 storage area. Due to the similarity to defining macros it is sometimes
11950 said to be stored in a macro. This is used for saving text for output
11951 at a later time, which is useful for keeping blocks of text on the same
11952 page, footnotes, tables of contents, and indices.
11954 @cindex top-level diversion
11955 @cindex diversion, top-level
11956 For orthogonality it is said that @code{gtroff} is in the @dfn{top-level
11957 diversion} if no diversion is active (i.e., the data is diverted to the
11960 @DefreqList {di, macro}
11961 @DefreqListEnd {da, macro}
11962 @cindex beginning diversion (@code{di})
11963 @cindex diversion, beginning (@code{di})
11964 @cindex ending diversion (@code{di})
11965 @cindex diversion, ending (@code{di})
11966 @cindex appending to a diversion (@code{da})
11967 @cindex diversion, appending (@code{da})
11968 Begin a diversion. Like the @code{de}
11969 request, it takes an argument of a macro name to divert subsequent text
11970 into. The @code{da} macro appends to an existing diversion.
11972 @code{di} or @code{da} without an argument ends the diversion.
11975 @DefreqList {box, macro}
11976 @DefreqListEnd {boxa, macro}
11977 Begin (or appends to) a diversion like the
11978 @code{di} and @code{da} requests.
11979 The difference is that @code{box} and @code{boxa}
11980 do not include a partially-filled line in the diversion.
11992 @result{} Before the box. After the box.
11994 @result{} In the box.
12001 Before the diversion.
12006 After the diversion.
12008 @result{} After the diversion.
12010 @result{} Before the diversion. In the diversion.
12013 @code{box} or @code{boxa} without an argument ends the diversion.
12017 @DefregListEnd {.d}
12018 @cindex @code{nl} register, and @code{.d}
12019 @cindex nested diversions
12020 @cindex diversion, nested
12021 @cindex diversion name register (@code{.z})
12022 @cindex vertical position in diversion register (@code{.d})
12023 @cindex position, vertical, in diversion, register (@code{.d})
12024 @cindex diversion, vertical position in, register (@code{.d})
12025 Diversions may be nested. The read-only number register @code{.z}
12026 contains the name of the current diversion (this is a string-valued
12027 register). The read-only number register @code{.d} contains the current
12028 vertical place in the diversion. If not in a diversion it is the same
12029 as register @code{nl}.
12033 @cindex high-water mark register (@code{.h})
12034 @cindex mark, high-water, register (@code{.h})
12035 @cindex position of lowest text line (@code{.h})
12036 @cindex text line, position of lowest (@code{.h})
12037 The @dfn{high-water mark} on the current page. It corresponds to the
12038 text baseline of the lowest line on the page. This is a read-only
12042 .tm .h==\n[.h], nl==\n[nl]
12043 @result{} .h==0, nl==-1
12047 .tm .h==\n[.h], nl==\n[nl]
12048 @result{} .h==40, nl==120
12051 @cindex @code{.h} register, difference to @code{nl}
12052 @cindex @code{nl} register, difference to @code{.h}
12054 As can be seen in the previous example, empty lines are not considered
12055 in the return value of the @code{.h} register.
12059 @DefregListEnd {dl}
12060 @cindex @code{dn} register, and @code{da} (@code{boxa})
12061 @cindex @code{dl} register, and @code{da} (@code{boxa})
12062 @cindex @code{da} request, and @code{dn} (@code{dl})
12063 @cindex @code{boxa} request, and @code{dn} (@code{dl})
12064 After completing a diversion, the read-write number registers @code{dn}
12065 and @code{dl} contain the vertical and horizontal size of the diversion.
12066 Note that only the just processed lines are counted: For the computation
12067 of @code{dn} and @code{dl}, the requests @code{da} and @code{boxa} are
12068 handled as if @code{di} and @code{box} had been used -- lines which have
12069 been already stored in a macro are not taken into account.
12072 .\" Center text both horizontally & vertically
12074 .\" Enclose macro definitions in .eo and .ec
12075 .\" to avoid the doubling of the backslash
12077 .\" macro .(c starts centering mode
12088 .\" macro .)c terminates centering mode
12093 . nr @@s (((\n[.t]u - \n[dn]u) / 2u) - 1v)
12105 .\" End of macro definitions, restore escape mechanism
12110 @DefescList {\\!, , , }
12111 @DefescListEnd {\\?, , anything, \\?}
12112 @cindex transparent output (@code{\!}, @code{\?})
12113 @cindex output, transparent (@code{\!}, @code{\?})
12114 Prevent requests, macros, and escapes from being
12115 interpreted when read into a diversion. Both escapes take the given text
12116 and @dfn{transparently} embed it into the diversion. This is useful for
12117 macros which shouldn't be invoked until the diverted text is actually
12120 The @code{\!} escape transparently embeds text up to
12121 and including the end of the line.
12122 The @code{\?} escape transparently embeds text until the next
12123 occurrence of the @code{\?} escape. Example:
12130 @var{anything} may not contain newlines; use @code{\!} to embed
12131 newlines in a diversion. The escape sequence @code{\?} is also
12132 recognized in copy mode and turned into a single internal code; it is
12133 this code that terminates @var{anything}. Thus the following example
12140 \?\\?\\\\?\\\\\\\\nx\\\\?\\?\?
12154 Both escapes read the data in copy mode.
12156 @cindex @code{\!}, in top-level diversion
12157 @cindex top-level diversion, and @code{\!}
12158 @cindex diversion, top-level, and @code{\!}
12159 If @code{\!} is used in the top-level diversion, its argument is
12160 directly embedded into the @code{gtroff} intermediate output. This can
12161 be used for example to control a postprocessor which processes the data
12162 before it is sent to the device driver.
12164 @cindex @code{\?}, in top-level diversion
12165 @cindex top-level diversion, and @code{\?}
12166 @cindex diversion, top-level, and @code{\?}
12167 The @code{\?} escape used in the top-level diversion produces no output
12168 at all; its argument is simply ignored.
12171 @cindex @code{\!}, and @code{output}
12172 @cindex @code{output} request, and @code{\!}
12173 @Defreq {output, string}
12174 Emit @var{string} directly to the @code{gtroff} intermediate output
12175 (subject to copy-mode interpretation); this is similar to @code{\!} used
12176 at the top level. An initial double quote in @var{string} is stripped off
12177 to allow initial blanks.
12179 This request can't be used before the first page has started -- if you get
12180 an error, simply insert @code{.br} before the @code{output} request.
12182 Without argument, @code{output} is ignored.
12184 Use with caution! It is normally only needed for mark-up used by a
12185 postprocessor which does something with the output before sending it to
12186 the output device, filtering out @var{string} again.
12189 @Defreq {asciify, div}
12190 @cindex unformatting diversions (@code{asciify})
12191 @cindex diversion, unformatting (@code{asciify})
12192 @cindex @code{trin} request, and @code{asciify}
12193 @dfn{Unformat} the diversion specified by @var{div}
12194 in such a way that @acronym{ASCII} characters, characters translated with
12195 the @code{trin} request, space characters, and some escape sequences that
12196 were formatted and diverted are treated like ordinary input
12197 characters when the diversion is reread. It can be also used for gross
12198 hacks; for example, the following sets register@tie{}@code{n} to@tie{}1.
12211 @xref{Copy-in Mode}.
12214 @Defreq {unformat, div}
12215 Like @code{asciify}, unformat the specified diversion.
12216 However, @code{unformat} only unformats spaces and tabs
12218 Unformatted tabs are treated as input tokens,
12219 and spaces are stretchable again.
12221 The vertical size of lines is not preserved; glyph information (font,
12222 font size, space width, etc.)@: is retained.
12226 @c =====================================================================
12228 @node Environments, Suppressing output, Diversions, gtroff Reference
12229 @section Environments
12230 @cindex environments
12232 It happens frequently that some text should be printed in a certain
12233 format regardless of what may be in effect at the time, for example, in
12234 a trap invoked macro to print headers and footers. To solve this
12235 @code{gtroff} processes text in @dfn{environments}. An
12236 environment contains most of the parameters that control text
12237 processing. It is possible to switch amongst these environments; by
12238 default @code{gtroff} processes text in environment@tie{}0. The
12239 following is the information kept in an environment.
12243 font parameters (size, family, style, glyph height and slant, space
12244 and sentence space size)
12247 page parameters (line length, title length, vertical spacing,
12248 line spacing, indentation, line numbering, centering, right-justifying,
12249 underlining, hyphenation data)
12252 fill and adjust mode
12255 tab stops, tab and leader characters, escape character,
12256 no-break and hyphen indicators, margin character data
12259 partially collected lines
12265 drawing and fill colours
12268 These environments may be given arbitrary names (see @ref{Identifiers},
12269 for more info). Old versions of @code{troff} only had environments
12270 named @samp{0}, @samp{1}, and @samp{2}.
12272 @DefreqList {ev, [@Var{env}]}
12273 @DefregListEnd {.ev}
12274 @cindex switching environments (@code{ev})
12275 @cindex environment, switching (@code{ev})
12276 @cindex environment number/name register (@code{.ev})
12277 Switch to another environment. The argument @var{env} is the name of
12278 the environment to switch to. With no argument, @code{gtroff} switches
12279 back to the previous environment. There is no limit on the number of
12280 named environments; they are created the first time that they are
12281 referenced. The @code{.ev} read-only register contains the name or
12282 number of the current environment. This is a string-valued register.
12284 Note that a call to @code{ev} (with argument) pushes the previously
12285 active environment onto a stack. If, say, environments @samp{foo},
12286 @samp{bar}, and @samp{zap} are called (in that order), the first
12287 @code{ev} request without parameter switches back to environment
12288 @samp{bar} (which is popped off the stack), and a second call
12289 switches back to environment @samp{foo}.
12291 Here is an example:
12304 \(dg Note the large, friendly letters.
12310 @cindex copying environment (@code{evc})
12311 @cindex environment, copying (@code{evc})
12312 Copy the environment @var{env} into the current environment.
12314 The following environment data is not copied:
12318 Partially filled lines.
12321 The status whether the previous line was interrupted.
12324 The number of lines still to center, or to right-justify, or to underline
12325 (with or without underlined spaces); they are set to zero.
12328 The status whether a temporary indent is active.
12331 Input traps and its associated data.
12334 Line numbering mode is disabled; it can be reactivated with
12338 The number of consecutive hyphenated lines (set to zero).
12345 @DefregListEnd {.csk}
12346 @cindex environment, dimensions of last glyph (@code{.w}, @code{.cht}, @code{.cdp}, @code{.csk})
12347 @cindex width, of last glyph (@code{.w})
12348 @cindex height, of last glyph (@code{.cht})
12349 @cindex depth, of last glyph (@code{.cdp})
12350 @cindex skew, of last glyph (@code{.csk})
12351 @cindex last glyph, dimensions (@code{.w}, @code{.cht}, @code{.cdp}, @code{.csk})
12352 @cindex glyph, last, dimensions (@code{.w}, @code{.cht}, @code{.cdp}, @code{.csk})
12353 The @code{\n[.w]} register contains the
12354 width of the last glyph added to the current environment.
12356 The @code{\n[.cht]} register contains the
12357 height of the last glyph added to the current environment.
12359 The @code{\n[.cdp]} register contains the
12360 depth of the last glyph added to the current environment.
12361 It is positive for glyphs extending below the baseline.
12363 The @code{\n[.csk]} register contains the
12364 @dfn{skew} (how far to the right of the glyph's center
12365 that @code{gtroff} should place an accent)
12366 of the last glyph added to the current environment.
12370 @cindex environment, previous line length (@code{.n})
12371 @cindex line length, previous (@code{.n})
12372 @cindex length of previous line (@code{.n})
12373 @cindex previous line length (@code{.n})
12374 The @code{\n[.n]} register contains the
12375 length of the previous output line in the current environment.
12379 @c =====================================================================
12381 @node Suppressing output, Colors, Environments, gtroff Reference
12382 @section Suppressing output
12384 @Defesc {\\O, , num, }
12385 @cindex suppressing output (@code{\O})
12386 @cindex output, suppressing (@code{\O})
12387 Disable or enable output depending on the value of @var{num}:
12391 Disable any glyphs from being emitted to the device driver, provided that
12392 the escape occurs at the outer level (see @code{\O[3]} and @code{\O[4]}).
12393 Motion is not suppressed so effectively @code{\O[0]} means @emph{pen up}.
12396 Enable output of glyphs, provided that the escape occurs at the outer
12404 @code{\O0} and @code{\O1} also reset the four registers @samp{opminx},
12405 @samp{opminy}, @samp{opmaxx}, and @samp{opmaxy} to @minus{}1.
12406 @xref{Register Index}. These four registers mark the top left and
12407 bottom right hand corners of a box which encompasses all written glyphs.
12409 For example the input text:
12412 Hello \O[0]world \O[1]this is a test.
12416 produces the following output:
12419 Hello this is a test.
12424 Provided that the escape occurs at the outer level, enable output of
12425 glyphs and also write out to @code{stderr} the page number and four
12426 registers encompassing the glyphs previously written since the last call
12430 Begin a nesting level. At start-up, @code{gtroff} is at outer level.
12433 End a nesting level.
12435 @item \O[5@var{P}@var{filename}]
12436 This escape is @code{grohtml} specific. Provided that this escape
12437 occurs at the outer nesting level write the @code{filename} to
12438 @code{stderr}. The position of the image, @var{P}, must be specified
12439 and must be one of @code{l}, @code{r}, @code{c}, or@tie{}@code{i} (left,
12440 right, centered, inline). @var{filename} will be associated with the
12441 production of the next inline image.
12445 @c =====================================================================
12447 @node Colors, I/O, Suppressing output, gtroff Reference
12451 @DefreqList {color, [@Var{n}]}
12452 @DefregListEnd {.color}
12453 If @var{n} is missing or non-zero, activate colors (this is the default);
12454 otherwise, turn it off.
12456 The read-only number register @code{.color} is@tie{}1 if colors are active,
12459 Internally, @code{color} sets a global flag; it does not produce a token.
12460 Similar to the @code{cp} request, you should use it at the beginning of
12461 your document to control color output.
12463 Colors can be also turned off with the @option{-c} command line option.
12466 @Defreq {defcolor, ident scheme color_components}
12467 Define color with name @var{ident}. @var{scheme} can be one of the
12468 following values: @code{rgb} (three components), @code{cmy} (three
12469 components), @code{cmyk} (four components), and @code{gray} or
12470 @code{grey} (one component).
12472 @cindex default color
12473 @cindex color, default
12474 Color components can be given either as a hexadecimal string or as
12475 positive decimal integers in the range 0--65535. A hexadecimal string
12476 contains all color components concatenated. It must start with either
12477 @code{#} or @code{##}; the former specifies hex values in the range
12478 0--255 (which are internally multiplied by@tie{}257), the latter in the
12479 range 0--65535. Examples: @code{#FFC0CB} (pink), @code{##ffff0000ffff}
12480 (magenta). The default color name @c{default} can't be redefined; its
12481 value is device-specific (usually black). It is possible that the
12482 default color for @code{\m} and @code{\M} is not identical.
12484 @cindex @code{f} unit, and colors
12485 @cindex unit, @code{f}, and colors
12486 A new scaling indicator@tie{}@code{f} has been introduced which multiplies
12487 its value by 65536; this makes it convenient to specify color components
12488 as fractions in the range 0 to@tie{}1 (1f equals 65536u). Example:
12491 .defcolor darkgreen rgb 0.1f 0.5f 0.2f
12494 Note that @code{f} is the default scaling indicator for the
12495 @code{defcolor} request, thus the above statement is equivalent to
12498 .defcolor darkgreen rgb 0.1 0.5 0.2
12502 @DefreqList {gcolor, [@Var{color}]}
12503 @DefescItem {\\m, , c, }
12504 @DefescItem {\\m, @Lparen{}, co, }
12505 @DefescItem {\\m, @Lbrack{}, color, @Rbrack{}}
12506 @DefregListEnd {.m}
12507 Set (glyph) drawing color. The following examples show how to turn the
12508 next four words red.
12514 and these words are in black.
12518 \m[red]these are in red\m[] and these words are in black.
12521 The escape @code{\m[]} returns to the previous color, as does a call to
12522 @code{gcolor} without an argument.
12524 @cindex drawing color name register (@code{.m})
12525 @cindex name, drawing color, register (@code{.m})
12526 @cindex color name, drawing, register (@code{.m})
12527 The name of the current drawing color is available in the read-only,
12528 string-valued number register @samp{.m}.
12530 The drawing color is associated with the current environment
12531 (@pxref{Environments}).
12533 Note that @code{\m} doesn't produce an input token in @code{gtroff}.
12534 As a consequence, it can be used in requests like @code{mc} (which
12535 expects a single character as an argument) to change the color on
12543 @DefreqList {fcolor, [@Var{color}]}
12544 @DefescItem {\\M, , c, }
12545 @DefescItem {\\M, @Lparen{}, co, }
12546 @DefescItem {\\M, @Lbrack{}, color, @Rbrack{}}
12547 @DefregListEnd {.M}
12548 Set fill (background) color for filled objects drawn with the
12549 @code{\D'@dots{}'} commands.
12551 A red ellipse can be created with the following code:
12554 \M[red]\h'0.5i'\D'E 2i 1i'\M[]
12557 The escape @code{\M[]} returns to the previous fill color, as does a call to
12558 @code{fcolor} without an argument.
12560 @cindex background color name register (@code{.M})
12561 @cindex name, background color, register (@code{.M})
12562 @cindex color name, background, register (@code{.M})
12563 @cindex fill color name register (@code{.M})
12564 @cindex name, fill color, register (@code{.M})
12565 @cindex color name, fill, register (@code{.M})
12566 The name of the current fill (background) color is available in the
12567 read-only, string-valued number register @samp{.M}.
12569 The fill color is associated with the current environment
12570 (@pxref{Environments}).
12572 Note that @code{\M} doesn't produce an input token in @code{gtroff}.
12576 @c =====================================================================
12578 @node I/O, Postprocessor Access, Colors, gtroff Reference
12581 @cindex input and output requests
12582 @cindex requests for input and output
12583 @cindex output and input requests
12585 @code{gtroff} has several requests for including files:
12588 @cindex including a file (@code{so})
12589 @cindex file, inclusion (@code{so})
12590 Read in the specified @var{file} and
12591 includes it in place of the @code{so} request. This is quite useful for
12592 large documents, e.g.@: keeping each chapter in a separate file.
12593 @xref{gsoelim}, for more information.
12595 Since @code{gtroff} replaces the @code{so} request with the contents
12596 of @code{file}, it makes a difference whether the data is terminated with
12597 a newline or not: Assuming that file @file{xxx} contains the word
12598 @samp{foo} without a final newline, this
12607 yields @samp{This is foobar}.
12609 The search path for @var{file} can be controlled with the @option{-I} command
12613 @Defreq {pso, command}
12614 Read the standard output from the specified @var{command}
12615 and includes it in place of the @code{pso} request.
12618 @cindex mode, safer
12619 @cindex unsafe mode
12620 @cindex mode, unsafe
12621 This request causes an error if used in safer mode (which is the default).
12622 Use @code{groff}'s or @code{troff}'s @option{-U} option to activate unsafe
12625 The comment regarding a final newline for the @code{so} request is valid
12626 for @code{pso} also.
12629 @Defreq {mso, file}
12630 Identical to the @code{so} request except that @code{gtroff} searches for
12631 the specified @var{file} in the same directories as macro files for the
12632 the @option{-m} command line option. If the file name to be included
12633 has the form @file{@var{name}.tmac} and it isn't found, @code{mso} tries
12634 to include @file{tmac.@var{name}} and vice versa.
12637 @DefreqList {trf, file}
12638 @DefreqListEnd {cf, file}
12639 @cindex transparent output (@code{cf}, @code{trf})
12640 @cindex output, transparent (@code{cf}, @code{trf})
12641 Transparently output the contents of @var{file}. Each line is output
12642 as if it were preceded by @code{\!}; however, the lines are not subject
12643 to copy mode interpretation. If the file does not end with a newline,
12644 then a newline is added (@code{trf} only). For example, to define a
12645 macro@tie{}@code{x} containing the contents of file@tie{}@file{f}, use
12653 Both @code{trf} and @code{cf}, when used in a diversion,
12654 embeds an object in the diversion which, when reread, causes the
12655 contents of @var{file} to be transparently copied through to the
12656 output. In @acronym{UNIX} @code{troff}, the contents of @var{file}
12657 is immediately copied through to the output regardless of whether there
12658 is a current diversion; this behaviour is so anomalous that it must be
12661 @cindex @code{trf} request, and invalid characters
12662 @cindex characters, invalid for @code{trf} request
12663 @cindex invalid characters for @code{trf} request
12664 While @code{cf} copies the contents of @var{file} completely unprocessed,
12665 @code{trf} disallows characters such as NUL that are not valid
12666 @code{gtroff} input characters (@pxref{Identifiers}).
12668 Both requests cause a line break.
12671 @Defreq {nx, [@Var{file}]}
12672 @cindex processing next file (@code{nx})
12673 @cindex file, processing next (@code{nx})
12674 @cindex next file, processing (@code{nx})
12675 Force @code{gtroff} to continue processing of
12676 the file specified as an argument. If no argument is given, immediately
12677 jump to the end of file.
12680 @Defreq {rd, [@Var{prompt} [@Var{arg1} @Var{arg2} @dots{}]]}
12681 @cindex reading from standard input (@code{rd})
12682 @cindex standard input, reading from (@code{rd})
12683 @cindex input, standard, reading from (@code{rd})
12684 Read from standard input, and include what is read as though it
12685 were part of the input file. Text is read until a blank line
12688 If standard input is a TTY input device (keyboard), write @var{prompt}
12689 to standard error, followed by a colon (or send BEL for a beep if no
12690 argument is given).
12692 Arguments after @var{prompt} are available for the input. For example,
12699 with the input @w{@samp{This is \$2.}} prints
12706 @cindex form letters
12707 @cindex letters, form
12708 Using the @code{nx} and @code{rd} requests,
12709 it is easy to set up form letters. The form
12710 letter template is constructed like this, putting the following lines
12711 into a file called @file{repeat.let}:
12727 @cindex @code{ex} request, used with @code{nx} and @code{rd}
12729 When this is run, a file containing the following lines should be
12730 redirected in. Note that requests included in this file are executed
12731 as though they were part of the form letter. The last block of input
12732 is the @code{ex} request which tells @code{groff} to stop processing. If
12733 this was not there, @code{groff} would not know when to stop.
12737 708 NW 19th Av., #202
12744 San Diego, CA 92103
12752 Pipe the output of @code{gtroff} to the shell command(s)
12753 specified by @var{pipe}. This request must occur before
12754 @code{gtroff} has a chance to print anything.
12757 @cindex mode, safer
12758 @cindex unsafe mode
12759 @cindex mode, unsafe
12760 @code{pi} causes an error if used in safer mode (which is the default).
12761 Use @code{groff}'s or @code{troff}'s @option{-U} option to activate unsafe
12764 Multiple calls to @code{pi} are allowed, acting as a chain. For example,
12772 is the same as @w{@samp{.pi foo | bar}}.
12774 @cindex @code{groff}, and @code{pi} request
12775 @cindex @code{pi} request, and @code{groff}
12776 Note that the intermediate output format of @code{gtroff} is piped to
12777 the specified commands. Consequently, calling @code{groff} without the
12778 @option{-Z} option normally causes a fatal error.
12781 @DefreqList {sy, cmds}
12782 @DefregListEnd {systat}
12783 Execute the shell command(s) specified by @var{cmds}. The output is not
12784 saved anyplace, so it is up to the user to do so.
12787 @cindex mode, safer
12788 @cindex unsafe mode
12789 @cindex mode, unsafe
12790 This request causes an error if used in safer mode (which is the default).
12791 Use @code{groff}'s or @code{troff}'s @option{-U} option to activate unsafe
12794 For example, the following code fragment introduces the current time into a
12797 @cindex time, current
12798 @cindex current time
12801 .sy perl -e 'printf ".nr H %d\\n.nr M %d\\n.nr S %d\\n",\
12802 (localtime(time))[2,1,0]' > /tmp/x\n[$$]
12804 .sy rm /tmp/x\n[$$]
12809 Note that this works by having the @code{perl} script (run by @code{sy})
12810 print out the @code{nr} requests which set the number registers
12811 @code{H}, @code{M}, and @code{S}, and then reads those commands in with
12812 the @code{so} request.
12814 For most practical purposes, the number registers @code{seconds},
12815 @code{minutes}, and @code{hours} which are initialized at start-up of
12816 @code{gtroff} should be sufficient. Use the @code{af} request to get a
12823 \n[hours]:\n[minutes]:\n[seconds]
12826 @cindex @code{system()} return value register (@code{systat})
12827 The @code{systat} read-write number register contains the return value
12828 of the @code{system()} function executed by the last @code{sy} request.
12831 @DefreqList {open, stream file}
12832 @DefreqListEnd {opena, stream file}
12833 @cindex opening file (@code{open})
12834 @cindex file, opening (@code{open})
12835 @cindex appending to a file (@code{opena})
12836 @cindex file, appending to (@code{opena})
12837 Open the specified @var{file} for writing and
12838 associates the specified @var{stream} with it.
12840 The @code{opena} request is like @code{open}, but if the file exists,
12841 append to it instead of truncating it.
12844 @cindex mode, safer
12845 @cindex unsafe mode
12846 @cindex mode, unsafe
12847 Both @code{open} and @code{opena} cause an error if used in safer mode
12848 (which is the default). Use @code{groff}'s or @code{troff}'s @option{-U}
12849 option to activate unsafe mode.
12852 @DefreqList {write, stream data}
12853 @DefreqListEnd {writec, stream data}
12854 @cindex copy-in mode, and @code{write} requests
12855 @cindex mode, copy-in, and @code{write} requests
12856 @cindex writing to file (@code{write})
12857 @cindex file, writing to (@code{write})
12858 Write to the file associated with the specified @var{stream}.
12859 The stream must previously have
12860 been the subject of an open request. The remainder of the line is
12861 interpreted as the @code{ds} request reads its second argument: A
12862 leading @samp{"} is stripped, and it is read in copy-in mode.
12864 The @code{writec} request is like @code{write}, but only
12865 @code{write} appends a newline to the data.
12868 @Defreq {writem, stream xx}
12869 @cindex @code{asciify} request, and @code{writem}
12870 Write the contents of the macro or string @var{xx}
12871 to the file associated with the specified @var{stream}.
12873 @var{xx} is read in copy mode, i.e., already formatted elements are
12874 ignored. Consequently, diversions must be unformatted with the
12875 @code{asciify} request before calling @code{writem}. Usually, this
12876 means a loss of information.
12879 @Defreq {close, stream}
12880 @cindex closing file (@code{close})
12881 @cindex file, closing (@code{close})
12882 Close the specified @var{stream};
12883 the stream is no longer an acceptable argument to the
12884 @code{write} request.
12886 Here a simple macro to write an index entry.
12892 . write idx \\n[%] \\$*
12901 @DefescList {\\V, , e, }
12902 @DefescItem {\\V, @Lparen{}, ev, }
12903 @DefescListEnd {\\V, @Lbrack{}, env, @Rbrack{}}
12904 Interpolate the contents of the specified environment variable
12905 @var{env} (one-character name@tie{}@var{e}, two-character name @var{ev})
12906 as returned by the function @code{getenv}. @code{\V} is interpreted
12911 @c =====================================================================
12913 @node Postprocessor Access, Miscellaneous, I/O, gtroff Reference
12914 @section Postprocessor Access
12915 @cindex postprocessor access
12916 @cindex access of postprocessor
12918 There are two escapes which give information directly to the
12919 postprocessor. This is particularly useful for embedding
12920 @sc{PostScript} into the final document.
12922 @Defesc {\\X, ', xxx, '}
12923 Embeds its argument into the @code{gtroff}
12924 output preceded with @w{@samp{x X}}.
12926 @cindex @code{\&}, in @code{\X}
12927 @cindex @code{\)}, in @code{\X}
12928 @cindex @code{\%}, in @code{\X}
12930 @cindex @code{\:}, in @code{\X}
12933 @cindex @code{\@r{<colon>}}, in @code{\X}
12935 The escapes @code{\&}, @code{\)}, @code{\%}, and @code{\:} are ignored
12936 within @code{\X}, @w{@samp{\ }} and @code{\~} are converted to single
12937 space characters. All other escapes (except @code{\\} which produces a
12938 backslash) cause an error.
12940 @kindex use_charnames_in_special
12941 @pindex DESC@r{, and @code{use_charnames_in_special}}
12942 @cindex @code{\X}, and special characters
12943 If the @samp{use_charnames_in_special} keyword is set in the @file{DESC}
12944 file, special characters no longer cause an error; the name @var{xx} is
12945 represented as @samp{\(@var{xx})} in the @w{@samp{x X}} output command.
12946 Additionally, the backslash is represented as @code{\\}.
12948 @samp{use_charnames_in_special} is currently used by @code{grohtml} only.
12951 @DefescList {\\Y, , n, }
12952 @DefescItem {\\Y, @Lparen{}, nm, }
12953 @DefescListEnd {\\Y, @Lbrack{}, name, @Rbrack{}}
12954 This is approximately equivalent to @samp{\X'\*[@var{name}]'}
12955 (one-character name@tie{}@var{n}, two-character name @var{nm}).
12956 However, the contents of the string or macro @var{name} are not
12957 interpreted; also it is permitted for @var{name} to have been defined
12958 as a macro and thus contain newlines (it is not permitted for the
12959 argument to @code{\X} to contain newlines). The inclusion of
12960 newlines requires an extension to the @acronym{UNIX} @code{troff}
12961 output format, and confuses drivers that do not know about this
12962 extension (@pxref{Device Control Commands}).
12965 @xref{Output Devices}.
12968 @c =====================================================================
12970 @node Miscellaneous, Gtroff Internals, Postprocessor Access, gtroff Reference
12971 @section Miscellaneous
12973 This section documents parts of @code{gtroff} which cannot (yet) be
12974 categorized elsewhere in this manual.
12976 @Defreq {nm, [@Var{start} [@Var{inc} [@Var{space} [@Var{indent}]]]]}
12977 @cindex printing line numbers (@code{nm})
12978 @cindex line numbers, printing (@code{nm})
12979 @cindex numbers, line, printing (@code{nm})
12980 Print line numbers.
12981 @var{start} is the line number of the @emph{next}
12982 output line. @var{inc} indicates which line numbers are printed.
12983 For example, the value@tie{}5 means to emit only line numbers which
12984 are multiples of@tie{}5; this defaults to@tie{}1. @var{space} is the
12985 space to be left between the number and the text; this defaults to
12986 one digit space. The fourth argument is the indentation of the line
12987 numbers, defaulting to zero. Both @var{space} and @var{indent} are
12988 given as multiples of digit spaces; they can be negative also.
12989 Without any arguments, line numbers are turned off.
12991 @code{gtroff} reserves three digit spaces for the line number (which is
12992 printed right-justified) plus the amount given by @var{indent}; the
12993 output lines are concatenated to the line numbers, separated by
12994 @var{space}, and @emph{without} reducing the line length. Depending
12995 on the value of the horizontal page offset (as set with the
12996 @code{po} request), line numbers which are longer than the reserved
12997 space stick out to the left, or the whole line is moved to the right.
12999 Parameters corresponding to missing arguments are not changed; any
13000 non-digit argument (to be more precise, any argument starting with a
13001 character valid as a delimiter for identifiers) is also treated as
13004 If line numbering has been disabled with a call to @code{nm} without
13005 an argument, it can be reactivated with @samp{.nm +0}, using the
13006 previously active line numbering parameters.
13008 The parameters of @code{nm} are associated with the current environment
13009 (@pxref{Environments}). The current output line number is available
13010 in the number register @code{ln}.
13015 This test shows how line numbering works with groff.
13017 This test shows how line numbering works with groff.
13021 This test shows how line numbering works with groff.
13023 This test shows how line numbering works with groff.
13027 And here the result:
13030 This test shows how
13031 line numbering works
13032 999 with groff. This
13033 1000 test shows how line
13034 1001 numbering works with
13036 This test shows how
13039 This test shows how
13040 1005 line numbering
13045 @Defreq {nn, [@Var{skip}]}
13046 Temporarily turn off line numbering. The argument is the number
13047 of lines not to be numbered; this defaults to@tie{}1.
13050 @Defreq {mc, glyph [@Var{dist}]}
13051 @cindex margin glyph (@code{mc})
13052 @cindex glyph, for margins (@code{mc})
13053 Print a @dfn{margin character} to the right of the
13054 text.@footnote{@dfn{Margin character} is a misnomer since it is an
13055 output glyph.} The first argument is the glyph to be
13056 printed. The second argument is the distance away from the right
13057 margin. If missing, the previously set value is used; default is
13058 10@dmn{pt}). For text lines that are too long (that is, longer than
13059 the text length plus @var{dist}), the margin character is directly
13060 appended to the lines.
13062 With no arguments the margin character is turned off.
13063 If this occurs before a break, no margin character is printed.
13065 For compatibility with @acronym{AT&T} @code{troff}, a call to @code{mc}
13066 to set the margin character can't be undone immediately; at least one
13067 line gets a margin character. Thus
13086 @cindex @code{tl} request, and @code{mc}
13087 For empty lines and lines produced by the @code{tl} request no margin
13088 character is emitted.
13090 The margin character is associated with the current environment
13091 (@pxref{Environments}).
13095 This is quite useful for indicating text that has changed, and, in fact,
13096 there are programs available for doing this (they are called
13097 @code{nrchbar} and @code{changebar} and can be found in any
13098 @samp{comp.sources.unix} archive).
13103 This paragraph is highlighted with a margin
13106 Note that vertical space isn't marked.
13110 But we can fake it with `\&'.
13116 This paragraph is highlighted |
13117 with a margin character. |
13119 Note that vertical space isn't |
13122 But we can fake it with `\&'. |
13126 @DefreqList {psbb, filename}
13130 @DefregListEnd {ury}
13131 @cindex PostScript, bounding box
13132 @cindex bounding box
13133 Retrieve the bounding box of the PostScript image
13134 found in @var{filename}.
13135 The file must conform to
13136 Adobe's @dfn{Document Structuring Conventions} (DSC);
13137 the command searches for a @code{%%BoundingBox} comment
13138 and extracts the bounding box values into the number registers
13139 @code{llx}, @code{lly}, @code{urx}, and @code{ury}.
13140 If an error occurs (for example, @code{psbb} cannot find
13141 the @code{%%BoundingBox} comment),
13142 it sets the four number registers to zero.
13144 The search path for @var{filename} can be controlled with the @option{-I}
13145 command line option.
13149 @c =====================================================================
13151 @node Gtroff Internals, Debugging, Miscellaneous, gtroff Reference
13152 @section @code{gtroff} Internals
13154 @cindex input token
13155 @cindex token, input
13156 @cindex output node
13157 @cindex node, output
13158 @code{gtroff} processes input in three steps. One or more input
13159 characters are converted to an @dfn{input token}.@footnote{Except the
13160 escapes @code{\f}, @code{\F}, @code{\H}, @code{\m}, @code{\M}, @code{\R},
13161 @code{\s}, and @code{\S} which are processed immediately if not in
13162 copy-in mode.} Then, one or more input tokens are converted to an
13163 @dfn{output node}. Finally, output nodes are converted to the
13164 intermediate output language understood by all output devices.
13166 Actually, before step one happens, @code{gtroff} converts certain
13167 escape sequences into reserved input characters (not accessible by
13168 the user); such reserved characters are used for other internal
13169 processing also -- this is the very reason why not all characters
13170 are valid input. @xref{Identifiers}, for more on this topic.
13172 For example, the input string @samp{fi\[:u]} is converted into a
13173 character token @samp{f}, a character token @samp{i}, and a special
13174 token @samp{:u} (representing u@tie{}umlaut). Later on, the character
13175 tokens @samp{f} and @samp{i} are merged to a single output node
13176 representing the ligature glyph @samp{fi} (provided the current font
13177 has a glyph for this ligature); the same happens with @samp{:u}. All
13178 output glyph nodes are `processed' which means that they are invariably
13179 associated with a given font, font size, advance width, etc. During
13180 the formatting process, @code{gtroff} itself adds various nodes to
13181 control the data flow.
13183 Macros, diversions, and strings collect elements in two chained lists:
13184 a list of input tokens which have been passed unprocessed, and a list
13185 of output nodes. Consider the following the diversion.
13197 It contains these elements.
13199 @multitable {@i{vertical size node}} {token list} {element number}
13200 @item node list @tab token list @tab element number
13202 @item @i{line start node} @tab --- @tab 1
13203 @item @i{glyph node @code{a}} @tab --- @tab 2
13204 @item @i{word space node} @tab --- @tab 3
13205 @item --- @tab @code{b} @tab 4
13206 @item --- @tab @code{\n} @tab 5
13207 @item @i{glyph node @code{c}} @tab --- @tab 6
13208 @item @i{vertical size node} @tab --- @tab 7
13209 @item @i{vertical size node} @tab --- @tab 8
13210 @item --- @tab @code{\n} @tab 9
13213 @cindex @code{\v}, internal representation
13215 Elements 1, 7, and@tie{}8 are inserted by @code{gtroff}; the latter two
13216 (which are always present) specify the vertical extent of the last
13217 line, possibly modified by @code{\x}. The @code{br} request finishes
13218 the current partial line, inserting a newline input token which is
13219 subsequently converted to a space when the diversion is reread. Note
13220 that the word space node has a fixed width which isn't stretchable
13221 anymore. To convert horizontal space nodes back to input tokens, use
13222 the @code{unformat} request.
13224 Macros only contain elements in the token list (and the node list is
13225 empty); diversions and strings can contain elements in both lists.
13227 Note that the @code{chop} request simply reduces the number of elements in a
13228 macro, string, or diversion by one. Exceptions are @dfn{compatibility save}
13229 and @dfn{compatibility ignore} input tokens which are ignored. The
13230 @code{substring} request also ignores those input tokens.
13232 Some requests like @code{tr} or @code{cflags} work on glyph
13233 identifiers only; this means that the associated glyph can be changed
13234 without destroying this association. This can be very helpful for
13235 substituting glyphs. In the following example, we assume that
13236 glyph @samp{foo} isn't available by default, so we provide a
13237 substitution using the @code{fchar} request and map it to input
13238 character @samp{x}.
13246 Now let us assume that we install an additional special font
13247 @samp{bar} which has glyph @samp{foo}.
13255 Since glyphs defined with @code{fchar} are searched before glyphs
13256 in special fonts, we must call @code{rchar} to remove the definition
13257 of the fallback glyph. Anyway, the translation is still active;
13258 @samp{x} now maps to the real glyph @samp{foo}.
13260 @cindex compatibility mode, and parameters
13261 @cindex mode, compatibility, and parameters
13262 @cindex arguments, and compatibility mode
13263 @cindex parameters, and compatibility mode
13264 @cindex macro arguments, and compatibility mode
13265 @cindex request arguments, and compatibility mode
13266 Macro and request arguments preserve the compatibility mode:
13269 .cp 1 \" switch to compatibility mode
13273 .cp 0 \" switch compatibility mode off
13279 Since compatibility mode is on while @code{de} is called, the macro
13280 @code{xx} activates compatibility mode while executing. Argument
13281 @code{$1} can still be handled properly because it inherits the
13282 compatibility mode status which was active at the point where @code{xx}
13285 After expansion of the parameters, the compatibility save and restore
13286 tokens are removed.
13289 @c =====================================================================
13291 @node Debugging, Implementation Differences, Gtroff Internals, gtroff Reference
13295 @code{gtroff} is not easy to debug, but there are some useful features
13296 and strategies for debugging.
13298 @Defreq {lf, line [@Var{filename}]}
13300 @cindex multi-file documents
13301 @cindex documents, multi-file
13302 @cindex setting input line number (@code{lf})
13303 @cindex input line number, setting (@code{lf})
13304 @cindex number, input line, setting (@code{lf})
13305 Change the line number and optionally the file name @code{gtroff} shall
13306 use for error and warning messages. @var{line} is the input line number
13307 of the @emph{next} line.
13309 Without argument, the request is ignored.
13311 This is a debugging aid for documents which are split into many files,
13312 then put together with @code{soelim} and other preprocessors. Usually,
13313 it isn't invoked manually.
13315 Note that other @code{troff} implementations (including the original
13316 @acronym{AT&T} version) handle @code{lf} differently. For them,
13317 @var{line} changes the line number of the @emph{current} line.
13320 @DefreqList {tm, string}
13321 @DefreqItem {tm1, string}
13322 @DefreqListEnd {tmc, string}
13323 @cindex printing to stderr (@code{tm}, @code{tm1}, @code{tmc})
13324 @cindex stderr, printing to (@code{tm}, @code{tm1}, @code{tmc})
13325 Send @var{string} to the standard error output;
13326 this is very useful for printing debugging messages among other things.
13328 @var{string} is read in copy mode.
13330 The @code{tm} request ignores leading spaces of @var{string}; @code{tm1}
13331 handles its argument similar to the @code{ds} request: a leading double
13332 quote in @var{string} is stripped to allow initial blanks.
13334 The @code{tmc} request is similar to @code{tm1} but does
13335 not append a newline (as is done in @code{tm} and @code{tm1}).
13338 @Defreq {ab, [@Var{string}]}
13339 @cindex aborting (@code{ab})
13340 Similar to the @code{tm} request, except that
13341 it causes @code{gtroff} to stop processing. With no argument it
13342 prints @samp{User Abort.} to standard error.
13346 @cindex @code{ex} request, use in debugging
13347 @cindex exiting (@code{ex})
13348 The @code{ex} request also causes @code{gtroff} to stop processing;
13349 see also @ref{I/O}.
13352 When doing something involved it is useful to leave the debugging
13353 statements in the code and have them turned on by a command line flag.
13356 .if \n(DB .tm debugging output
13360 To activate these statements say
13366 If it is known in advance that there will be many errors and no useful
13367 output, @code{gtroff} can be forced to suppress formatted output with
13368 the @option{-z} flag.
13371 @cindex dumping symbol table (@code{pm})
13372 @cindex symbol table, dumping (@code{pm})
13373 Print the entire symbol table on @code{stderr}. Names of all defined
13374 macros, strings, and diversions are print together with their size in
13375 bytes. Since @code{gtroff} sometimes adds nodes by itself, the
13376 returned size can be larger than expected.
13378 This request differs from @acronym{UNIX} @code{troff}: @code{gtroff}
13379 reports the sizes of diversions, ignores an additional argument to
13380 print only the total of the sizes, and the size isn't returned in
13381 blocks of 128 characters.
13385 @cindex dumping number registers (@code{pnr})
13386 @cindex number registers, dumping (@code{pnr})
13387 Print the names and contents of all
13388 currently defined number registers on @code{stderr}.
13392 @cindex dumping traps (@code{ptr})
13393 @cindex traps, dumping (@code{ptr})
13394 Print the names and positions of all traps
13395 (not including input line traps and diversion traps) on @code{stderr}.
13396 Empty slots in the page trap list are printed as well, because they can
13397 affect the priority of subsequently planted traps.
13401 @cindex flush output (@code{fl})
13402 @cindex output, flush (@code{fl})
13403 @cindex interactive use of @code{gtroff}
13404 @cindex @code{gtroff}, interactive use
13405 Instruct @code{gtroff} to flush its output immediately. The intent
13406 is for interactive use, but this behaviour is currently not
13407 implemented in @code{gtroff}. Contrary to @acronym{UNIX} @code{troff},
13408 TTY output is sent to a device driver also (@code{grotty}), making it
13409 non-trivial to communicate interactively.
13411 This request causes a line break.
13414 @Defreq {backtrace, }
13415 @cindex backtrace of input stack (@code{backtrace})
13416 @cindex input stack, backtrace (@code{backtrace})
13417 Print a backtrace of the input stack to the standard error stream.
13419 Consider the following in file @file{test}:
13433 On execution, @code{gtroff} prints the following:
13436 test:2: backtrace: macro `xxx'
13437 test:5: backtrace: macro `yyy'
13438 test:8: backtrace: file `test'
13441 The option @option{-b} of @code{gtroff} internally calls a variant of
13442 this request on each error and warning.
13446 @cindex input stack, setting limit
13447 Use the @code{slimit} number register
13448 to set the maximum number of objects on the input stack.
13449 If @code{slimit} is less than or equal to@tie{}0,
13450 there is no limit set.
13451 With no limit, a buggy recursive macro can exhaust virtual memory.
13453 The default value is 1000; this is a compile-time constant.
13456 @Defreq {warnscale, si}
13457 Set the scaling indicator used in warnings to @var{si}. Valid values for
13458 @var{si} are @samp{u}, @samp{i}, @samp{c}, @samp{p}, and @samp{P}. At
13459 startup, it is set to @samp{i}.
13462 @Defreq {spreadwarn, [@Var{limit}]}
13463 Make @code{gtroff} emit a warning if the additional space inserted for
13464 each space between words in an output line is larger or equal to
13465 @var{limit}. A negative value is changed to zero; no argument toggles the
13466 warning on and off without changing @var{limit}. The default scaling
13467 indicator is @samp{m}. At startup, @code{spreadwarn} is deactivated, and
13468 @var{limit} is set to 3@dmn{m}.
13477 will cause a warning if @code{gtroff} must add 0.2@dmn{m} or more for each
13478 interword space in a line.
13480 This request is active only if text is justified to both margins (using
13485 @code{gtroff} has command line options for printing out more warnings
13486 (@option{-w}) and for printing backtraces (@option{-b}) when a warning
13487 or an error occurs. The most verbose level of warnings is @option{-ww}.
13489 @DefreqList {warn, [@Var{flags}]}
13490 @DefregListEnd {.warn}
13491 @cindex level of warnings (@code{warn})
13492 @cindex warnings, level (@code{warn})
13493 Control the level of warnings checked for. The @var{flags} are the sum
13494 of the numbers associated with each warning that is to be enabled; all
13495 other warnings are disabled. The number associated with each warning is
13496 listed below. For example, @w{@code{.warn 0}} disables all warnings,
13497 and @w{@code{.warn 1}} disables all warnings except that about missing
13498 glyphs. If no argument is given, all warnings are enabled.
13500 The read-only number register @code{.warn} contains the current warning
13508 @c ---------------------------------------------------------------------
13510 @node Warnings, , Debugging, Debugging
13511 @subsection Warnings
13514 The warnings that can be given to @code{gtroff} are divided into the
13515 following categories. The name associated with each warning is used by
13516 the @option{-w} and @option{-W} options; the number is used by the
13517 @code{warn} request and by the @code{.warn} register.
13522 Non-existent glyphs.@footnote{@code{char} is a misnomer since it reports
13523 missing glyphs -- there aren't missing input characters, only invalid
13524 ones.} This is enabled by default.
13528 Invalid numeric expressions. This is enabled by default.
13529 @xref{Expressions}.
13535 In fill mode, lines which could not be broken so that their length was
13536 less than the line length. This is enabled by default.
13540 Missing or mismatched closing delimiters.
13544 @cindex @code{ie} request, and warnings
13545 @cindex @code{el} request, and warnings
13546 Use of the @code{el} request with no matching @code{ie} request.
13551 Meaningless scaling indicators.
13555 Out of range arguments.
13559 Dubious syntax in numeric expressions.
13563 @cindex @code{di} request, and warnings
13564 @cindex @code{da} request, and warnings
13565 Use of @code{di} or @code{da} without an argument when there is no
13570 @cindex @code{de}, @code{de1}, @code{dei} requests, and warnings
13571 @cindex @code{am}, @code{am1}, @code{ami} requests, and warnings
13572 @cindex @code{ds}, @code{ds1} requests, and warnings
13573 @cindex @code{as}, @code{as1} requests, and warnings
13574 @cindex @code{di} request, and warnings
13575 @cindex @code{da} request, and warnings
13576 @cindex @code{box}, @code{boxa} requests, and warnings
13577 @cindex @code{\*}, and warnings
13578 Use of undefined strings, macros and diversions. When an undefined
13579 string, macro, or diversion is used, that string is automatically
13580 defined as empty. So, in most cases, at most one warning is given
13585 @cindex @code{nr} request, and warnings
13586 @cindex @code{\R}, and warnings
13587 @cindex @code{\n}, and warnings
13588 Use of undefined number registers. When an undefined number register is
13589 used, that register is automatically defined to have a value of@tie{}0.
13590 So, in most cases, at most one warning is given for use of a particular
13595 @cindex @code{\t}, and warnings
13596 Use of a tab character where a number was expected.
13600 @cindex @code{\@}}, and warnings
13601 Use of @code{\@}} where a number was expected.
13605 Requests that are missing non-optional arguments.
13609 Invalid input characters.
13613 Unrecognized escape sequences. When an unrecognized escape sequence
13614 @code{\@var{X}} is encountered, the escape character is ignored, and
13615 @var{X} is printed.
13619 @cindex compatibility mode
13620 Missing space between a request or macro and its argument. This warning
13621 is given when an undefined name longer than two characters is
13622 encountered, and the first two characters of the name make a defined
13623 name. The request or macro is not invoked. When this warning is
13624 given, no macro is automatically defined. This is enabled by default.
13625 This warning never occurs in compatibility mode.
13629 Non-existent fonts. This is enabled by default.
13633 Invalid escapes in text ignored with the @code{ig} request. These are
13634 conditions that are errors when they do not occur in ignored text.
13638 Color related warnings.
13641 All warnings except @samp{di}, @samp{mac} and @samp{reg}. It is
13642 intended that this covers all warnings that are useful with traditional
13650 @c =====================================================================
13652 @node Implementation Differences, , Debugging, gtroff Reference
13653 @section Implementation Differences
13654 @cindex implementation differences
13655 @cindex differences in implementation
13656 @cindex incompatibilities with @acronym{AT&T} @code{troff}
13657 @cindex compatibility mode
13658 @cindex mode, compatibility
13660 GNU @code{troff} has a number of features which cause incompatibilities
13661 with documents written with old versions of @code{troff}.
13664 @cindex names, long
13665 Long names cause some incompatibilities. @acronym{UNIX} @code{troff}
13672 @cindex @code{\*}, incompatibilities with @acronym{AT&T} @code{troff}
13673 @cindex @code{\n}, incompatibilities with @acronym{AT&T} @code{troff}
13675 as defining a string @samp{ab} with contents @samp{cd}. Normally, GNU
13676 @code{troff} interprets this as a call of a macro named
13677 @code{dsabcd}. Also @acronym{UNIX} @code{troff} interprets
13678 @code{\*[} or @code{\n[} as references to a string or number register
13679 called @samp{[}. In GNU @code{troff}, however, this is normally
13680 interpreted as the start of a long name. In compatibility mode GNU
13681 @code{troff} interprets long names in the traditional way
13682 (which means that they are not recognized as names).
13684 @DefreqList {cp, [@Var{n}]}
13685 @DefreqItem {do, cmd}
13686 @DefregListEnd {.C}
13687 If @var{n} is missing or non-zero, turn on compatibility mode;
13688 otherwise, turn it off.
13690 The read-only number register @code{.C} is@tie{}1 if compatibility mode is
13691 on, 0@tie{}otherwise.
13693 Compatibility mode can be also turned on with the @option{-C} command line
13696 The @code{do} request turns off compatibility mode
13697 while executing its arguments as a @code{gtroff} command.
13704 executes the @code{fam} request when compatibility mode
13707 @code{gtroff} restores the previous compatibility setting
13708 before interpreting any files sourced by the @var{cmd}.
13711 @cindex input level in delimited arguments
13712 @cindex delimited arguments, incompatibilities with @acronym{AT&T} @code{troff}
13713 Two other features are controlled by @option{-C}. If not in
13714 compatibility mode, GNU @code{troff} preserves the input level in
13715 delimited arguments:
13723 In compatibility mode, the string @samp{72def'} is returned; without
13724 @option{-C} the resulting string is @samp{168} (assuming a TTY output
13727 @cindex @code{\f}, incompatibilities with @acronym{AT&T} @code{troff}
13728 @cindex @code{\H}, incompatibilities with @acronym{AT&T} @code{troff}
13729 @cindex @code{\s}, incompatibilities with @acronym{AT&T} @code{troff}
13730 @cindex @code{\S}, incompatibilities with @acronym{AT&T} @code{troff}
13731 Finally, the escapes @code{\f}, @code{\H}, @code{\m}, @code{\M},
13732 @code{\R}, @code{\s}, and @code{\S} are transparent for recognizing the
13733 beginning of a line only in compatibility mode (this is a rather obscure
13734 feature). For example, the code
13744 prints @samp{Hallo!} in bold face if in compatibility mode, and
13745 @samp{.xx} in bold face otherwise.
13747 @cindex @code{\A}, incompatibilities with @acronym{AT&T} @code{troff}
13748 @cindex @code{\|}, incompatibilities with @acronym{AT&T} @code{troff}
13749 @cindex @code{\^}, incompatibilities with @acronym{AT&T} @code{troff}
13750 @cindex @code{\&}, incompatibilities with @acronym{AT&T} @code{troff}
13751 @cindex @code{\@{}, incompatibilities with @acronym{AT&T} @code{troff}
13752 @cindex @code{\@}}, incompatibilities with @acronym{AT&T} @code{troff}
13753 @cindex @code{\@key{SP}}, incompatibilities with @acronym{AT&T} @code{troff}
13754 @cindex @code{\'}, incompatibilities with @acronym{AT&T} @code{troff}
13755 @cindex @code{\`}, incompatibilities with @acronym{AT&T} @code{troff}
13756 @cindex @code{\-}, incompatibilities with @acronym{AT&T} @code{troff}
13757 @cindex @code{\_}, incompatibilities with @acronym{AT&T} @code{troff}
13758 @cindex @code{\!}, incompatibilities with @acronym{AT&T} @code{troff}
13759 @cindex @code{\%}, incompatibilities with @acronym{AT&T} @code{troff}
13760 @cindex @code{\c}, incompatibilities with @acronym{AT&T} @code{troff}
13761 GNU @code{troff} does not allow the use of the escape sequences
13762 @code{\|}, @code{\^}, @code{\&}, @code{\@{}, @code{\@}},
13763 @code{\@key{SP}}, @code{\'}, @code{\`}, @code{\-}, @code{\_}, @code{\!},
13764 @code{\%}, and @code{\c} in names of strings, macros, diversions, number
13765 registers, fonts or environments; @acronym{UNIX} @code{troff} does. The
13766 @code{\A} escape sequence (@pxref{Identifiers}) may be helpful in
13767 avoiding use of these escape sequences in names.
13769 @cindex fractional point sizes
13770 @cindex fractional type sizes
13771 @cindex point sizes, fractional
13772 @cindex type sizes, fractional
13773 @cindex sizes, fractional
13774 @cindex @code{ps} request, incompatibilities with @acronym{AT&T} @code{troff}
13775 Fractional point sizes cause one noteworthy incompatibility. In
13776 @acronym{UNIX} @code{troff} the @code{ps} request ignores scale
13777 indicators and thus
13784 sets the point size to 10@tie{}points, whereas in GNU @code{troff} it
13785 sets the point size to 10@tie{}scaled points. @xref{Fractional Type
13786 Sizes}, for more information.
13788 @cindex @code{bd} request, incompatibilities with @acronym{AT&T} @code{troff}
13789 @cindex @code{cs} request, incompatibilities with @acronym{AT&T} @code{troff}
13790 @cindex @code{tr} request, incompatibilities with @acronym{AT&T} @code{troff}
13791 @cindex @code{fp} request, incompatibilities with @acronym{AT&T} @code{troff}
13792 @cindex input characters and output glyphs, compatibility with @acronym{AT&T} @code{troff}
13793 @cindex output glyphs, and input characters,compatibility with @acronym{AT&T} @code{troff}
13794 @cindex characters, input, and output glyphs, compatibility with @acronym{AT&T} @code{troff}
13795 @cindex glyphs, output, and input characters, compatibility with @acronym{AT&T} @code{troff}
13796 In GNU @code{troff} there is a fundamental difference between
13797 (unformatted) input characters and (formatted) output glyphs.
13798 Everything that affects how a glyph is output is stored
13799 with the glyph node; once a glyph node has been constructed it is
13800 unaffected by any subsequent requests that are executed, including
13801 @code{bd}, @code{cs}, @code{tkf}, @code{tr}, or @code{fp} requests.
13802 Normally glyphs are constructed from input characters at the
13803 moment immediately before the glyph is added to the current output
13804 line. Macros, diversions and strings are all, in fact, the same type of
13805 object; they contain lists of input characters and glyph nodes in
13806 any combination. A glyph node does not behave like an input
13807 character for the purposes of macro processing; it does not inherit any
13808 of the special properties that the input character from which it was
13809 constructed might have had. For example,
13819 @cindex printing backslash (@code{\\}, @code{\e}, @code{\E}, @code{\[rs]})
13820 @cindex backslash, printing (@code{\\}, @code{\e}, @code{\E}, @code{\[rs]})
13821 @cindex @code{\e}, incompatibilities with @acronym{AT&T} @code{troff}
13822 @cindex @code{\!}, incompatibilities with @acronym{AT&T} @code{troff}
13823 @cindex @code{\?}, incompatibilities with @acronym{AT&T} @code{troff}
13824 @cindex transparent output, incompatibilities with @acronym{AT&T} @code{troff}
13825 @cindex output, transparent, incompatibilities with @acronym{AT&T} @code{troff}
13827 prints @samp{\\} in GNU @code{troff}; each pair of input backslashes
13828 is turned into one output backslash and the resulting output backslashes
13829 are not interpreted as escape characters when they are reread.
13830 @acronym{UNIX} @code{troff} would interpret them as escape characters
13831 when they were reread and would end up printing one @samp{\}. The
13832 correct way to obtain a printable backslash is to use the @code{\e}
13833 escape sequence: This always prints a single instance of the current
13834 escape character, regardless of whether or not it is used in a
13835 diversion; it also works in both GNU @code{troff} and @acronym{UNIX}
13836 @code{troff}.@footnote{To be completely independent of the current
13837 escape character, use @code{\(rs} which represents a reverse solidus
13838 (backslash) glyph.} To store, for some reason, an escape sequence in a
13839 diversion that will be interpreted when the diversion is reread, either
13840 use the traditional @code{\!} transparent output facility, or, if this
13841 is unsuitable, the new @code{\?} escape sequence.
13843 @xref{Diversions}, and @ref{Gtroff Internals}, for more information.
13847 @c =====================================================================
13848 @c =====================================================================
13850 @node Preprocessors, Output Devices, gtroff Reference, Top
13851 @chapter Preprocessors
13852 @cindex preprocessors
13854 This chapter describes all preprocessors that come with @code{groff} or
13855 which are freely available.
13868 @c =====================================================================
13870 @node geqn, gtbl, Preprocessors, Preprocessors
13871 @section @code{geqn}
13872 @cindex @code{eqn}, the program
13873 @cindex @code{geqn}, the program
13881 @c ---------------------------------------------------------------------
13883 @node Invoking geqn, , geqn, geqn
13884 @subsection Invoking @code{geqn}
13885 @cindex invoking @code{geqn}
13886 @cindex @code{geqn}, invoking
13891 @c =====================================================================
13893 @node gtbl, gpic, geqn, Preprocessors
13894 @section @code{gtbl}
13895 @cindex @code{tbl}, the program
13896 @cindex @code{gtbl}, the program
13904 @c ---------------------------------------------------------------------
13906 @node Invoking gtbl, , gtbl, gtbl
13907 @subsection Invoking @code{gtbl}
13908 @cindex invoking @code{gtbl}
13909 @cindex @code{gtbl}, invoking
13914 @c =====================================================================
13916 @node gpic, ggrn, gtbl, Preprocessors
13917 @section @code{gpic}
13918 @cindex @code{pic}, the program
13919 @cindex @code{gpic}, the program
13927 @c ---------------------------------------------------------------------
13929 @node Invoking gpic, , gpic, gpic
13930 @subsection Invoking @code{gpic}
13931 @cindex invoking @code{gpic}
13932 @cindex @code{gpic}, invoking
13937 @c =====================================================================
13939 @node ggrn, grap, gpic, Preprocessors
13940 @section @code{ggrn}
13941 @cindex @code{grn}, the program
13942 @cindex @code{ggrn}, the program
13950 @c ---------------------------------------------------------------------
13952 @node Invoking ggrn, , ggrn, ggrn
13953 @subsection Invoking @code{ggrn}
13954 @cindex invoking @code{ggrn}
13955 @cindex @code{ggrn}, invoking
13960 @c =====================================================================
13962 @node grap, grefer, ggrn, Preprocessors
13963 @section @code{grap}
13964 @cindex @code{grap}, the program
13966 A free implementation of @code{grap}, written by Ted Faber,
13967 is available as an extra package from the following address:
13970 @uref{http://www.lunabase.org/~faber/Vault/software/grap/}
13974 @c =====================================================================
13976 @node grefer, gsoelim, grap, Preprocessors
13977 @section @code{grefer}
13978 @cindex @code{refer}, the program
13979 @cindex @code{grefer}, the program
13984 * Invoking grefer::
13987 @c ---------------------------------------------------------------------
13989 @node Invoking grefer, , grefer, grefer
13990 @subsection Invoking @code{grefer}
13991 @cindex invoking @code{grefer}
13992 @cindex @code{grefer}, invoking
13997 @c =====================================================================
13999 @node gsoelim, , grefer, Preprocessors
14000 @section @code{gsoelim}
14001 @cindex @code{soelim}, the program
14002 @cindex @code{gsoelim}, the program
14007 * Invoking gsoelim::
14010 @c ---------------------------------------------------------------------
14012 @node Invoking gsoelim, , gsoelim, gsoelim
14013 @subsection Invoking @code{gsoelim}
14014 @cindex invoking @code{gsoelim}
14015 @cindex @code{gsoelim}, invoking
14021 @c =====================================================================
14022 @c =====================================================================
14024 @node Output Devices, File formats, Preprocessors, Top
14025 @chapter Output Devices
14026 @cindex output devices
14027 @cindex devices for output
14032 * Special Characters::
14043 @c =====================================================================
14045 @node Special Characters, grotty, Output Devices, Output Devices
14046 @section Special Characters
14047 @cindex special characters
14048 @cindex characters, special
14055 @c =====================================================================
14057 @node grotty, grops, Special Characters, Output Devices
14058 @section @code{grotty}
14059 @cindex @code{grotty}, the program
14064 * Invoking grotty::
14067 @c ---------------------------------------------------------------------
14069 @node Invoking grotty, , grotty, grotty
14070 @subsection Invoking @code{grotty}
14071 @cindex invoking @code{grotty}
14072 @cindex @code{grotty}, invoking
14076 @c The following is no longer true; fix and extend it.
14079 @c @cindex Teletype
14080 @c @cindex ISO 6249 SGR
14081 @c @cindex terminal control sequences
14082 @c @cindex control sequences, for terminals
14083 @c For TTY output devices, underlining is done by emitting sequences of
14084 @c @samp{_} and @samp{\b} (the backspace character) before the actual
14085 @c character. Literally, this is printing an underline character, then
14086 @c moving back one character position, and printing the actual character
14087 @c at the same position as the underline character (similar to a
14088 @c typewriter). Usually, a modern terminal can't interpret this (and the
14089 @c original Teletype machines for which this sequence was appropriate are
14090 @c no longer in use). You need a pager program like @code{less} which
14091 @c translates this into ISO 6429 SGR sequences to control terminals.
14094 @c =====================================================================
14096 @node grops, grodvi, grotty, Output Devices
14097 @section @code{grops}
14098 @cindex @code{grops}, the program
14104 * Embedding PostScript::
14107 @c ---------------------------------------------------------------------
14109 @node Invoking grops, Embedding PostScript, grops, grops
14110 @subsection Invoking @code{grops}
14111 @cindex invoking @code{grops}
14112 @cindex @code{grops}, invoking
14116 @c ---------------------------------------------------------------------
14118 @node Embedding PostScript, , Invoking grops, grops
14119 @subsection Embedding @sc{PostScript}
14120 @cindex embedding PostScript
14121 @cindex PostScript, embedding
14126 @c =====================================================================
14128 @node grodvi, grolj4, grops, Output Devices
14129 @section @code{grodvi}
14130 @cindex @code{grodvi}, the program
14135 * Invoking grodvi::
14138 @c ---------------------------------------------------------------------
14140 @node Invoking grodvi, , grodvi, grodvi
14141 @subsection Invoking @code{grodvi}
14142 @cindex invoking @code{grodvi}
14143 @cindex @code{grodvi}, invoking
14148 @c =====================================================================
14150 @node grolj4, grolbp, grodvi, Output Devices
14151 @section @code{grolj4}
14152 @cindex @code{grolj4}, the program
14157 * Invoking grolj4::
14160 @c ---------------------------------------------------------------------
14162 @node Invoking grolj4, , grolj4, grolj4
14163 @subsection Invoking @code{grolj4}
14164 @cindex invoking @code{grolj4}
14165 @cindex @code{grolj4}, invoking
14170 @c =====================================================================
14172 @node grolbp, grohtml, grolj4, Output Devices
14173 @section @code{grolbp}
14174 @cindex @code{grolbp}, the program
14179 * Invoking grolbp::
14182 @c ---------------------------------------------------------------------
14184 @node Invoking grolbp, , grolbp, grolbp
14185 @subsection Invoking @code{grolbp}
14186 @cindex invoking @code{grolbp}
14187 @cindex @code{grolbp}, invoking
14192 @c =====================================================================
14194 @node grohtml, gxditview, grolbp, Output Devices
14195 @section @code{grohtml}
14196 @cindex @code{grohtml}, the program
14201 * Invoking grohtml::
14202 * grohtml specific registers and strings::
14205 @c ---------------------------------------------------------------------
14207 @node Invoking grohtml, grohtml specific registers and strings, grohtml, grohtml
14208 @subsection Invoking @code{grohtml}
14209 @cindex invoking @code{grohtml}
14210 @cindex @code{grohtml}, invoking
14214 @c ---------------------------------------------------------------------
14216 @node grohtml specific registers and strings, , Invoking grohtml, grohtml
14217 @subsection @code{grohtml} specific registers and strings
14218 @cindex registers specific to @code{grohtml}
14219 @cindex strings specific to @code{grohtml}
14220 @cindex @code{grohtml}, registers and strings
14222 @DefmpregList {ps4html, grohtml}
14223 @DefstrListEnd {www-image-template, grohtml}
14224 The registers @code{ps4html} and @code{www-image-template} are defined
14225 by the @code{pre-grohtml} preprocessor. @code{pre-grohtml} reads in
14226 the @code{troff} input, marks up the inline equations and passes the
14230 troff -Tps -rps4html=1 -dwww-image-template=@var{template}
14240 The PostScript device is used to create all the image files, and the
14241 register @code{ps4html} enables the macro sets to ignore floating
14242 keeps, footers, and headings.
14244 The register @code{www-image-template} is set to the user specified
14245 template name or the default name.
14249 @c =====================================================================
14251 @node gxditview, , grohtml, Output Devices
14252 @section @code{gxditview}
14253 @cindex @code{gxditview}, the program
14258 * Invoking gxditview::
14261 @c ---------------------------------------------------------------------
14263 @node Invoking gxditview, , gxditview, gxditview
14264 @subsection Invoking @code{gxditview}
14265 @cindex invoking @code{gxditview}
14266 @cindex @code{gxditview}, invoking
14273 @c =====================================================================
14274 @c =====================================================================
14276 @node File formats, Installation, Output Devices, Top
14277 @chapter File formats
14278 @cindex file formats
14279 @cindex formats, file
14281 All files read and written by @code{gtroff} are text files. The
14282 following two sections describe their format.
14290 @c =====================================================================
14292 @node gtroff Output, Font Files, File formats, File formats
14293 @section @code{gtroff} Output
14294 @cindex @code{gtroff}, output
14295 @cindex output, @code{gtroff}
14297 This section describes the intermediate output format of GNU
14298 @code{troff}. This output is produced by a run of @code{gtroff}
14299 before it is fed into a device postprocessor program.
14301 As @code{groff} is a wrapper program around @code{gtroff} that
14302 automatically calls a postprocessor, this output does not show up
14303 normally. This is why it is called @dfn{intermediate}.
14304 @code{groff} provides the option @option{-Z} to inhibit postprocessing,
14305 such that the produced intermediate output is sent to standard output
14306 just like calling @code{gtroff} manually.
14308 @cindex troff output
14309 @cindex output, troff
14310 @cindex intermediate output
14311 @cindex output, intermediate
14312 Here, the term @dfn{troff output} describes what is output by
14313 @code{gtroff}, while @dfn{intermediate output} refers to the language
14314 that is accepted by the parser that prepares this output for the
14315 postprocessors. This parser is smarter on whitespace and implements
14316 obsolete elements for compatibility, otherwise both formats are the
14317 same.@footnote{The parser and postprocessor for intermediate output
14318 can be found in the file@*
14319 @file{@var{groff-source-dir}/src/libs/libdriver/input.cpp}.}
14321 The main purpose of the intermediate output concept is to facilitate
14322 the development of postprocessors by providing a common programming
14323 interface for all devices. It has a language of its own that is
14324 completely different from the @code{gtroff} language. While the
14325 @code{gtroff} language is a high-level programming language for text
14326 processing, the intermediate output language is a kind of low-level
14327 assembler language by specifying all positions on the page for writing
14330 The intermediate output produced by @code{gtroff} is fairly readable,
14331 while output from @acronym{AT&T} @code{troff} is rather hard to
14332 understand because of strange habits that are still supported, but not
14333 used any longer by @code{gtroff}.
14336 * Language Concepts::
14337 * Command Reference::
14338 * Intermediate Output Examples::
14339 * Output Language Compatibility::
14342 @c ---------------------------------------------------------------------
14344 @node Language Concepts, Command Reference, gtroff Output, gtroff Output
14345 @subsection Language Concepts
14347 During the run of @code{gtroff}, the input data is cracked down to the
14348 information on what has to be printed at what position on the intended
14349 device. So the language of the intermediate output format can be quite
14350 small. Its only elements are commands with and without arguments.
14351 In this section, the term @dfn{command} always refers to the intermediate
14352 output language, and never to the @code{gtroff} language used for document
14353 formatting. There are commands for positioning and text writing, for drawing, and
14354 for device controlling.
14362 @node Separation, Argument Units, Language Concepts, Language Concepts
14363 @subsubsection Separation
14365 @acronym{AT&T} @code{troff} output has strange requirements on whitespace.
14366 The @code{gtroff} output parser, however, is smart about whitespace by
14367 making it maximally optional. The whitespace characters, i.e., the
14368 tab, space, and newline characters, always have a syntactical meaning.
14369 They are never printable because spacing within the output is always
14370 done by positioning commands.
14372 Any sequence of space or tab characters is treated as a single
14373 @dfn{syntactical space}. It separates commands and arguments, but is
14374 only required when there would occur a clashing between the command code
14375 and the arguments without the space. Most often, this happens when
14376 variable-length command names, arguments, argument lists, or command
14377 clusters meet. Commands and arguments with a known, fixed length need
14378 not be separated by syntactical space.
14380 A line break is a syntactical element, too. Every command argument can be
14381 followed by whitespace, a comment, or a newline character. Thus a
14382 @dfn{syntactical line break} is defined to consist of optional
14383 syntactical space that is optionally followed by a comment, and a
14386 The normal commands, those for positioning and text, consist of a
14387 single letter taking a fixed number of arguments. For historical reasons,
14388 the parser allows to stack such commands on the same line, but
14389 fortunately, in @code{gtroff}'s intermediate output, every command with
14390 at least one argument is followed by a line break, thus providing
14391 excellent readability.
14393 The other commands -- those for drawing and device controlling --
14394 have a more complicated structure; some recognize long command names,
14395 and some take a variable number of arguments. So all @samp{D} and
14396 @samp{x} commands were designed to request a syntactical line break
14397 after their last argument. Only one command, @w{@samp{x X}},
14398 has an argument that can stretch over several lines; all other
14399 commands must have all of their arguments on the same line as the
14400 command, i.e., the arguments may not be splitted by a line break.
14402 Empty lines (these are lines containing only space and/or a comment), can
14403 occur everywhere. They are just ignored.
14405 @node Argument Units, Document Parts, Separation, Language Concepts
14406 @subsubsection Argument Units
14408 Some commands take integer arguments that are assumed to represent
14409 values in a measurement unit, but the letter for the corresponding
14410 scale indicator is not written with the output command arguments.
14411 Most commands assume the scale indicator @samp{u}, the basic unit of
14412 the device, some use @samp{z}, the scaled point unit of the device,
14413 while others, such as the color commands, expect plain integers.
14415 Note that single characters can have the eighth bit set, as can the
14416 names of fonts and special characters. The names of characters and
14417 fonts can be of arbitrary length. A character that is to be printed
14418 will always be in the current font.
14420 A string argument is always terminated by the next whitespace
14421 character (space, tab, or newline); an embedded @samp{#} character is
14422 regarded as part of the argument, not as the beginning of a comment
14423 command. An integer argument is already terminated by the next
14424 non-digit character, which then is regarded as the first character of
14425 the next argument or command.
14427 @node Document Parts, , Argument Units, Language Concepts
14428 @subsubsection Document Parts
14430 A correct intermediate output document consists of two parts, the
14431 @dfn{prologue} and the @dfn{body}.
14433 The task of the prologue is to set the general device parameters
14434 using three exactly specified commands. @code{gtroff}'s prologue
14435 is guaranteed to consist of the following three lines (in that order):
14439 x res @var{n} @var{h} @var{v}
14444 with the arguments set as outlined in @ref{Device Control Commands}.
14445 Note that the parser for the intermediate output format is able to
14446 swallow additional whitespace and comments as well even in the
14449 The body is the main section for processing the document data.
14450 Syntactically, it is a sequence of any commands different from the
14451 ones used in the prologue. Processing is terminated as soon as the
14452 first @w{@samp{x stop}} command is encountered; the last line of any
14453 @code{gtroff} intermediate output always contains such a command.
14455 Semantically, the body is page oriented. A new page is started by a
14456 @samp{p} command. Positioning, writing, and drawing commands are
14457 always done within the current page, so they cannot occur before the
14458 first @samp{p} command. Absolute positioning (by the @samp{H} and
14459 @samp{V} commands) is done relative to the current page; all other
14460 positioning is done relative to the current location within this page.
14462 @c ---------------------------------------------------------------------
14464 @node Command Reference, Intermediate Output Examples, Language Concepts, gtroff Output
14465 @subsection Command Reference
14467 This section describes all intermediate output commands, both from
14468 @acronym{AT&T} @code{troff} as well as the @code{gtroff} extensions.
14471 * Comment Command::
14472 * Simple Commands::
14473 * Graphics Commands::
14474 * Device Control Commands::
14475 * Obsolete Command::
14478 @node Comment Command, Simple Commands, Command Reference, Command Reference
14479 @subsubsection Comment Command
14482 @item #@var{anything}@angles{end of line}
14483 A comment. Ignore any characters from the @samp{#} character up to
14484 the next newline character.
14486 This command is the only possibility for commenting in the intermediate
14487 output. Each comment can be preceded by arbitrary syntactical space;
14488 every command can be terminated by a comment.
14491 @node Simple Commands, Graphics Commands, Comment Command, Command Reference
14492 @subsubsection Simple Commands
14494 The commands in this subsection have a command code consisting of a
14495 single character, taking a fixed number of arguments. Most of them
14496 are commands for positioning and text writing. These commands are
14497 smart about whitespace. Optionally, syntactical space can be inserted
14498 before, after, and between the command letter and its arguments.
14499 All of these commands are stackable, i.e., they can be preceded by
14500 other simple commands or followed by arbitrary other commands on the
14501 same line. A separating syntactical space is only necessary when two
14502 integer arguments would clash or if the preceding argument ends with a
14507 .if (\n[@USE_ENV_STACK] == 1) \{\
14509 Open a new environment by copying the actual device configuration data
14510 to the environment stack.
14512 The current environment is setup by the device specification and
14513 manipulated by the setting commands.
14517 Close the actual environment (opened by a preceding
14519 and restore the previous environment from the environment
14520 stack as the actual device configuration data.
14522 \} \" endif @USE_ENV_STACK
14525 @item C @var{xxx}@angles{whitespace}
14526 Print a special character named @var{xxx}. The trailing
14527 syntactical space or line break is necessary to allow glyph names
14528 of arbitrary length. The glyph is printed at the current print
14529 position; the glyph's size is read from the font file. The print
14530 position is not changed.
14533 Print glyph@tie{}@var{g} at the current print position;@footnote{@samp{c}
14534 is actually a misnomer since it outputs a glyph.} the glyph's size is
14535 read from the font file. The print position is not changed.
14538 Set font to font number@tie{}@var{n} (a non-negative integer).
14541 Move right to the absolute vertical position@tie{}@var{n} (a
14542 non-negative integer in basic units @samp{u} relative to left edge
14546 Move @var{n} (a non-negative integer) basic units @samp{u} horizontally
14547 to the right. The original @acronym{UNIX} troff manual allows negative
14548 values for @var{n} also, but @code{gtroff} doesn't use this.
14550 @item m @var{color-scheme} @r{[}@var{component} @dots{}@r{]}
14551 Set the color for text (glyphs), line drawing, and the outline of
14552 graphic objects using different color schemes; the analoguous command
14553 for the filling color of graphic objects is @samp{DF}. The color
14554 components are specified as integer arguments between 0 and 65536.
14555 The number of color components and their meaning vary for the
14556 different color schemes. These commands are generated by
14557 @code{gtroff}'s escape sequence @code{\m}. No position changing.
14558 These commands are a @code{gtroff} extension.
14561 @item mc @var{cyan} @var{magenta} @var{yellow}
14562 Set color using the CMY color scheme, having the 3@tie{}color components
14563 @var{cyan}, @var{magenta}, and @var{yellow}.
14566 Set color to the default color value (black in most cases).
14567 No component arguments.
14569 @item mg @var{gray}
14570 Set color to the shade of gray given by the argument, an integer
14571 between 0 (black) and 65536 (white).
14573 @item mk @var{cyan} @var{magenta} @var{yellow} @var{black}
14574 Set color using the CMYK color scheme, having the 4@tie{}color components
14575 @var{cyan}, @var{magenta}, @var{yellow}, and @var{black}.
14577 @item mr @var{red} @var{green} @var{blue}
14578 Set color using the RGB color scheme, having the 3@tie{}color components
14579 @var{red}, @var{green}, and @var{blue}.
14583 Print glyph with index@tie{}@var{n} (a non-negative integer) of the
14584 current font. This command is a @code{gtroff} extension.
14586 @item n @var{b} @var{a}
14587 Inform the device about a line break, but no positioning is done by
14588 this command. In @acronym{AT&T} @code{troff}, the integer arguments
14589 @var{b} and@tie{}@var{a} informed about the space before and after the
14590 current line to make the intermediate output more human readable
14591 without performing any action. In @code{groff}, they are just ignored, but
14592 they must be provided for compatibility reasons.
14595 Begin a new page in the outprint. The page number is set
14596 to@tie{}@var{n}. This page is completely independent of pages formerly
14597 processed even if those have the same page number. The vertical
14598 position on the outprint is automatically set to@tie{}0. All
14599 positioning, writing, and drawing is always done relative to a page,
14600 so a @samp{p} command must be issued before any of these commands.
14603 Set point size to @var{n}@tie{}scaled points (this is unit @samp{z}).
14604 @acronym{AT&T} @code{troff} used the unit points (@samp{p}) instead.
14605 @xref{Output Language Compatibility}.
14607 @item t @var{xxx}@angles{whitespace}
14608 @itemx t @var{xxx} @var{dummy-arg}@angles{whitespace}
14609 Print a word, i.e., a sequence of characters @var{xxx} representing
14610 output glyphs which names are single characters, terminated by
14611 a space character or a line break; an optional second integer argument
14612 is ignored (this allows the formatter to generate an even number of
14613 arguments). The first glyph should be printed at the current
14614 position, the current horizontal position should then be increased by
14615 the width of the first glyph, and so on for each glyph.
14616 The widths of the glyphs are read from the font file, scaled for the
14617 current point size, and rounded to a multiple of the horizontal
14618 resolution. Special characters cannot be printed using this command
14619 (use the @samp{C} command for special characters). This command is a
14620 @code{gtroff} extension; it is only used for devices whose @file{DESC}
14621 file contains the @code{tcommand} keyword (@pxref{DESC File Format}).
14623 @item u @var{n} @var{xxx}@angles{whitespace}
14624 Print word with track kerning. This is the same as the @samp{t}
14625 command except that after printing each glyph, the current
14626 horizontal position is increased by the sum of the width of that
14627 glyph and@tie{}@var{n} (an integer in basic units @samp{u}).
14628 This command is a @code{gtroff} extension; it is only used for devices
14629 whose @file{DESC} file contains the @code{tcommand} keyword
14630 (@pxref{DESC File Format}).
14633 Move down to the absolute vertical position@tie{}@var{n} (a
14634 non-negative integer in basic units @samp{u}) relative to upper edge
14638 Move @var{n}@tie{}basic units @samp{u} down (@var{n} is a non-negative
14639 integer). The original @acronym{UNIX} troff manual allows negative
14640 values for @var{n} also, but @code{gtroff} doesn't use this.
14643 Informs about a paddable white space to increase readability.
14644 The spacing itself must be performed explicitly by a move command.
14647 @node Graphics Commands, Device Control Commands, Simple Commands, Command Reference
14648 @subsubsection Graphics Commands
14650 Each graphics or drawing command in the intermediate output starts
14651 with the letter @samp{D}, followed by one or two characters that
14652 specify a subcommand; this is followed by a fixed or variable number
14653 of integer arguments that are separated by a single space character.
14654 A @samp{D} command may not be followed by another command on the same line
14655 (apart from a comment), so each @samp{D} command is terminated by a
14656 syntactical line break.
14658 @code{gtroff} output follows the classical spacing rules (no space
14659 between command and subcommand, all arguments are preceded by a
14660 single space character), but the parser allows optional space between
14661 the command letters and makes the space before the first argument
14662 optional. As usual, each space can be any sequence of tab and space
14665 Some graphics commands can take a variable number of arguments.
14666 In this case, they are integers representing a size measured in basic
14667 units @samp{u}. The arguments called @var{h1}, @var{h2}, @dots{},
14668 @var{hn} stand for horizontal distances where positive means right,
14669 negative left. The arguments called @var{v1}, @var{v2}, @dots{},
14670 @var{vn} stand for vertical distances where positive means down,
14671 negative up. All these distances are offsets relative to the current
14674 Each graphics command directly corresponds to a similar @code{gtroff}
14675 @code{\D} escape sequence. @xref{Drawing Requests}.
14677 Unknown @samp{D} commands are assumed to be device-specific.
14678 Its arguments are parsed as strings; the whole information is then
14679 sent to the postprocessor.
14681 In the following command reference, the syntax element
14682 @angles{line break} means a syntactical line break as defined above.
14685 @item D~ @var{h1} @var{v1} @var{h2} @var{v2} @dots{} @var{hn} @var{vn}@angles{line break}
14686 Draw B-spline from current position to offset (@var{h1},@var{v1}),
14687 then to offset (@var{h2},@var{v2}), if given, etc.@: up to
14688 (@var{hn},@var{vn}). This command takes a variable number of argument
14689 pairs; the current position is moved to the terminal point of the drawn
14692 @item Da @var{h1} @var{v1} @var{h2} @var{v2}@angles{line break}
14693 Draw arc from current position to
14694 (@var{h1},@var{v1})@math{+}(@var{h2},@var{v2}) with center at
14695 (@var{h1},@var{v1}); then move the current position to the final point
14698 @item DC @var{d}@angles{line break}
14699 @itemx DC @var{d} @var{dummy-arg}@angles{line break}
14700 Draw a solid circle using the current fill color with
14701 diameter@tie{}@var{d} (integer in basic units @samp{u}) with leftmost
14702 point at the current position; then move the current position to the
14703 rightmost point of the circle. An optional second integer argument is
14704 ignored (this allows the formatter to generate an even number of
14705 arguments). This command is a @code{gtroff} extension.
14707 @item Dc @var{d}@angles{line break}
14708 Draw circle line with diameter@tie{}@var{d} (integer in basic units
14709 @samp{u}) with leftmost point at the current position; then move the
14710 current position to the rightmost point of the circle.
14712 @item DE @var{h} @var{v}@angles{line break}
14713 Draw a solid ellipse in the current fill color with a horizontal
14714 diameter of@tie{}@var{h} and a vertical diameter of@tie{}@var{v} (both
14715 integers in basic units @samp{u}) with the leftmost point at the
14716 current position; then move to the rightmost point of the ellipse.
14717 This command is a @code{gtroff} extension.
14719 @item De @var{h} @var{v}@angles{line break}
14720 Draw an outlined ellipse with a horizontal diameter of@tie{}@var{h}
14721 and a vertical diameter of@tie{}@var{v} (both integers in basic units
14722 @samp{u}) with the leftmost point at current position; then move to
14723 the rightmost point of the ellipse.
14725 @item DF @var{color-scheme} @r{[}@var{component} @dots{}@r{]}@angles{line break}
14726 Set fill color for solid drawing objects using different color
14727 schemes; the analoguous command for setting the color of text, line
14728 graphics, and the outline of graphic objects is @samp{m}.
14729 The color components are specified as integer arguments between 0 and
14730 65536. The number of color components and their meaning vary for the
14731 different color schemes. These commands are generated by @code{gtroff}'s
14732 escape sequences @w{@code{\D'F @dots{}'}} and @code{\M} (with no other
14733 corresponding graphics commands). No position changing. This command
14734 is a @code{gtroff} extension.
14737 @item DFc @var{cyan} @var{magenta} @var{yellow}@angles{line break}
14738 Set fill color for solid drawing objects using the CMY color scheme,
14739 having the 3@tie{}color components @var{cyan}, @var{magenta}, and
14742 @item DFd@angles{line break}
14743 Set fill color for solid drawing objects to the default fill color value
14744 (black in most cases). No component arguments.
14746 @item DFg @var{gray}@angles{line break}
14747 Set fill color for solid drawing objects to the shade of gray given by
14748 the argument, an integer between 0 (black) and 65536 (white).
14750 @item DFk @var{cyan} @var{magenta} @var{yellow} @var{black}@angles{line break}
14751 Set fill color for solid drawing objects using the CMYK color scheme,
14752 having the 4@tie{}color components @var{cyan}, @var{magenta}, @var{yellow},
14755 @item DFr @var{red} @var{green} @var{blue}@angles{line break}
14756 Set fill color for solid drawing objects using the RGB color scheme,
14757 having the 3@tie{}color components @var{red}, @var{green}, and @var{blue}.
14760 @item Df @var{n}@angles{line break}
14761 The argument@tie{}@var{n} must be an integer in the range @math{-32767}
14765 @item @math{0 @LE{} @var{n} @LE{} 1000}
14766 Set the color for filling solid drawing objects to a shade of gray,
14767 where 0 corresponds to solid white, 1000 (the default) to solid black,
14768 and values in between to intermediate shades of gray; this is
14769 obsoleted by command @samp{DFg}.
14771 @item @math{@var{n} < 0} or @math{@var{n} > 1000}
14772 Set the filling color to the color that is currently being used for
14773 the text and the outline, see command @samp{m}. For example, the
14782 sets all colors to blue.
14786 No position changing. This command is a @code{gtroff} extension.
14788 @item Dl @var{h} @var{v}@angles{line break}
14789 Draw line from current position to offset (@var{h},@var{v}) (integers
14790 in basic units @samp{u}); then set current position to the end of the
14793 @item Dp @var{h1} @var{v1} @var{h2} @var{v2} @dots{} @var{hn} @var{vn}@angles{line break}
14794 Draw a polygon line from current position to offset (@var{h1},@var{v1}),
14795 from there to offset (@var{h2},@var{v2}), etc.@: up to offset
14796 (@var{hn},@var{vn}), and from there back to the starting position.
14797 For historical reasons, the position is changed by adding the sum of
14798 all arguments with odd index to the actual horizontal position and the
14799 even ones to the vertical position. Although this doesn't make sense
14800 it is kept for compatibility.
14802 As the polygon is closed, the end of drawing is the starting point, so
14803 the position doesn't change.
14805 This command is a @code{gtroff} extension.
14807 @item Dp @var{h1} @var{v1} @var{h2} @var{v2} @dots{} @var{hn} @var{vn}@angles{line break}
14808 Draw a solid polygon in the current fill color rather than an outlined
14809 polygon, using the same arguments and positioning as the corresponding
14812 No position changing.
14814 This command is a @code{gtroff} extension.
14816 @item Dt @var{n}@angles{line break}
14817 Set the current line thickness to@tie{}@var{n} (an integer in basic
14818 units @samp{u}) if @math{@var{n}>0}; if @math{@var{n}=0} select the
14819 smallest available line thickness; if @math{@var{n}<0} set the line
14820 thickness proportional to the point size (this is the default before
14821 the first @samp{Dt} command was specified). For historical reasons,
14822 the horizontal position is changed by adding the argument to the actual
14823 horizontal position, while the vertical position is not changed.
14824 Although this doesn't make sense it is kept for compatibility.
14826 No position changing.
14828 This command is a @code{gtroff} extension.
14831 @node Device Control Commands, Obsolete Command, Graphics Commands, Command Reference
14832 @subsubsection Device Control Commands
14834 Each device control command starts with the letter @samp{x},
14835 followed by a space character (optional or arbitrary space or tab in
14836 @code{gtroff}) and a subcommand letter or word; each argument (if any)
14837 must be preceded by a syntactical space. All @samp{x} commands are
14838 terminated by a syntactical line break; no device control command can
14839 be followed by another command on the same line (except a comment).
14841 The subcommand is basically a single letter, but to increase
14842 readability, it can be written as a word, i.e., an arbitrary sequence
14843 of characters terminated by the next tab, space, or newline character.
14844 All characters of the subcommand word but the first are simply ignored.
14845 For example, @code{gtroff} outputs the initialization command
14846 @w{@samp{x i}} as @w{@samp{x init}} and the resolution command
14847 @w{@samp{x r}} as @w{@samp{x res}}.
14849 In the following, the syntax element @angles{line break} means a
14850 syntactical line break (@pxref{Separation}).
14853 @item xF @var{name}@angles{line break}
14854 The @samp{F} stands for @var{Filename}.
14856 Use @var{name} as the intended name for the current file in error
14857 reports. This is useful for remembering the original file name when
14858 @code{gtroff} uses an internal piping mechanism. The input file is
14859 not changed by this command. This command is a @code{gtroff} extension.
14861 @item xf @var{n} @var{s}@angles{line break}
14862 The @samp{f} stands for @var{font}.
14864 Mount font position@tie{}@var{n} (a non-negative integer) with font
14865 named@tie{}@var{s} (a text word). @xref{Font Positions}.
14867 @item xH @var{n}@angles{line break}
14868 The @samp{H} stands for @var{Height}.
14870 Set glyph height to@tie{}@var{n} (a positive integer in scaled
14871 points @samp{z}). @acronym{AT&T} @code{troff} uses the unit points
14872 (@samp{p}) instead. @xref{Output Language Compatibility}.
14874 @item xi@angles{line break}
14875 The @samp{i} stands for @var{init}.
14877 Initialize device. This is the third command of the prologue.
14879 @item xp@angles{line break}
14880 The @samp{p} stands for @var{pause}.
14882 Parsed but ignored. The original @acronym{UNIX} troff manual writes
14885 pause device, can be restarted
14888 @item xr @var{n} @var{h} @var{v}@angles{line break}
14889 The @samp{r} stands for @var{resolution}.
14891 Resolution is@tie{}@var{n}, while @var{h} is the minimal horizontal
14892 motion, and @var{v} the minimal vertical motion possible with this
14893 device; all arguments are positive integers in basic units @samp{u}
14894 per inch. This is the second command of the prologue.
14896 @item xS @var{n}@angles{line break}
14897 The @samp{S} stands for @var{Slant}.
14899 Set slant to@tie{}@var{n} (an integer in basic units @samp{u}).
14901 @item xs@angles{line break}
14902 The @samp{s} stands for @var{stop}.
14904 Terminates the processing of the current file; issued as the last
14905 command of any intermediate troff output.
14907 @item xt@angles{line break}
14908 The @samp{t} stands for @var{trailer}.
14910 Generate trailer information, if any. In @var{gtroff}, this is
14911 actually just ignored.
14913 @item xT @var{xxx}@angles{line break}
14914 The @samp{T} stands for @var{Typesetter}.
14916 Set name of device to word @var{xxx}, a sequence of characters ended
14917 by the next white space character. The possible device names coincide
14918 with those from the @code{groff} @option{-T} option. This is the first
14919 command of the prologue.
14921 @item xu @var{n}@angles{line break}
14922 The @samp{u} stands for @var{underline}.
14924 Configure underlining of spaces. If @var{n} is@tie{}1, start
14925 underlining of spaces; if @var{n} is@tie{}0, stop underlining of spaces.
14926 This is needed for the @code{cu} request in nroff mode and is ignored
14927 otherwise. This command is a @code{gtroff} extension.
14929 @item xX @var{anything}@angles{line break}
14930 The @samp{x} stands for @var{X-escape}.
14932 Send string @var{anything} uninterpreted to the device. If the line
14933 following this command starts with a @samp{+} character this line is
14934 interpreted as a continuation line in the following sense. The
14935 @samp{+} is ignored, but a newline character is sent instead to the
14936 device, the rest of the line is sent uninterpreted. The same applies
14937 to all following lines until the first character of a line is not a
14938 @samp{+} character. This command is generated by the @code{gtroff}
14939 escape sequence @code{\X}. The line-continuing feature is a
14940 @code{gtroff} extension.
14943 @node Obsolete Command, , Device Control Commands, Command Reference
14944 @subsubsection Obsolete Command
14945 In @acronym{AT&T} @code{troff} output, the writing of a single
14946 glyph is mostly done by a very strange command that combines a
14947 horizontal move and a single character giving the glyph name. It
14948 doesn't have a command code, but is represented by a 3-character
14949 argument consisting of exactly 2@tie{}digits and a character.
14952 @item @var{dd}@var{g}
14953 Move right @var{dd} (exactly two decimal digits) basic units @samp{u},
14954 then print glyph@tie{}@var{g} (represented as a single character).
14956 In @code{gtroff}, arbitrary syntactical space around and within this
14957 command is allowed to be added. Only when a preceding command on the
14958 same line ends with an argument of variable length a separating space
14959 is obligatory. In @acronym{AT&T} @code{troff}, large clusters of these
14960 and other commands are used, mostly without spaces; this made such output
14964 For modern high-resolution devices, this command does not make sense
14965 because the width of the glyphs can become much larger than two
14966 decimal digits. In @code{gtroff}, this is only used for the devices
14967 @code{X75}, @code{X75-12}, @code{X100}, and @code{X100-12}. For other
14968 devices, the commands @samp{t} and @samp{u} provide a better
14971 @c ---------------------------------------------------------------------
14973 @node Intermediate Output Examples, Output Language Compatibility, Command Reference, gtroff Output
14974 @subsection Intermediate Output Examples
14976 This section presents the intermediate output generated from the same
14977 input for three different devices. The input is the sentence
14978 @samp{hell world} fed into @code{gtroff} on the command line.
14981 @item High-resolution device @code{ps}
14983 This is the standard output of @code{gtroff} if no @option{-T} option
14988 shell> echo "hell world" | groff -Z -T ps
15014 This output can be fed into @code{grops} to get its representation as
15017 @item Low-resolution device @code{latin1}
15019 This is similar to the high-resolution device except that the
15020 positioning is done at a minor scale. Some comments (lines starting
15021 with @samp{#}) were added for clarification; they were not generated
15026 shell> echo "hell world" | groff -Z -T latin1
15039 # initial positioning on the page
15042 # write text `hell'
15044 # inform about space, and issue a horizontal jump
15046 # write text `world'
15048 # announce line break, but do nothing because ...
15051 # ... the end of the document has been reached
15059 This output can be fed into @code{grotty} to get a formatted text
15062 @item @acronym{AT&T} @code{troff} output
15063 Since a computer monitor has a very low resolution compared to modern
15064 printers the intermediate output for the X@tie{}Window devices can use
15065 the jump-and-write command with its 2-digit displacements.
15069 shell> echo "hell world" | groff -Z -T X100
15081 # write text with jump-and-write commands
15082 ch07e07l03lw06w11o07r05l03dh7
15092 This output can be fed into @code{xditview} or @code{gxditview}
15093 for displaying in@tie{}X.
15095 Due to the obsolete jump-and-write command, the text clusters in the
15096 @acronym{AT&T} @code{troff} output are almost unreadable.
15099 @c ---------------------------------------------------------------------
15101 @node Output Language Compatibility, , Intermediate Output Examples, gtroff Output
15102 @subsection Output Language Compatibility
15104 The intermediate output language of @acronym{AT&T} @code{troff}
15105 was first documented in the @acronym{UNIX} troff manual, with later
15106 additions documented in @cite{A Typesetter-indenpendent TROFF},
15107 written by Brian Kernighan.
15109 The @code{gtroff} intermediate output format is compatible with this
15110 specification except for the following features.
15114 The classical quasi device independence is not yet implemented.
15117 The old hardware was very different from what we use today. So the
15118 @code{groff} devices are also fundamentally different from the ones in
15119 @acronym{AT&T} @code{troff}. For example, the @acronym{AT&T}
15120 PostScript device is called @code{post} and has a resolution of only
15121 720 units per inch, suitable for printers 20 years ago, while
15122 @code{groff}'s @code{ps} device has a resolution of
15123 72000 units per inch. Maybe, by implementing some rescaling
15124 mechanism similar to the classical quasi device independence,
15125 @code{groff} could emulate @acronym{AT&T}'s @code{post} device.
15128 The B-spline command @samp{D~} is correctly handled by the
15129 intermediate output parser, but the drawing routines aren't
15130 implemented in some of the postprocessor programs.
15133 The argument of the commands @samp{s} and @w{@samp{x H}} has the
15134 implicit unit scaled point @samp{z} in @code{gtroff}, while
15135 @acronym{AT&T} @code{troff} has point (@samp{p}). This isn't an
15136 incompatibility but a compatible extension, for both units coincide
15137 for all devices without a @code{sizescale} parameter in the @file{DESC}
15138 file, including all postprocessors from @acronym{AT&T} and
15139 @code{groff}'s text devices. The few @code{groff} devices with
15140 a @code{sizescale} parameter either do not exist for @acronym{AT&T}
15141 @code{troff}, have a different name, or seem to have a different
15142 resolution. So conflicts are very unlikely.
15145 The position changing after the commands @samp{Dp}, @samp{DP}, and
15146 @samp{Dt} is illogical, but as old versions of @code{gtroff} used this
15147 feature it is kept for compatibility reasons.
15150 Temporarily, there existed some confusion on the positioning after the
15151 @samp{D} commands that are groff extensions. This has been clarified
15152 by establishing the classical rule for all @code{groff} drawing commands:
15156 The position after a graphic object has been drawn is at its end;
15157 for circles and ellipses, the `end' is at the right side.
15160 From this, the positionings specified for the drawing commands above
15161 follow quite naturally.
15168 @c =====================================================================
15170 @node Font Files, , gtroff Output, File formats
15171 @section Font Files
15173 @cindex files, font
15175 The @code{gtroff} font format is roughly a superset of the
15176 @code{ditroff} font format (as used in later versions of @acronym{AT&T}
15177 @code{troff} and its descendants). Unlike the @code{ditroff} font
15178 format, there is no associated binary format; all files are text
15179 files.@footnote{Plan@tie{}9 @code{troff} has also abandoned the binary
15180 format.} The font files for device @var{name} are stored in a directory
15181 @file{dev@var{name}}. There are two types of file: a device description
15182 file called @file{DESC} and for each font@tie{}@var{f} a font file
15183 called@tie{}@file{@var{f}}.
15186 * DESC File Format::
15187 * Font File Format::
15190 @c ---------------------------------------------------------------------
15192 @node DESC File Format, Font File Format, Font Files, Font Files
15193 @subsection @file{DESC} File Format
15194 @cindex @file{DESC} file, format
15195 @cindex font description file, format
15196 @cindex format of font description file
15197 @pindex DESC@r{ file format}
15199 The @file{DESC} file can contain the following types of line. Except
15200 for the @code{charset} keyword which must comes last (if at all), the
15201 order of the lines is not important.
15206 @cindex device resolution
15207 @cindex resolution, device
15208 There are @var{n}@tie{}machine units per inch.
15212 @cindex horizontal resolution
15213 @cindex resolution, horizontal
15214 The horizontal resolution is @var{n}@tie{}machine units. All horizontal
15215 quantities are rounded to be multiples of this value.
15219 @cindex vertical resolution
15220 @cindex resolution, vertical
15221 The vertical resolution is @var{n}@tie{}machine units. All vertical
15222 quantities are rounded to be multiples of this value.
15224 @item sizescale @var{n}
15226 The scale factor for point sizes. By default this has a value of@tie{}1.
15227 One scaled point is equal to one point/@var{n}. The arguments to the
15228 @code{unitwidth} and @code{sizes} commands are given in scaled points.
15229 @xref{Fractional Type Sizes}, for more information.
15231 @item unitwidth @var{n}
15233 Quantities in the font files are given in machine units for fonts whose
15234 point size is @var{n}@tie{}scaled points.
15236 @item prepro @var{program}
15238 Call @var{program} as a preprocessor. Currently, this keyword is used
15239 by @code{groff} with option @option{-Thtml} only.
15241 @item postpro @var{program}
15243 Call @var{program} as a postprocessor. For example, the line
15250 in the file @file{devdvi/DESC} makes @code{groff} call @code{grodvi}
15251 if option @option{-Tdvi} is given (and @option{-Z} isn't used).
15255 This means that the postprocessor can handle the @samp{t} and @samp{u}
15256 intermediate output commands.
15258 @item sizes @var{s1} @var{s2} @dots{} @var{sn} 0
15260 This means that the device has fonts at @var{s1}, @var{s2}, @dots{}
15261 @var{sn} scaled points. The list of sizes must be terminated by@tie{}0
15262 (this is digit zero). Each @var{si} can also be a range of sizes
15263 @var{m}-@var{n}. The list can extend over more than one line.
15265 @item styles @var{S1} @var{S2} @dots{} @var{Sm}
15267 The first @var{m}@tie{}font positions are associated with styles
15268 @var{S1} @dots{} @var{Sm}.
15270 @item fonts @var{n} @var{F1} @var{F2} @var{F3} @dots{} @var{Fn}
15272 Fonts @var{F1} @dots{} @var{Fn} are mounted in the font positions
15273 @var{m}+1, @dots{}, @var{m}+@var{n} where @var{m} is the number of
15274 styles. This command may extend over more than one line. A font name
15275 of@tie{}0 means no font is mounted on the corresponding font position.
15277 @item family @var{fam}
15279 The default font family is @var{fam}.
15281 @item use_charnames_in_special
15282 @kindex use_charnames_in_special
15283 This command indicates that @code{gtroff} should encode special
15284 characters inside special commands. Currently, this is only used
15285 by the @acronym{HTML} output device. @xref{Postprocessor Access}.
15287 @item papersize @var{string} @dots{}
15289 Select a paper size. Valid values for @var{string} are the ISO paper
15290 types @code{A0}-@code{A7}, @code{B0}-@code{B7}, @code{C0}-@code{C7},
15291 @code{D0}-@code{D7}, @code{DL}, and the US paper types @code{letter},
15292 @code{legal}, @code{tabloid}, @code{ledger}, @code{statement},
15293 @code{executive}, @code{com10}, and @code{monarch}. Case is not significant
15294 for @var{string} if it holds predefined paper types. Alternatively,
15295 @var{string} can be a file name (e.g.@: @file{/etc/papersize}); if the file
15296 can be opened, @code{groff} reads the first line and tests for the above
15297 paper sizes. Finally, @var{string} can be a custom paper size in the format
15298 @code{@var{length},@var{width}} (no spaces before and after the comma).
15299 Both @var{length} and @var{width} must have a unit appended; valid values
15300 are @samp{i} for inches, @samp{C} for centimeters, @samp{p} for points, and
15301 @samp{P} for picas. Example: @code{12c,235p}. An argument which starts
15302 with a digit is always treated as a custom paper format. @code{papersize}
15303 sets both the vertical and horizontal dimension of the output medium.
15305 More than one argument can be specified; @code{groff} scans from left to
15306 right and uses the first valid paper specification.
15308 @item pass_filenames
15309 @kindex pass_filenames
15310 Tell @code{gtroff} to emit the name of the source file currently
15311 being processed. This is achieved by the intermediate output command
15312 @samp{F}. Currently, this is only used by the @acronym{HTML} output
15315 @item print @var{program}
15317 Use @var{program} as a spooler program for printing. If omitted,
15318 the @option{-l} and @option{-L} options of @code{groff} are ignored.
15322 This line and everything following in the file are ignored. It is
15323 allowed for the sake of backwards compatibility.
15326 The @code{res}, @code{unitwidth}, @code{fonts}, and @code{sizes} lines
15327 are mandatory. Other commands are ignored by @code{gtroff} but may be
15328 used by postprocessors to store arbitrary information about the device
15329 in the @file{DESC} file.
15333 @kindex biggestfont
15334 Here a list of obsolete keywords which are recognized by @code{groff}
15335 but completely ignored: @code{spare1}, @code{spare2},
15336 @code{biggestfont}.
15338 @c ---------------------------------------------------------------------
15340 @node Font File Format, , DESC File Format, Font Files
15341 @subsection Font File Format
15342 @cindex font file, format
15343 @cindex font description file, format
15344 @cindex format of font files
15345 @cindex format of font description files
15347 A @dfn{font file}, also (and probably better) called a @dfn{font
15348 description file}, has two sections. The first section is a sequence
15349 of lines each containing a sequence of blank delimited words; the first
15350 word in the line is a key, and subsequent words give a value for that
15356 The name of the font is@tie{}@var{f}.
15358 @item spacewidth @var{n}
15360 The normal width of a space is@tie{}@var{n}.
15362 @item slant @var{n}
15364 The glyphs of the font have a slant of @var{n}@tie{}degrees.
15365 (Positive means forward.)
15367 @item ligatures @var{lig1} @var{lig2} @dots{} @var{lign} [0]
15369 Glyphs @var{lig1}, @var{lig2}, @dots{}, @var{lign} are ligatures;
15370 possible ligatures are @samp{ff}, @samp{fi}, @samp{fl}, @samp{ffi} and
15371 @samp{ffl}. For backwards compatibility, the list of ligatures may be
15372 terminated with a@tie{}0. The list of ligatures may not extend over more
15376 @cindex special fonts
15378 The font is @dfn{special}; this means that when a glyph is requested
15379 that is not present in the current font, it is searched for in any
15380 special fonts that are mounted.
15383 Other commands are ignored by @code{gtroff} but may be used by
15384 postprocessors to store arbitrary information about the font in the font
15387 @cindex comments in font files
15388 @cindex font files, comments
15390 The first section can contain comments which start with the @samp{#}
15391 character and extend to the end of a line.
15393 The second section contains one or two subsections. It must contain a
15394 @code{charset} subsection and it may also contain a @code{kernpairs}
15395 subsection. These subsections can appear in any order. Each
15396 subsection starts with a word on a line by itself.
15399 The word @code{charset} starts the character set
15400 subsection.@footnote{This keyword is misnamed since it starts a list
15401 of ordered glyphs, not characters.} The @code{charset} line is
15402 followed by a sequence of lines. Each line gives information for one
15403 glyph. A line comprises a number of fields separated by blanks or
15404 tabs. The format is
15407 @var{name} @var{metrics} @var{type} @var{code}
15408 [@var{entity-name}] [@code{--} @var{comment}]
15411 @cindex 8-bit input
15412 @cindex input, 8-bit
15413 @cindex accessing unnamed glyphs with @code{\N}
15414 @cindex unnamed glyphs, accessing with @code{\N}
15415 @cindex characters, unnamed, accessing with @code{\N}
15416 @cindex glyphs, unnamed, accessing with @code{\N}
15419 @var{name} identifies the glyph name@footnote{The distinction between
15420 input, characters, and output, glyphs, is not clearly separated in the
15421 terminology of @code{groff}; for example, the @code{char} request
15422 should be called @code{glyph} since it defines an output entity.}:
15423 If @var{name} is a single character@tie{}@var{c} then it corresponds
15424 to the @code{gtroff} input character@tie{}@var{c}; if it is of the form
15425 @samp{\@var{c}} where @var{c} is a single character, then it
15426 corresponds to the special character @code{\[@var{c}]}; otherwise it
15427 corresponds to the special character @samp{\[@var{name}]}. If it
15428 is exactly two characters @var{xx} it can be entered as
15429 @samp{\(@var{xx}}. Note that single-letter special characters can't
15430 be accessed as @samp{\@var{c}}; the only exception is @samp{\-} which
15431 is identical to @code{\[-]}.
15433 @code{gtroff} supports 8-bit input characters; however some utilities
15434 have difficulties with eight-bit characters. For this reason, there is
15435 a convention that the entity name @samp{char@var{n}} is equivalent to
15436 the single input character whose code is@tie{}@var{n}. For example,
15437 @samp{char163} would be equivalent to the character with code@tie{}163
15438 which is the pounds sterling sign in the ISO@tie{}@w{Latin-1} character set.
15439 You shouldn't use @samp{char@var{n}} entities in font description files
15440 since they are related to input, not output. Otherwise, you get
15441 hard-coded connections between input and output encoding which
15442 prevents use of different (input) character sets.
15444 The name @samp{---} is special and indicates that the glyph is
15445 unnamed; such glyphs can only be used by means of the @code{\N}
15446 escape sequence in @code{gtroff}.
15448 The @var{type} field gives the glyph type:
15452 the glyph has a descender, for example, @samp{p};
15455 the glyph has an ascender, for example, @samp{b};
15458 the glyph has both an ascender and a descender, for example, @samp{(}.
15461 The @var{code} field gives the code which the postprocessor uses to
15462 print the glyph. The glyph can also be input to @code{gtroff}
15463 using this code by means of the @code{\N} escape sequence. @var{code}
15464 can be any integer. If it starts with @samp{0} it is interpreted as
15465 octal; if it starts with @samp{0x} or @samp{0X} it is interpreted as
15466 hexadecimal. Note, however, that the @code{\N} escape sequence only
15467 accepts a decimal integer.
15469 The @var{entity-name} field gives an @acronym{ASCII} string
15470 identifying the glyph which the postprocessor uses to print the
15471 @code{gtroff} glyph @var{name}. This field is optional and has been
15472 introduced so that the @acronym{HTML} device driver can encode its
15473 character set. For example, the glyph @samp{\[Po]} is
15474 represented as @samp{£} in @acronym{HTML} 4.0.
15476 Anything on the line after the @var{entity-name} field resp.@: after
15477 @samp{--} will be ignored.
15479 The @var{metrics} field has the form:
15483 @var{width}[@code{,}@var{height}[@code{,}@var{depth}[@code{,}@var{italic-correction}
15484 [@code{,}@var{left-italic-correction}[@code{,}@var{subscript-correction}]]]]]
15489 There must not be any spaces between these subfields (it has been split
15490 here into two lines for better legibility only). Missing subfields are
15491 assumed to be@tie{}0. The subfields are all decimal integers. Since
15492 there is no associated binary format, these values are not required to
15493 fit into a variable of type @samp{char} as they are in @code{ditroff}.
15494 The @var{width} subfield gives the width of the glyph. The @var{height}
15495 subfield gives the height of the glyph (upwards is positive); if a
15496 glyph does not extend above the baseline, it should be given a zero
15497 height, rather than a negative height. The @var{depth} subfield gives
15498 the depth of the glyph, that is, the distance from the baseline to the
15499 lowest point below the baseline to which the glyph extends (downwards is
15500 positive); if a glyph does not extend below the baseline, it should be
15501 given a zero depth, rather than a negative depth. The
15502 @var{italic-correction} subfield gives the amount of space that should
15503 be added after the glyph when it is immediately to be followed by a
15504 glyph from a roman font. The @var{left-italic-correction} subfield
15505 gives the amount of space that should be added before the glyph when it
15506 is immediately to be preceded by a glyph from a roman font. The
15507 @var{subscript-correction} gives the amount of space that should be
15508 added after a glyph before adding a subscript. This should be less
15509 than the italic correction.
15511 A line in the @code{charset} section can also have the format
15518 This indicates that @var{name} is just another name for the glyph
15519 mentioned in the preceding line.
15522 The word @code{kernpairs} starts the kernpairs section. This contains a
15523 sequence of lines of the form:
15526 @var{c1} @var{c2} @var{n}
15530 This means that when glyph @var{c1} appears next to glyph @var{c2}
15531 the space between them should be increased by@tie{}@var{n}. Most
15532 entries in the kernpairs section have a negative value for@tie{}@var{n}.
15536 @c =====================================================================
15537 @c =====================================================================
15539 @node Installation, Copying This Manual, File formats, Top
15540 @chapter Installation
15541 @cindex installation
15547 @c =====================================================================
15548 @c =====================================================================
15550 @node Copying This Manual, Request Index, Installation, Top
15551 @appendix Copying This Manual
15554 * GNU Free Documentation License:: License for copying this manual.
15561 @c =====================================================================
15562 @c =====================================================================
15564 @node Request Index, Escape Index, Copying This Manual, Top
15565 @appendix Request Index
15567 Requests appear without the leading control character (normally either
15568 @samp{.} or @samp{'}).
15574 @c =====================================================================
15575 @c =====================================================================
15577 @node Escape Index, Operator Index, Request Index, Top
15578 @appendix Escape Index
15580 Any escape sequence @code{\@var{X}} with @var{X} not in the list below
15581 emits a warning, printing glyph @var{X}.
15587 @c =====================================================================
15588 @c =====================================================================
15590 @node Operator Index, Register Index, Escape Index, Top
15591 @appendix Operator Index
15597 @c =====================================================================
15598 @c =====================================================================
15600 @node Register Index, Macro Index, Operator Index, Top
15601 @appendix Register Index
15603 The macro package or program a specific register belongs to is appended in
15606 A register name@tie{}@code{x} consisting of exactly one character can be
15607 accessed as @samp{\nx}. A register name @code{xx} consisting of exactly
15608 two characters can be accessed as @samp{\n(xx}. Register names @code{xxx}
15609 of any length can be accessed as @samp{\n[xxx]}.
15615 @c =====================================================================
15616 @c =====================================================================
15618 @node Macro Index, String Index, Register Index, Top
15619 @appendix Macro Index
15621 The macro package a specific macro belongs to is appended in brackets.
15622 They appear without the leading control character (normally @samp{.}).
15628 @c =====================================================================
15629 @c =====================================================================
15631 @node String Index, Glyph Name Index, Macro Index, Top
15632 @appendix String Index
15634 The macro package or program a specific string belongs to is appended in
15637 A string name@tie{}@code{x} consisting of exactly one character can be
15638 accessed as @samp{\*x}. A string name @code{xx} consisting of exactly
15639 two characters can be accessed as @samp{\*(xx}. String names @code{xxx}
15640 of any length can be accessed as @samp{\*[xxx]}.
15647 @c =====================================================================
15648 @c =====================================================================
15650 @node Glyph Name Index, Font File Keyword Index, String Index, Top
15651 @appendix Glyph Name Index
15653 A glyph name @code{xx} consisting of exactly two characters can be
15654 accessed as @samp{\(xx}. Glyph names @code{xxx} of any length can be
15655 accessed as @samp{\[xxx]}.
15661 @c =====================================================================
15662 @c =====================================================================
15664 @node Font File Keyword Index, Program and File Index, Glyph Name Index, Top
15665 @appendix Font File Keyword Index
15671 @c =====================================================================
15672 @c =====================================================================
15674 @node Program and File Index, Concept Index, Font File Keyword Index, Top
15675 @appendix Program and File Index
15681 @c =====================================================================
15682 @c =====================================================================
15684 @node Concept Index, , Program and File Index, Top
15685 @appendix Concept Index