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}
358 @set LEmacro @LEmacro
370 @c We need special parentheses and brackets:
372 @c . Real parentheses in @deffn produce an error while compiling with
374 @c . Real brackets use the wrong font in @deffn, overriding @t{}.
376 @c Since macros aren't expanded in @deffn during -E, the following
377 @c definitions are for non-TeX only.
379 @c This is true for texinfo 4.0.
382 @set Lparenmacro @lparen
383 @set Rparenmacro @rparen
384 @set Lbrackmacro @lbrack
385 @set Rbrackmacro @rbrack
409 @c This suppresses the word `Appendix' in the appendix headers.
412 \gdef\gobblefirst#1#2{#2}
413 \gdef\putwordAppendix{\gobblefirst}
417 @c We map some latin-1 characters to corresponding texinfo macros.
420 \global\catcode`^^e4\active % ä
422 \global\catcode`^^c4\active % Ä
424 \global\catcode`^^e9\active % é
426 \global\catcode`^^c9\active % É
428 \global\catcode`^^f6\active % ö
430 \global\catcode`^^d6\active % Ö
432 \global\catcode`^^fc\active % ü
434 \global\catcode`^^dc\active % Ü
436 \global\catcode`^^e6\active % æ
438 \global\catcode`^^c6\active % Æ
440 \global\catcode`^^df\active % ß
445 @c Note: We say `Roman numerals' but `roman font'.
448 @dircategory Typesetting
450 * Groff: (groff). The GNU troff document formatting system.
456 @subtitle The GNU implementation of @code{troff}
457 @subtitle Edition 1.19.2
458 @subtitle Spring 2005
459 @author by Trent A.@tie{}Fisher
460 @author and Werner Lemberg (@email{bug-groff@@gnu.org})
463 @vskip 0pt plus 1filll
471 @node Top, Introduction, (dir), (dir)
478 @node Top, Introduction, (dir), (dir)
487 * Tutorial for Macro Users::
494 * Copying This Manual::
502 * Font File Keyword Index::
503 * Program and File Index::
509 @c =====================================================================
510 @c =====================================================================
512 @node Introduction, Invoking groff, Top, Top
513 @chapter Introduction
516 GNU @code{troff} (or @code{groff}) is a system for typesetting
517 documents. @code{troff} is very flexible and has been in existence (and
518 use) for about 3@tie{}decades. It is quite widespread and firmly
519 entrenched in the @acronym{UNIX} community.
524 * groff Capabilities::
525 * Macro Package Intro::
526 * Preprocessor Intro::
527 * Output device intro::
532 @c =====================================================================
534 @node What Is groff?, History, Introduction, Introduction
535 @section What Is @code{groff}?
536 @cindex what is @code{groff}?
537 @cindex @code{groff} -- what is it?
539 @code{groff} belongs to an older generation of document preparation
540 systems, which operate more like compilers than the more recent
541 interactive @acronym{WYSIWYG}@footnote{What You See Is What You Get}
542 systems. @code{groff} and its contemporary counterpart, @TeX{}, both
543 work using a @dfn{batch} paradigm: The input (or @dfn{source}) files are
544 normal text files with embedded formatting commands. These files can
545 then be processed by @code{groff} to produce a typeset document on a
548 Likewise, @code{groff} should not be confused with a @dfn{word
549 processor}, since that term connotes an integrated system that includes
550 an editor and a text formatter. Also, many word processors follow the
551 @acronym{WYSIWYG} paradigm discussed earlier.
553 Although @acronym{WYSIWYG} systems may be easier to use, they have a
554 number of disadvantages compared to @code{troff}:
558 They must be used on a graphics display to work on a document.
561 Most of the @acronym{WYSIWYG} systems are either non-free or are not
565 @code{troff} is firmly entrenched in all @acronym{UNIX} systems.
568 It is difficult to have a wide range of capabilities available within
569 the confines of a GUI/window system.
572 It is more difficult to make global changes to a document.
576 ``GUIs normally make it simple to accomplish simple actions and
577 impossible to accomplish complex actions.'' --Doug Gwyn (22/Jun/91 in
578 @code{comp.unix.wizards})
582 @c =====================================================================
584 @node History, groff Capabilities, What Is groff?, Introduction
588 @cindex @code{runoff}, the program
589 @cindex @code{rf}, the program
590 @code{troff} can trace its origins back to a formatting program called
591 @code{runoff}, written by J.@tie{}E.@tie{}Saltzer, which ran on MIT's CTSS
592 operating system in the mid-sixties. This name came from the common
593 phrase of the time ``I'll run off a document.'' Bob Morris ported it to
594 the 635 architecture and called the program @code{roff} (an abbreviation
595 of @code{runoff}). It was rewritten as @code{rf} for the @w{PDP-7}
596 (before having @acronym{UNIX}), and at the same time (1969), Doug
597 McIllroy rewrote an extended and simplified version of @code{roff} in
598 the @acronym{BCPL} programming language.
600 @cindex @code{roff}, the program
601 The first version of @acronym{UNIX} was developed on a @w{PDP-7} which
602 was sitting around Bell Labs. In 1971 the developers wanted to get a
603 @w{PDP-11} for further work on the operating system. In order to
604 justify the cost for this system, they proposed that they would
605 implement a document formatting system for the @acronym{AT&T} patents
606 division. This first formatting program was a reimplementation of
607 McIllroy's @code{roff}, written by J.@tie{}F.@tie{}Ossanna.
609 @cindex @code{nroff}, the program
610 When they needed a more flexible language, a new version of @code{roff}
611 called @code{nroff} (``Newer @code{roff}'') was written. It had a much
612 more complicated syntax, but provided the basis for all future versions.
613 When they got a Graphic Systems CAT Phototypesetter, Ossanna wrote a
614 version of @code{nroff} that would drive it. It was dubbed
615 @code{troff}, for ``typesetter @code{roff}'', although many people have
616 speculated that it actually means ``Times @code{roff}'' because of the
617 use of the Times font family in @code{troff} by default. As such, the
618 name @code{troff} is pronounced `@w{t-roff}' rather than `trough'.
620 With @code{troff} came @code{nroff} (they were actually the same program
621 except for some @samp{#ifdef}s), which was for producing output for line
622 printers and character terminals. It understood everything @code{troff}
623 did, and ignored the commands which were not applicable (e.g.@: font
626 Since there are several things which cannot be done easily in
627 @code{troff}, work on several preprocessors began. These programs would
628 transform certain parts of a document into @code{troff}, which made a
629 very natural use of pipes in @acronym{UNIX}.
631 The @code{eqn} preprocessor allowed mathematical formulæ to be
632 specified in a much simpler and more intuitive manner. @code{tbl} is a
633 preprocessor for formatting tables. The @code{refer} preprocessor (and
634 the similar program, @code{bib}) processes citations in a document
635 according to a bibliographic database.
637 Unfortunately, Ossanna's @code{troff} was written in @w{PDP-11} assembly
638 language and produced output specifically for the CAT phototypesetter.
639 He rewrote it in C, although it was now 7000@tie{}lines of uncommented
640 code and still dependent on the CAT. As the CAT became less common, and
641 was no longer supported by the manufacturer, the need to make it support
642 other devices became a priority. However, before this could be done,
643 Ossanna was killed in a car accident.
646 @cindex @code{ditroff}, the program
647 So, Brian Kernighan took on the task of rewriting @code{troff}. The
648 newly rewritten version produced device independent code which was
649 very easy for postprocessors to read and translate to the appropriate
650 printer codes. Also, this new version of @code{troff} (called
651 @code{ditroff} for ``device independent @code{troff}'') had several
652 extensions, which included drawing functions.
654 Due to the additional abilities of the new version of @code{troff},
655 several new preprocessors appeared. The @code{pic} preprocessor
656 provides a wide range of drawing functions. Likewise the @code{ideal}
657 preprocessor did the same, although via a much different paradigm. The
658 @code{grap} preprocessor took specifications for graphs, but, unlike
659 other preprocessors, produced @code{pic} code.
661 James Clark began work on a GNU implementation of @code{ditroff} in
662 early@tie{}1989. The first version, @code{groff}@tie{}0.3.1, was released
663 June@tie{}1990. @code{groff} included:
667 A replacement for @code{ditroff} with many extensions.
670 The @code{soelim}, @code{pic}, @code{tbl}, and @code{eqn} preprocessors.
673 Postprocessors for character devices, @sc{PostScript}, @TeX{} DVI, and
674 X@tie{}Windows. GNU @code{troff} also eliminated the need for a
675 separate @code{nroff} program with a postprocessor which would produce
676 @acronym{ASCII} output.
679 A version of the @file{me} macros and an implementation of the
683 Also, a front-end was included which could construct the, sometimes
684 painfully long, pipelines required for all the post- and preprocessors.
686 Development of GNU @code{troff} progressed rapidly, and saw the
687 additions of a replacement for @code{refer}, an implementation of the
688 @file{ms} and @file{mm} macros, and a program to deduce how to format a
689 document (@code{grog}).
691 It was declared a stable (i.e.@: non-beta) package with the release of
692 version@tie{}1.04 around November@tie{}1991.
694 Beginning in@tie{}1999, @code{groff} has new maintainers (the package was
695 an orphan for a few years). As a result, new features and programs like
696 @code{grn}, a preprocessor for gremlin images, and an output device to
697 produce @acronym{HTML} output have been added.
700 @c =====================================================================
702 @node groff Capabilities, Macro Package Intro, History, Introduction
703 @section @code{groff} Capabilities
704 @cindex @code{groff} capabilities
705 @cindex capabilities of @code{groff}
707 So what exactly is @code{groff} capable of doing? @code{groff} provides
708 a wide range of low-level text formatting operations. Using these, it
709 is possible to perform a wide range of formatting tasks, such as
710 footnotes, table of contents, multiple columns, etc. Here's a list of
711 the most important operations supported by @code{groff}:
715 text filling, adjusting, and centering
724 font and glyph size control
727 vertical spacing (e.g.@: double-spacing)
730 line length and indenting
733 macros, strings, diversions, and traps
739 tabs, leaders, and fields
742 input and output conventions and character translation
745 overstrike, bracket, line drawing, and zero-width functions
748 local horizontal and vertical motions and the width function
754 output line numbering
757 conditional acceptance of input
760 environment switching
763 insertions from the standard input
766 input/output file switching
769 output and error messages
773 @c =====================================================================
775 @node Macro Package Intro, Preprocessor Intro, groff Capabilities, Introduction
776 @section Macro Packages
777 @cindex macro packages
779 Since @code{groff} provides such low-level facilities, it can be quite
780 difficult to use by itself. However, @code{groff} provides a
781 @dfn{macro} facility to specify how certain routine operations
782 (e.g.@tie{}starting paragraphs, printing headers and footers, etc.)@:
783 should be done. These macros can be collected together into a @dfn{macro
784 package}. There are a number of macro packages available; the most
785 common (and the ones described in this manual) are @file{man},
786 @file{mdoc}, @file{me}, @file{ms}, and @file{mm}.
789 @c =====================================================================
791 @node Preprocessor Intro, Output device intro, Macro Package Intro, Introduction
792 @section Preprocessors
793 @cindex preprocessors
795 Although @code{groff} provides most functions needed to format a
796 document, some operations would be unwieldy (e.g.@: to draw pictures).
797 Therefore, programs called @dfn{preprocessors} were written which
798 understand their own language and produce the necessary @code{groff}
799 operations. These preprocessors are able to differentiate their own
800 input from the rest of the document via markers.
802 To use a preprocessor, @acronym{UNIX} pipes are used to feed the output
803 from the preprocessor into @code{groff}. Any number of preprocessors
804 may be used on a given document; in this case, the preprocessors are
805 linked together into one pipeline. However, with @code{groff}, the user
806 does not need to construct the pipe, but only tell @code{groff} what
807 preprocessors to use.
809 @code{groff} currently has preprocessors for producing tables
810 (@code{tbl}), typesetting equations (@code{eqn}), drawing pictures
811 (@code{pic} and @code{grn}), and for processing bibliographies
812 (@code{refer}). An associated program which is useful when dealing with
813 preprocessors is @code{soelim}.
815 A free implementation of @code{grap}, a preprocessor for drawing graphs,
816 can be obtained as an extra package; @code{groff} can use @code{grap}
819 There are other preprocessors in existence, but, unfortunately, no free
820 implementations are available. Among them are preprocessors for drawing
821 mathematical pictures (@code{ideal}) and chemical structures
825 @c =====================================================================
827 @node Output device intro, Credits, Preprocessor Intro, Introduction
828 @section Output Devices
829 @cindex postprocessors
830 @cindex output devices
831 @cindex devices for output
833 @code{groff} actually produces device independent code which may be
834 fed into a postprocessor to produce output for a particular device.
835 Currently, @code{groff} has postprocessors for @sc{PostScript}
836 devices, character terminals, X@tie{}Windows (for previewing), @TeX{}
837 DVI format, HP LaserJet@tie{}4 and Canon LBP printers (which use
838 @acronym{CAPSL}), and @acronym{HTML}.
841 @c =====================================================================
843 @node Credits, , Output device intro, Introduction
847 Large portions of this manual were taken from existing documents, most
848 notably, the manual pages for the @code{groff} package by James Clark,
849 and Eric Allman's papers on the @file{me} macro package.
851 The section on the @file{man} macro package is partly based on
852 Susan@tie{}G.@: Kleinmann's @file{groff_man} manual page written for the
853 Debian GNU/Linux system.
855 Larry Kollar contributed the section in the @file{ms} macro package.
859 @c =====================================================================
860 @c =====================================================================
862 @node Invoking groff, Tutorial for Macro Users, Introduction, Top
863 @chapter Invoking @code{groff}
864 @cindex invoking @code{groff}
865 @cindex @code{groff} invocation
867 This section focuses on how to invoke the @code{groff} front end. This
868 front end takes care of the details of constructing the pipeline among
869 the preprocessors, @code{gtroff} and the postprocessor.
871 It has become a tradition that GNU programs get the prefix @samp{g} to
872 distinguish it from its original counterparts provided by the host (see
873 @ref{Environment}, for more details). Thus, for example, @code{geqn} is
874 GNU @code{eqn}. On operating systems like GNU/Linux or the Hurd, which
875 don't contain proprietary versions of @code{troff}, and on
876 MS-DOS/MS-Windows, where @code{troff} and associated programs are not
877 available at all, this prefix is omitted since GNU @code{troff} is the
878 only used incarnation of @code{troff}. Exception: @samp{groff} is never
879 replaced by @samp{roff}.
881 In this document, we consequently say @samp{gtroff} when talking about
882 the GNU @code{troff} program. All other implementations of @code{troff}
883 are called @acronym{AT&T} @code{troff} which is the common origin of
884 all @code{troff} derivates (with more or less compatible changes).
885 Similarly, we say @samp{gpic}, @samp{geqn}, etc.
890 * Macro Directories::
893 * Invocation Examples::
897 @c =====================================================================
899 @node Groff Options, Environment, Invoking groff, Invoking groff
912 @code{groff} normally runs the @code{gtroff} program and a postprocessor
913 appropriate for the selected device. The default device is @samp{ps}
914 (but it can be changed when @code{groff} is configured and built). It
915 can optionally preprocess with any of @code{gpic}, @code{geqn},
916 @code{gtbl}, @code{ggrn}, @code{grap}, @code{grefer}, or @code{gsoelim}.
918 This section only documents options to the @code{groff} front end. Many
919 of the arguments to @code{groff} are passed on to @code{gtroff},
920 therefore those are also included. Arguments to pre- or postprocessors
921 can be found in @ref{Invoking gpic}, @ref{Invoking geqn}, @ref{Invoking
922 gtbl}, @ref{Invoking ggrn}, @ref{Invoking grefer}, @ref{Invoking
923 gsoelim}, @ref{Invoking grotty}, @ref{Invoking grops}, @ref{Invoking
924 grohtml}, @ref{Invoking grodvi}, @ref{Invoking grolj4}, @ref{Invoking
925 grolbp}, and @ref{Invoking gxditview}.
927 The command line format for @code{groff} is:
930 groff [ -abceghilpstvzCEGNRSUVXZ ] [ -F@var{dir} ] [ -m@var{name} ]
931 [ -T@var{def} ] [ -f@var{fam} ] [ -w@var{name} ] [ -W@var{name} ]
932 [ -M@var{dir} ] [ -d@var{cs} ] [ -r@var{cn} ] [ -n@var{num} ]
933 [ -o@var{list} ] [ -P@var{arg} ] [ -L@var{arg} ] [ -I@var{dir} ]
934 [ @var{files}@dots{} ]
937 The command line format for @code{gtroff} is as follows.
940 gtroff [ -abcivzCERU ] [ -w@var{name} ] [ -W@var{name} ] [ -d@var{cs} ]
941 [ -f@var{fam} ] [ -m@var{name} ] [ -n@var{num} ]
942 [ -o@var{list} ] [ -r@var{cn} ] [ -T@var{name} ]
943 [ -F@var{dir} ] [ -M@var{dir} ] [ @var{files}@dots{} ]
947 Obviously, many of the options to @code{groff} are actually passed on to
950 Options without an argument can be grouped behind a single@tie{}@option{-}.
951 A filename of@tie{}@file{-} denotes the standard input. It is possible to
952 have whitespace between an option and its parameter.
954 The @code{grog} command can be used to guess the correct @code{groff}
955 command to format a file.
957 Here's the description of the command-line options:
959 @cindex command-line options
962 Print a help message.
965 Preprocess with @code{geqn}.
968 Preprocess with @code{gtbl}.
971 Preprocess with @code{ggrn}.
974 Preprocess with @code{grap}.
977 Preprocess with @code{gpic}.
980 Preprocess with @code{gsoelim}.
983 Suppress color output.
986 Preprocess with @code{grefer}. No mechanism is provided for passing
987 arguments to @code{grefer} because most @code{grefer} options have
988 equivalent commands which can be included in the file. @xref{grefer},
993 Note that @code{gtroff} also accepts a @option{-R} option, which is not
994 accessible via @code{groff}. This option prevents the loading of the
995 @file{troffrc} and @file{troffrc-end} files.
998 Make programs run by @code{groff} print out their version number.
1001 Print the pipeline on @code{stdout} instead of executing it. If specified
1002 more than once, print the pipeline on @code{stderr} and execute it.
1005 Suppress output from @code{gtroff}. Only error messages are printed.
1008 Do not postprocess the output of @code{gtroff}. Normally @code{groff}
1009 automatically runs the appropriate postprocessor.
1012 Pass @var{arg} to the postprocessor. Each argument should be passed
1013 with a separate @option{-P} option. Note that @code{groff} does not
1014 prepend @samp{-} to @var{arg} before passing it to the postprocessor.
1017 Send the output to a spooler for printing. The command used for this is
1018 specified by the @code{print} command in the device description file
1019 (see @ref{Font Files}, for more info). If not present, @option{-l} is
1023 Pass @var{arg} to the spooler. Each argument should be passed with a
1024 separate @option{-L} option. Note that @code{groff} does not prepend
1025 a @samp{-} to @var{arg} before passing it to the postprocessor.
1026 If the @code{print} keyword in the device description file is missing,
1027 @option{-L} is ignored.
1030 Prepare output for device @var{dev}. The default device is @samp{ps},
1031 unless changed when @code{groff} was configured and built. The
1032 following are the output devices currently available:
1036 For @sc{PostScript} printers and previewers.
1039 For @TeX{} DVI format.
1042 For a 75@dmn{dpi} X11 previewer.
1045 For a 75@dmn{dpi} X11 previewer with a 12@dmn{pt} base font in the
1049 For a 100@dmn{dpi} X11 previewer.
1052 For a 100@dmn{dpi} X11 previewer with a 12@dmn{pt} base font in the
1056 @cindex encoding, output, @acronym{ASCII}
1057 @cindex @acronym{ASCII}, output encoding
1058 @cindex output encoding, @acronym{ASCII}
1059 For typewriter-like devices using the (7-bit) @acronym{ASCII}
1063 @cindex encoding, output, @w{latin-1} (ISO @w{8859-1})
1064 @cindex @w{latin-1} (ISO @w{8859-1}), output encoding
1065 @cindex ISO @w{8859-1} (@w{latin-1}), output encoding
1066 @cindex output encoding, @w{latin-1} (ISO @w{8859-1})
1067 For typewriter-like devices that support the @w{Latin-1}
1068 (ISO@tie{}@w{8859-1}) character set.
1071 @cindex encoding, output, @w{utf-8}
1072 @cindex @w{utf-8}, output encoding
1073 @cindex output encoding, @w{utf-8}
1074 For typewriter-like devices which use the Unicode (ISO@tie{}10646)
1075 character set with @w{UTF-8} encoding.
1078 @cindex encoding, output, @acronym{EBCDIC}
1079 @cindex @acronym{EBCDIC}, output encoding
1080 @cindex output encoding, @acronym{EBCDIC}
1081 @cindex encoding, output, cp1047
1082 @cindex cp1047, output encoding
1083 @cindex output encoding, cp1047
1084 @cindex IBM cp1047 output encoding
1085 For typewriter-like devices which use the @acronym{EBCDIC} encoding IBM
1089 For HP LaserJet4-compatible (or other PCL5-compatible) printers.
1092 For Canon @acronym{CAPSL} printers (@w{LBP-4} and @w{LBP-8} series laser
1096 @pindex post-grohtml
1097 @cindex @code{grohtml}, the program
1099 To produce @acronym{HTML} output. Note that the @acronym{HTML} driver
1100 consists of two parts, a preprocessor (@code{pre-grohtml}) and a
1101 postprocessor (@code{post-grohtml}).
1104 @cindex output device name string register (@code{.T})
1105 @cindex output device usage number register (@code{.T})
1106 The predefined @code{gtroff} string register @code{.T} contains the
1107 current output device; the read-only number register @code{.T} is set
1108 to@tie{}1 if this option is used (which is always true if @code{groff} is
1109 used to call @code{gtroff}). @xref{Built-in Registers}.
1111 The postprocessor to be used for a device is specified by the
1112 @code{postpro} command in the device description file. (@xref{Font
1113 Files}, for more info.) This can be overridden with the @option{-X}
1117 Preview with @code{gxditview} instead of using the usual postprocessor.
1118 This is unlikely to produce good results except with @option{-Tps}.
1120 Note that this is not the same as using @option{-TX75} or
1121 @option{-TX100} to view a document with @code{gxditview}: The former
1122 uses the metrics of the specified device, whereas the latter uses
1123 X-specific fonts and metrics.
1126 Don't allow newlines with @code{eqn} delimiters. This is the same as
1127 the @option{-N} option in @code{geqn}.
1130 @cindex @code{open} request, and safer mode
1131 @cindex @code{opena} request, and safer mode
1132 @cindex @code{pso} request, and safer mode
1133 @cindex @code{sy} request, and safer mode
1134 @cindex @code{pi} request, and safer mode
1137 Safer mode. Pass the @option{-S} option to @code{gpic} and disable the
1138 @code{open}, @code{opena}, @code{pso}, @code{sy}, and @code{pi}
1139 requests. For security reasons, this is enabled by default.
1142 @cindex mode, unsafe
1144 Unsafe mode. This enables the @code{open}, @code{opena}, @code{pso},
1145 @code{sy}, and @code{pi} requests.
1148 @cindex @acronym{ASCII} approximation output register (@code{.A})
1149 Generate an @acronym{ASCII} approximation of the typeset output. The
1150 read-only register @code{.A} is then set to@tie{}1. @xref{Built-in
1151 Registers}. A typical example is
1154 groff -a -man -Tdvi troff.man | less
1158 which shows how lines are broken for the DVI device. Note that this
1159 option is rather useless today since graphic output devices are
1160 available virtually everywhere.
1163 Print a backtrace with each warning or error message. This backtrace
1164 should help track down the cause of the error. The line numbers given
1165 in the backtrace may not always be correct: @code{gtroff} can get
1166 confused by @code{as} or @code{am} requests while counting line numbers.
1169 Read the standard input after all the named input files have been
1173 Enable warning @var{name}. Available warnings are described in
1174 @ref{Debugging}. Multiple @option{-w} options are allowed.
1177 Inhibit warning @var{name}. Multiple @option{-W} options are allowed.
1180 Inhibit all error messages.
1183 Enable compatibility mode. @xref{Implementation Differences}, for the
1184 list of incompatibilities between @code{groff} and @acronym{AT&T}
1187 @item -d@var{c}@var{s}
1188 @itemx -d@var{name}=@var{s}
1189 Define @var{c} or @var{name} to be a string@tie{}@var{s}. @var{c}@tie{}must
1190 be a one-letter name; @var{name} can be of arbitrary length. All string
1191 assignments happen before loading any macro file (including the start-up
1195 Use @var{fam} as the default font family. @xref{Font Families}.
1198 Read in the file @file{@var{name}.tmac}. Normally @code{groff} searches
1199 for this in its macro directories. If it isn't found, it tries
1200 @file{tmac.@var{name}} (searching in the same directories).
1203 Number the first page @var{num}.
1206 @cindex print current page register (@code{.P})
1207 Output only pages in @var{list}, which is a comma-separated list of page
1208 ranges; @samp{@var{n}} means print page@tie{}@var{n}, @samp{@var{m}-@var{n}}
1209 means print every page between @var{m} and@tie{}@var{n}, @samp{-@var{n}}
1210 means print every page up to@tie{}@var{n}, @samp{@var{n}-} means print every
1211 page beginning with@tie{}@var{n}. @code{gtroff} exits after printing the
1212 last page in the list. All the ranges are inclusive on both ends.
1214 Within @code{gtroff}, this information can be extracted with the
1215 @samp{.P} register. @xref{Built-in Registers}.
1217 If your document restarts page numbering at the beginning of each
1218 chapter, then @code{gtroff} prints the specified page range for each
1221 @item -r@var{c}@var{n}
1222 @itemx -r@var{name}=@var{n}
1223 Set number register@tie{}@var{c} or @var{name} to the value@tie{}@var{n}.
1224 @var{c}@tie{}must be a one-letter name; @var{name} can be of arbitrary
1225 length. @var{n}@tie{}can be any @code{gtroff} numeric expression. All
1226 register assignments happen before loading any macro file (including
1230 Search @file{@var{dir}} for subdirectories @file{dev@var{name}}
1231 (@var{name} is the name of the device), for the @file{DESC} file, and
1232 for font files before looking in the standard directories (@pxref{Font
1233 Directories}). This option is passed to all pre- and postprocessors
1234 using the @env{GROFF_FONT_PATH} environment variable.
1237 Search directory @file{@var{dir}} for macro files before the standard
1238 directories (@pxref{Macro Directories}).
1241 This option may be used to specify a directory to search for files.
1242 It is passed to the following programs:
1246 @code{gsoelim} (see @ref{gsoelim} for more details);
1247 it also implies @code{groff}'s @option{-s} option.
1250 @code{gtroff}; it is used to search files named in the @code{psbb} and
1254 @code{grops}; it is used to search files named in the
1255 @w{@code{\X'ps: import}} and @w{@code{\X'ps: file}} escapes.
1258 The current directory is always searched first. This option may be specified
1259 more than once; the directories will be searched in the order specified. No
1260 directory search is performed for files specified using an absolute path.
1264 @c =====================================================================
1266 @node Environment, Macro Directories, Groff Options, Invoking groff
1267 @section Environment
1268 @cindex environment variables
1269 @cindex variables in environment
1271 There are also several environment variables (of the operating system,
1272 not within @code{gtroff}) which can modify the behavior of @code{groff}.
1275 @item GROFF_COMMAND_PREFIX
1276 @tindex GROFF_COMMAND_PREFIX@r{, environment variable}
1277 @cindex command prefix
1278 @cindex prefix, for commands
1279 If this is set to@tie{}@var{X}, then @code{groff} runs @code{@var{X}troff}
1280 instead of @code{gtroff}. This also applies to @code{tbl}, @code{pic},
1281 @code{eqn}, @code{grn}, @code{refer}, and @code{soelim}. It does not
1282 apply to @code{grops}, @code{grodvi}, @code{grotty}, @code{pre-grohtml},
1283 @code{post-grohtml}, @code{grolj4}, and @code{gxditview}.
1285 The default command prefix is determined during the installation process.
1286 If a non-GNU troff system is found, prefix @samp{g} is used, none
1289 @item GROFF_TMAC_PATH
1290 @tindex GROFF_TMAC_PATH@r{, environment variable}
1291 A colon-separated list of directories in which to search for macro files
1292 (before the default directories are tried). @xref{Macro Directories}.
1294 @item GROFF_TYPESETTER
1295 @tindex GROFF_TYPESETTER@r{, environment variable}
1296 The default output device.
1298 @item GROFF_FONT_PATH
1299 @tindex GROFF_FONT_PATH@r{, environment variable}
1300 A colon-separated list of directories in which to search for the
1301 @code{dev}@var{name} directory (before the default directories are
1302 tried). @xref{Font Directories}.
1304 @item GROFF_BIN_PATH
1305 @tindex GROFF_BIN_PATH@r{, environment variable}
1306 This search path, followed by @code{PATH}, is used for commands executed
1310 @tindex GROFF_TMPDIR@r{, environment variable}
1311 @tindex TMPDIR@r{, environment variable}
1312 The directory in which @code{groff} creates temporary files. If this is
1313 not set and @env{TMPDIR} is set, temporary files are created in that
1314 directory. Otherwise temporary files are created in a system-dependent
1315 default directory (on Unix and GNU/Linux systems, this is usually
1316 @file{/tmp}). @code{grops}, @code{grefer}, @code{pre-grohtml}, and
1317 @code{post-grohtml} can create temporary files in this directory.
1320 Note that MS-DOS and MS-Windows ports of @code{groff} use semi-colons,
1321 rather than colons, to separate the directories in the lists described
1325 @c =====================================================================
1327 @node Macro Directories, Font Directories, Environment, Invoking groff
1328 @section Macro Directories
1329 @cindex macro directories
1330 @cindex directories for macros
1331 @cindex searching macros
1332 @cindex macros, searching
1334 All macro file names must be named @code{@var{name}.tmac} or
1335 @code{tmac.@var{name}} to make the @option{-m@var{name}} command line
1336 option work. The @code{mso} request doesn't have this restriction; any
1337 file name can be used, and @code{gtroff} won't try to append or prepend
1338 the @samp{tmac} string.
1340 @cindex tmac, directory
1341 @cindex directory, for tmac files
1343 @cindex path, for tmac files
1344 @cindex searching macro files
1345 @cindex macro files, searching
1346 @cindex files, macro, searching
1347 Macro files are kept in the @dfn{tmac directories}, all of which
1348 constitute the @dfn{tmac path}. The elements of the search path for
1349 macro files are (in that order):
1353 The directories specified with @code{gtroff}'s or @code{groff}'s
1354 @option{-M} command line option.
1357 @tindex GROFF_TMAC_PATH@r{, environment variable}
1358 The directories given in the @env{GROFF_TMAC_PATH} environment
1365 @cindex mode, unsafe
1366 @cindex current directory
1367 @cindex directory, current
1368 The current directory (only if in unsafe mode using the @option{-U}
1369 command line switch).
1372 @cindex home directory
1373 @cindex directory, home
1377 @cindex site-specific directory
1378 @cindex directory, site-specific
1379 @cindex platform-specific directory
1380 @cindex directory, platform-specific
1381 A platform-dependent directory, a site-specific (platform-independent)
1382 directory, and the main tmac directory; the default locations are
1385 /usr/local/lib/groff/site-tmac
1386 /usr/local/share/groff/site-tmac
1387 /usr/local/share/groff/1.18.2/tmac
1391 assuming that the version of @code{groff} is 1.18.2, and the installation
1392 prefix was @file{/usr/local}. It is possible to fine-tune those
1393 directories during the installation process.
1397 @c =====================================================================
1399 @node Font Directories, Paper Size, Macro Directories, Invoking groff
1400 @section Font Directories
1401 @cindex font directories
1402 @cindex directories for fonts
1403 @cindex searching fonts
1404 @cindex fonts, searching
1406 Basically, there is no restriction how font files for @code{groff} are
1407 named and how long font names are; however, to make the font family
1408 mechanism work (@pxref{Font Families}), fonts within a family should
1409 start with the family name, followed by the shape. For example, the
1410 Times family uses @samp{T} for the family name and @samp{R}, @samp{B},
1411 @samp{I}, and @samp{BI} to indicate the shapes `roman', `bold',
1412 `italic', and `bold italic', respectively. Thus the final font names
1413 are @samp{TR}, @samp{TB}, @samp{TI}, and @samp{TBI}.
1416 @cindex path, for font files
1417 All font files are kept in the @dfn{font directories} which constitute
1418 the @dfn{font path}. The file search functions will always append the
1419 directory @code{dev}@var{name}, where @var{name} is the name of the
1420 output device. Assuming, say, DVI output, and @file{/foo/bar} as a
1421 font directory, the font files for @code{grodvi} must be in
1422 @file{/foo/bar/devdvi}.
1424 The elements of the search path for font files are (in that order):
1428 The directories specified with @code{gtroff}'s or @code{groff}'s
1429 @option{-F} command line option. All device drivers and some
1430 preprocessors also have this option.
1433 @tindex GROFF_FONT_PATH@r{, environment variable}
1434 The directories given in the @env{GROFF_FONT_PATH} environment
1438 @cindex site-specific directory
1439 @cindex directory, site-specific
1440 A site-specific directory and the main font directory; the default
1444 /usr/local/share/groff/site-font
1445 /usr/local/share/groff/1.18.2/font
1449 assuming that the version of @code{groff} is 1.18.2, and the installation
1450 prefix was @file{/usr/local}. It is possible to fine-tune those
1451 directories during the installation process.
1455 @c =====================================================================
1457 @node Paper Size, Invocation Examples, Font Directories, Invoking groff
1461 @cindex landscape page orientation
1462 @cindex orientation, landscape
1463 @cindex page orientation, landscape
1465 In groff, the page size for @code{gtroff} and for output devices are
1466 handled separately. @xref{Page Layout}, for vertical manipulation of
1467 the page size. @xref{Line Layout}, for horizontal changes.
1469 A default paper size can be set in the device's @file{DESC} file. Most
1470 output devices also have a command line option @option{-p} to override
1471 the default paper size and option @option{-l} to use landscape
1472 orientation. @xref{DESC File Format}, for a description of the
1473 @code{papersize} keyword which takes the same argument as @option{-p}.
1475 @pindex papersize.tmac
1477 A convenient shorthand to set a particular paper size for @code{gtroff}
1478 is command line option @option{-dpaper=@var{size}}. This defines string
1479 @code{paper} which is processed in file @file{papersize.tmac} (loaded in
1480 the start-up file @file{troffrc} by default). Possible values for
1481 @var{size} are the same as the predefined values for the
1482 @code{papersize} keyword (but only in lowercase) except
1483 @code{a7}-@code{d7}. An appended @samp{l} (ell) character denotes
1484 landscape orientation.
1486 For example, use the following for PS output on A4 paper in landscape
1490 groff -Tps -dpaper=a4l -P-pa4 -P-l -ms foo.ms > foo.ps
1493 Note that it is up to the particular macro package to respect default
1494 page dimensions set in this way (most do).
1497 @c =====================================================================
1499 @node Invocation Examples, , Paper Size, Invoking groff
1500 @section Invocation Examples
1501 @cindex invocation examples
1502 @cindex examples of invocation
1504 This section lists several common uses of @code{groff} and the
1505 corresponding command lines.
1512 This command processes @file{file} without a macro package or a
1513 preprocessor. The output device is the default, @samp{ps}, and the
1514 output is sent to @code{stdout}.
1517 groff -t -mandoc -Tascii file | less
1521 This is basically what a call to the @code{man} program does.
1522 @code{gtroff} processes the manual page @file{file} with the
1523 @file{mandoc} macro file (which in turn either calls the @file{man} or
1524 the @file{mdoc} macro package), using the @code{tbl} preprocessor and
1525 the @acronym{ASCII} output device. Finally, the @code{less} pager
1526 displays the result.
1533 Preview @file{file} with @code{gxditview}, using the @file{me} macro
1534 package. Since no @option{-T} option is specified, use the default
1535 device (@samp{ps}). Note that you can either say @w{@samp{-m me}} or
1536 @w{@samp{-me}}; the latter is an anachronism from the early days of
1537 @acronym{UNIX}.@footnote{The same is true for the other main macro
1538 packages that come with @code{groff}: @file{man}, @file{mdoc},
1539 @file{ms}, @file{mm}, and @file{mandoc}. This won't work in general;
1540 for example, to load @file{trace.tmac}, either @samp{-mtrace} or
1541 @w{@samp{-m trace}} must be used.}
1544 groff -man -rD1 -z file
1548 Check @file{file} with the @file{man} macro package, forcing
1549 double-sided printing -- don't produce any output.
1555 @c ---------------------------------------------------------------------
1557 @node grog, , Invocation Examples, Invocation Examples
1558 @subsection @code{grog}
1561 @code{grog} reads files, guesses which of the @code{groff} preprocessors
1562 and/or macro packages are required for formatting them, and prints the
1563 @code{groff} command including those options on the standard output. It
1564 generates one or more of the options @option{-e}, @option{-man},
1565 @option{-me}, @option{-mm}, @option{-mom}, @option{-ms}, @option{-mdoc},
1566 @option{-mdoc-old}, @option{-p}, @option{-R}, @option{-g}, @option{-G},
1567 @option{-s}, and @option{-t}.
1569 A special file name@tie{}@file{-} refers to the standard input. Specifying
1570 no files also means to read the standard input. Any specified options
1571 are included in the printed command. No space is allowed between
1572 options and their arguments. The only options recognized are
1573 @option{-C} (which is also passed on) to enable compatibility mode, and
1574 @option{-v} to print the version number and exit.
1583 guesses the appropriate command to print @file{paper.ms} and then prints
1584 it to the command line after adding the @option{-Tdvi} option. For
1585 direct execution, enclose the call to @code{grog} in backquotes at the
1586 @acronym{UNIX} shell prompt:
1589 `grog -Tdvi paper.ms` > paper.dvi
1593 As seen in the example, it is still necessary to redirect the output to
1594 something meaningful (i.e.@: either a file or a pager program like
1599 @c =====================================================================
1600 @c =====================================================================
1602 @node Tutorial for Macro Users, Macro Packages, Invoking groff, Top
1603 @chapter Tutorial for Macro Users
1604 @cindex tutorial for macro users
1605 @cindex macros, tutorial for users
1606 @cindex user's tutorial for macros
1607 @cindex user's macro tutorial
1609 Most users tend to use a macro package to format their papers. This
1610 means that the whole breadth of @code{groff} is not necessary for most
1611 people. This chapter covers the material needed to efficiently use a
1620 @c =====================================================================
1622 @node Basics, Common Features, Tutorial for Macro Users, Tutorial for Macro Users
1624 @cindex basics of macros
1625 @cindex macro basics
1627 This section covers some of the basic concepts necessary to understand
1628 how to use a macro package.@footnote{This section is derived from
1629 @cite{Writing Papers with nroff using -me} by Eric P.@tie{}Allman.}
1630 References are made throughout to more detailed information, if desired.
1632 @code{gtroff} reads an input file prepared by the user and outputs a
1633 formatted document suitable for publication or framing. The input
1634 consists of text, or words to be printed, and embedded commands
1635 (@dfn{requests} and @dfn{escapes}), which tell @code{gtroff} how to
1636 format the output. For more detail on this, see @ref{Embedded
1639 The word @dfn{argument} is used in this chapter to mean a word or number
1640 which appears on the same line as a request, and which modifies the
1641 meaning of that request. For example, the request
1648 spaces one line, but
1655 spaces four lines. The number@tie{}4 is an argument to the @code{sp}
1656 request which says to space four lines instead of one. Arguments are
1657 separated from the request and from each other by spaces (@emph{no}
1658 tabs). More details on this can be found in @ref{Request and Macro
1661 The primary function of @code{gtroff} is to collect words from input
1662 lines, fill output lines with those words, justify the right-hand margin
1663 by inserting extra spaces in the line, and output the result. For
1671 Four score and seven
1676 is read, packed onto output lines, and justified to produce:
1679 Now is the time for all good men to come to the aid of their party.
1680 Four score and seven years ago, etc.
1685 Sometimes a new output line should be started even though the current
1686 line is not yet full; for example, at the end of a paragraph. To do
1687 this it is possible to cause a @dfn{break}, which starts a new output
1688 line. Some requests cause a break automatically, as normally do blank
1689 input lines and input lines beginning with a space.
1691 Not all input lines are text to be formatted. Some input lines are
1692 requests which describe how to format the text. Requests always have a
1693 period (@samp{.}) or an apostrophe (@samp{'}) as the first character of
1696 The text formatter also does more complex things, such as automatically
1697 numbering pages, skipping over page boundaries, putting footnotes in the
1698 correct place, and so forth.
1700 Here are a few hints for preparing text for input to @code{gtroff}.
1704 First, keep the input lines short. Short input lines are easier to
1705 edit, and @code{gtroff} packs words onto longer lines anyhow.
1708 In keeping with this, it is helpful to begin a new line after every
1709 comma or phrase, since common corrections are to add or delete sentences
1713 End each sentence with two spaces -- or better, start each sentence on a
1714 new line. @code{gtroff} recognizes characters that usually end a
1715 sentence, and inserts sentence space accordingly.
1718 Do not hyphenate words at the end of lines -- @code{gtroff} is smart
1719 enough to hyphenate words as needed, but is not smart enough to take
1720 hyphens out and join a word back together. Also, words such as
1721 ``mother-in-law'' should not be broken over a line, since then a space
1722 can occur where not wanted, such as ``@w{mother- in}-law''.
1725 @cindex double-spacing (@code{ls})
1727 @code{gtroff} double-spaces output text automatically if you use the
1728 request @w{@samp{.ls 2}}. Reactivate single-spaced mode by typing
1729 @w{@samp{.ls 1}}.@footnote{If you need finer granularity of the
1730 vertical space, use the @code{pvs} request (@pxref{Changing Type
1733 A number of requests allow to change the way the output looks,
1734 sometimes called the @dfn{layout} of the output page. Most of these
1735 requests adjust the placing of @dfn{whitespace} (blank lines or
1738 @cindex new page (@code{bp})
1739 The @code{bp} request starts a new page, causing a line break.
1741 @cindex blank line (@code{sp})
1742 @cindex empty line (@code{sp})
1743 @cindex line, empty (@code{sp})
1744 The request @w{@samp{.sp @var{N}}} leaves @var{N}@tie{}lines of blank
1745 space. @var{N}@tie{}can be omitted (meaning skip a single line) or can
1746 be of the form @var{N}i (for @var{N}@tie{}inches) or @var{N}c (for
1747 @var{N}@tie{}centimeters). For example, the input:
1751 My thoughts on the subject
1756 leaves one and a half inches of space, followed by the line ``My
1757 thoughts on the subject'', followed by a single blank line (more
1758 measurement units are available, see @ref{Measurements}).
1760 @cindex centering lines (@code{ce})
1761 @cindex lines, centering (@code{ce})
1762 Text lines can be centered by using the @code{ce} request. The line
1763 after @code{ce} is centered (horizontally) on the page. To center more
1764 than one line, use @w{@samp{.ce @var{N}}} (where @var{N} is the number
1765 of lines to center), followed by the @var{N}@tie{}lines. To center many
1766 lines without counting them, type:
1775 The @w{@samp{.ce 0}} request tells @code{groff} to center zero more
1776 lines, in other words, stop centering.
1778 @cindex line break (@code{br})
1779 @cindex break (@code{br})
1780 All of these requests cause a break; that is, they always start a new
1781 line. To start a new line without performing any other action, use
1785 @c =====================================================================
1787 @node Common Features, , Basics, Tutorial for Macro Users
1788 @section Common Features
1789 @cindex common features
1790 @cindex features, common
1792 @code{gtroff} provides very low-level operations for formatting a
1793 document. There are many common routine operations which are done in
1794 all documents. These common operations are written into @dfn{macros}
1795 and collected into a @dfn{macro package}.
1797 All macro packages provide certain common capabilities which fall into
1798 the following categories.
1802 * Sections and Chapters::
1803 * Headers and Footers::
1804 * Page Layout Adjustment::
1806 * Footnotes and Annotations::
1807 * Table of Contents::
1810 * Multiple Columns::
1811 * Font and Size Changes::
1812 * Predefined Strings::
1813 * Preprocessor Support::
1814 * Configuration and Customization::
1817 @c ---------------------------------------------------------------------
1819 @node Paragraphs, Sections and Chapters, Common Features, Common Features
1820 @subsection Paragraphs
1823 One of the most common and most used capability is starting a
1824 paragraph. There are a number of different types of paragraphs, any
1825 of which can be initiated with macros supplied by the macro package.
1826 Normally, paragraphs start with a blank line and the first line
1827 indented, like the text in this manual. There are also block style
1828 paragraphs, which omit the indentation:
1831 Some men look at constitutions with sanctimonious
1832 reverence, and deem them like the ark of the covenant, too
1833 sacred to be touched.
1837 And there are also indented paragraphs which begin with a tag or label
1838 at the margin and the remaining text indented.
1841 one This is the first paragraph. Notice how the first
1842 line of the resulting paragraph lines up with the
1843 other lines in the paragraph.
1847 This paragraph had a long label. The first
1848 character of text on the first line does not line up
1849 with the text on second and subsequent lines,
1850 although they line up with each other.
1853 A variation of this is a bulleted list.
1856 . Bulleted lists start with a bullet. It is possible
1857 to use other glyphs instead of the bullet. In nroff
1858 mode using the ASCII character set for output, a dot
1859 is used instead of a real bullet.
1862 @c ---------------------------------------------------------------------
1864 @node Sections and Chapters, Headers and Footers, Paragraphs, Common Features
1865 @subsection Sections and Chapters
1867 Most macro packages supply some form of section headers. The simplest
1868 kind is simply the heading on a line by itself in bold type. Others
1869 supply automatically numbered section heading or different heading
1870 styles at different levels. Some, more sophisticated, macro packages
1871 supply macros for starting chapters and appendices.
1873 @c ---------------------------------------------------------------------
1875 @node Headers and Footers, Page Layout Adjustment, Sections and Chapters, Common Features
1876 @subsection Headers and Footers
1878 Every macro package gives some way to manipulate the @dfn{headers} and
1879 @dfn{footers} (also called @dfn{titles}) on each page. This is text
1880 put at the top and bottom of each page, respectively, which contain
1881 data like the current page number, the current chapter title, and so
1882 on. Its appearance is not affected by the running text. Some packages
1883 allow for different ones on the even and odd pages (for material printed
1886 The titles are called @dfn{three-part titles}, that is, there is a
1887 left-justified part, a centered part, and a right-justified part. An
1888 automatically generated page number may be put in any of these fields
1889 with the @samp{%} character (see @ref{Page Layout}, for more details).
1891 @c ---------------------------------------------------------------------
1893 @node Page Layout Adjustment, Displays, Headers and Footers, Common Features
1894 @subsection Page Layout
1896 Most macro packages let the user specify top and bottom margins and
1897 other details about the appearance of the printed pages.
1899 @c ---------------------------------------------------------------------
1901 @node Displays, Footnotes and Annotations, Page Layout Adjustment, Common Features
1902 @subsection Displays
1905 @dfn{Displays} are sections of text to be set off from the body of
1906 the paper. Major quotes, tables, and figures are types of displays, as
1907 are all the examples used in this document.
1909 @cindex quotes, major
1910 @cindex major quotes
1911 @dfn{Major quotes} are quotes which are several lines long, and hence
1912 are set in from the rest of the text without quote marks around them.
1915 A @dfn{list} is an indented, single-spaced, unfilled display. Lists
1916 should be used when the material to be printed should not be filled and
1917 justified like normal text, such as columns of figures or the examples
1921 A @dfn{keep} is a display of lines which are kept on a single page if
1922 possible. An example for a keep might be a diagram. Keeps differ from
1923 lists in that lists may be broken over a page boundary whereas keeps are
1926 @cindex keep, floating
1927 @cindex floating keep
1928 @dfn{Floating keeps} move relative to the text. Hence, they are good for
1929 things which are referred to by name, such as ``See figure@tie{}3''. A
1930 floating keep appears at the bottom of the current page if it fits;
1931 otherwise, it appears at the top of the next page. Meanwhile, the
1932 surrounding text `flows' around the keep, thus leaving no blank areas.
1934 @c ---------------------------------------------------------------------
1936 @node Footnotes and Annotations, Table of Contents, Displays, Common Features
1937 @subsection Footnotes and Annotations
1941 There are a number of requests to save text for later printing.
1943 @dfn{Footnotes} are printed at the bottom of the current page.
1945 @cindex delayed text
1946 @dfn{Delayed text} is very similar to a footnote except that it is
1947 printed when called for explicitly. This allows a list of references to
1948 appear (for example) at the end of each chapter, as is the convention in
1951 Most macro packages which supply this functionality also supply a means
1952 of automatically numbering either type of annotation.
1954 @c ---------------------------------------------------------------------
1956 @node Table of Contents, Indices, Footnotes and Annotations, Common Features
1957 @subsection Table of Contents
1958 @cindex table of contents
1959 @cindex contents, table of
1961 @dfn{Tables of contents} are a type of delayed text having a tag
1962 (usually the page number) attached to each entry after a row of dots.
1963 The table accumulates throughout the paper until printed, usually after
1964 the paper has ended. Many macro packages provide the ability to have
1965 several tables of contents (e.g.@: a standard table of contents, a list
1968 @c ---------------------------------------------------------------------
1970 @node Indices, Paper Formats, Table of Contents, Common Features
1972 @cindex index, in macro package
1974 While some macro packages use the term @dfn{index}, none actually
1975 provide that functionality. The facilities they call indices are
1976 actually more appropriate for tables of contents.
1979 To produce a real index in a document, external tools like the
1980 @code{makeindex} program are necessary.
1982 @c ---------------------------------------------------------------------
1984 @node Paper Formats, Multiple Columns, Indices, Common Features
1985 @subsection Paper Formats
1986 @cindex paper formats
1988 Some macro packages provide stock formats for various kinds of
1989 documents. Many of them provide a common format for the title and
1990 opening pages of a technical paper. The @file{mm} macros in particular
1991 provide formats for letters and memoranda.
1993 @c ---------------------------------------------------------------------
1995 @node Multiple Columns, Font and Size Changes, Paper Formats, Common Features
1996 @subsection Multiple Columns
1998 Some macro packages (but not @file{man}) provide the ability to have two
1999 or more columns on a page.
2001 @c ---------------------------------------------------------------------
2003 @node Font and Size Changes, Predefined Strings, Multiple Columns, Common Features
2004 @subsection Font and Size Changes
2006 The built-in font and size functions are not always intuitive, so all
2007 macro packages provide macros to make these operations simpler.
2009 @c ---------------------------------------------------------------------
2011 @node Predefined Strings, Preprocessor Support, Font and Size Changes, Common Features
2012 @subsection Predefined Strings
2014 Most macro packages provide various predefined strings for a variety of
2015 uses; examples are sub- and superscripts, printable dates, quotes and
2016 various special characters.
2018 @c ---------------------------------------------------------------------
2020 @node Preprocessor Support, Configuration and Customization, Predefined Strings, Common Features
2021 @subsection Preprocessor Support
2023 All macro packages provide support for various preprocessors and may
2024 extend their functionality.
2026 For example, all macro packages mark tables (which are processed with
2027 @code{gtbl}) by placing them between @code{TS} and @code{TE} macros.
2028 The @file{ms} macro package has an option, @samp{.TS@tie{}H}, that prints
2029 a caption at the top of a new page (when the table is too long to fit on
2032 @c ---------------------------------------------------------------------
2034 @node Configuration and Customization, , Preprocessor Support, Common Features
2035 @subsection Configuration and Customization
2037 Some macro packages provide means of customizing many of the details of
2038 how the package behaves. This ranges from setting the default type size
2039 to changing the appearance of section headers.
2043 @c =====================================================================
2044 @c =====================================================================
2046 @node Macro Packages, gtroff Reference, Tutorial for Macro Users, Top
2047 @chapter Macro Packages
2048 @cindex macro packages
2049 @cindex packages, macros
2051 This chapter documents the main macro packages that come with
2054 Different main macro packages can't be used at the same time; for example
2057 groff -m man foo.man -m ms bar.doc
2061 doesn't work. Note that option arguments are processed before non-option
2062 arguments; the above (failing) sample is thus reordered to
2065 groff -m man -m ms foo.man bar.doc
2077 @c =====================================================================
2079 @node man, mdoc, Macro Packages, Macro Packages
2081 @cindex manual pages
2085 @pindex man-old.tmac
2087 This is the most popular and probably the most important macro package
2088 of @code{groff}. It is easy to use, and a vast majority of manual pages
2095 * Miscellaneous man macros::
2096 * Predefined man strings::
2097 * Preprocessors in man pages::
2098 * Optional man extensions::
2101 @c ---------------------------------------------------------------------
2103 @node Man options, Man usage, man, man
2106 The command line format for using the @file{man} macros with
2110 groff -m man [ -rLL=@var{length} ] [ -rLT=@var{length} ] [ -rFT=@var{dist} ]
2111 [ -rcR=1 ] [ -rC1 ] [ -rD1 ] [-rHY=@var{flags} ]
2112 [ -rP@var{nnn} ] [ -rS@var{xx} ] [ -rX@var{nnn} ]
2113 [ -rIN=@var{length} ] [ -rSN=@var{length} ] [ @var{files}@dots{} ]
2117 It is possible to use @samp{-man} instead of @w{@samp{-m man}}.
2121 This option (the default if a TTY output device is used) creates a
2122 single, very long page instead of multiple pages. Use @code{-rcR=0}
2126 If more than one manual page is given on the command line, number the
2127 pages continuously, rather than starting each at@tie{}1.
2130 Double-sided printing. Footers for even and odd pages are formatted
2133 @item -rFT=@var{dist}
2134 Set the position of the footer text to @var{dist}. If positive, the
2135 distance is measured relative to the top of the page, otherwise it is
2136 relative to the bottom. The default is @minus{}0.5@dmn{i}.
2138 @item -rHY=@var{flags}
2139 Set hyphenation flags. Possible values are 1@tie{}to hyphenate without
2140 restrictions, 2@tie{} to not hyphenate the last word on a page,
2141 4@tie{}to not hyphenate the last two characters of a word, and
2142 8@tie{}to not hyphenate the first two characters of a word. These
2143 values are additive; the default is@tie{}14.
2145 @item -rIN=@var{length}
2146 Set the body text indent to @var{length}.
2147 If not specified, the indent defaults to 7@dmn{n}
2148 (7@tie{}characters) in nroff mode and 7.2@dmn{n} otherwise.
2149 For nroff, this value should always be an integer multiple of unit @samp{n}
2150 to get consistent indentation.
2152 @item -rLL=@var{length}
2153 Set line length to @var{length}. If not specified, the line length
2154 defaults to 78@tie{}en in nroff mode (this is 78@tie{}characters per
2155 line) and 6.5@tie{}inch otherwise.
2157 @item -rLT=@var{length}
2158 Set title length to @var{length}. If not specified, the title length
2159 defaults to the line length.
2162 Page numbering starts with @var{nnn} rather than with@tie{}1.
2165 Use @var{xx} (which can be 10, 11, or@tie{}12@dmn{pt}) as the base
2166 document font size instead of the default value of@tie{}10@dmn{pt}.
2168 @item -rSN=@var{length}
2169 Set the indent for sub-subheadings to @var{length}.
2170 If not specified, the indent defaults to 3@dmn{n}.
2173 After page @var{nnn}, number pages as @var{nnn}a, @var{nnn}b,
2174 @var{nnn}c, etc. For example, the option @option{-rX2} produces the
2175 following page numbers: 1, 2, 2a, 2b, 2c, etc.
2178 @c ---------------------------------------------------------------------
2180 @node Man usage, Man font macros, Man options, man
2182 @cindex @code{man} macros
2183 @cindex macros for manual pages [@code{man}]
2186 This section describes the available macros for manual pages. For
2187 further customization, put additional macros and requests into the file
2188 @file{man.local} which is loaded immediately after the @file{man}
2191 @Defmac {TH, title section [@Var{extra1} [@Var{extra2} [@Var{extra3}]]], man}
2192 Set the title of the man page to @var{title} and the section to
2193 @var{section}, which must have a value between 1 and@tie{}8. The value
2194 of @var{section} may also have a string appended, e.g.@: @samp{.pm},
2195 to indicate a specific subsection of the man pages.
2197 Both @var{title} and @var{section} are positioned at the left and right
2198 in the header line (with @var{section} in parentheses immediately
2199 appended to @var{title}. @var{extra1} is positioned in the middle of
2200 the footer line. @var{extra2} is positioned at the left in the footer
2201 line (or at the left on even pages and at the right on odd pages if
2202 double-sided printing is active). @var{extra3} is centered in the
2205 For @acronym{HTML} output, headers and footers are completely suppressed.
2207 Additionally, this macro starts a new page; the new line number is@tie{}1
2208 again (except if the @option{-rC1} option is given on the command line)
2209 -- this feature is intended only for formatting multiple man pages; a
2210 single man page should contain exactly one @code{TH} macro at the
2211 beginning of the file.
2214 @Defmac {SH, [@Var{heading}], man}
2215 Set up an unnumbered section heading sticking out to the left. Prints
2216 out all the text following @code{SH} up to the end of the line (or the
2217 text in the next line if there is no argument to @code{SH}) in bold
2218 face (or the font specified by the string @code{HF}), one size larger than
2219 the base document size. Additionally, the left margin and the indentation
2220 for the following text is reset to its default value.
2223 @Defmac {SS, [@Var{heading}], man}
2224 Set up an unnumbered (sub)section heading. Prints out all the text
2225 following @code{SS} up to the end of the line (or the text in the next
2226 line if there is no argument to @code{SS}) in bold face (or the font
2227 specified by the string @code{HF}), at the same size as the base document
2228 size. Additionally, the left margin and the indentation for the
2229 following text is reset to its default value.
2232 @Defmac {TP, [@Var{nnn}], man}
2233 Set up an indented paragraph with label. The indentation is set to
2234 @var{nnn} if that argument is supplied (the default unit is @samp{n}
2235 if omitted), otherwise it is set to the previous indentation value
2236 specified with @code{TP}, @code{IP}, or @code{HP} (or to the default
2237 value if none of them have been used yet).
2239 The first line of text following this macro is interpreted as a string
2240 to be printed flush-left, as it is appropriate for a label. It is not
2241 interpreted as part of a paragraph, so there is no attempt to fill the
2242 first line with text from the following input lines. Nevertheless, if
2243 the label is not as wide as the indentation the paragraph starts
2244 at the same line (but indented), continuing on the following lines.
2245 If the label is wider than the indentation the descriptive part
2246 of the paragraph begins on the line following the label, entirely
2247 indented. Note that neither font shape nor font size of the label is
2248 set to a default value; on the other hand, the rest of the text has
2249 default font settings.
2252 @DefmacList {LP, , man}
2253 @DefmacItem {PP, , man}
2254 @DefmacListEnd {P, , man}
2255 These macros are mutual aliases. Any of them causes a line break at
2256 the current position, followed by a vertical space downwards by the
2257 amount specified by the @code{PD} macro. The font size and shape are
2258 reset to the default value (10@dmn{pt} roman if no @option{-rS} option
2259 is given on the command line). Finally, the current left margin and the
2260 indentation is restored.
2263 @Defmac {IP, [@Var{designator} [@Var{nnn}]], man}
2264 Set up an indented paragraph, using @var{designator} as a tag to mark
2265 its beginning. The indentation is set to @var{nnn} if that argument
2266 is supplied (default unit is @samp{n}), otherwise it is set to the
2267 previous indentation value specified with @code{TP}, @code{IP}, or
2268 @code{HP} (or the default value if none of them have been used yet).
2269 Font size and face of the paragraph (but not the designator) are reset
2270 to their default values.
2272 To start an indented paragraph with a particular indentation but without
2273 a designator, use @samp{""} (two double quotes) as the first argument of
2276 For example, to start a paragraph with bullets as the designator and
2277 4@tie{}en indentation, write
2284 @Defmac {HP, [@Var{nnn}], man}
2285 @cindex hanging indentation [@code{man}]
2286 @cindex @code{man} macros, hanging indentation
2287 Set up a paragraph with hanging left indentation. The indentation is
2288 set to @var{nnn} if that argument is supplied (default unit is
2289 @samp{n}), otherwise it is set to the previous indentation value
2290 specified with @code{TP}, @code{IP}, or @code{HP} (or the default
2291 value if non of them have been used yet). Font size and face are reset
2292 to their default values.
2295 @Defmac {RS, [@Var{nnn}], man}
2296 @cindex left margin, how to move [@code{man}]
2297 @cindex @code{man} macros, moving left margin
2298 Move the left margin to the right by the value @var{nnn} if specified
2299 (default unit is @samp{n}); otherwise it is set to the previous
2300 indentation value specified with @code{TP}, @code{IP}, or @code{HP}
2301 (or to the default value if none of them have been used yet). The
2302 indentation value is then set to the default.
2304 Calls to the @code{RS} macro can be nested.
2307 @Defmac {RE, [@Var{nnn}], man}
2308 Move the left margin back to level @var{nnn}, restoring the previous left
2309 margin. If no argument is given, it moves one level back. The first
2310 level (i.e., no call to @code{RS} yet) has number@tie{}1, and each call
2311 to @code{RS} increases the level by@tie{}1.
2314 @cindex line breaks, with vertical space [@code{man}]
2315 @cindex @code{man} macros, line breaks with vertical space
2316 To summarize, the following macros cause a line break with the insertion
2317 of vertical space (which amount can be changed with the @code{PD}
2318 macro): @code{SH}, @code{SS}, @code{TP}, @code{LP} (@code{PP},
2319 @code{P}), @code{IP}, and @code{HP}.
2321 @cindex line breaks, without vertical space [@code{man}]
2322 @cindex @code{man} macros, line breaks without vertical space
2323 The macros @code{RS} and @code{RE} also cause a break but do not insert
2326 @cindex default indentation, resetting [@code{man}]
2327 @cindex indentaion, resetting to default [@code{man}]
2328 @cindex @code{man} macros, resetting default indentation
2329 Finally, the macros @code{SH}, @code{SS}, @code{LP} (@code{PP}, @code{P}),
2330 and @code{RS} reset the indentation to its default value.
2332 @c ---------------------------------------------------------------------
2334 @node Man font macros, Miscellaneous man macros, Man usage, man
2335 @subsection Macros to set fonts
2336 @cindex font selection [@code{man}]
2337 @cindex @code{man} macros, how to set fonts
2339 The standard font is roman; the default text size is 10@tie{}point.
2340 If command line option @option{-rS=@var{n}} is given, use
2341 @var{n}@dmn{pt} as the default text size.
2343 @Defmac {SM, [@Var{text}], man}
2344 Set the text on the same line or the text on the next line in a font
2345 that is one point size smaller than the default font.
2348 @Defmac {SB, [@Var{text}], man}
2349 @cindex bold face [@code{man}]
2350 @cindex @code{man} macros, bold face
2351 Set the text on the same line or the text on the next line in bold face
2352 font, one point size smaller than the default font.
2355 @Defmac {BI, text, man}
2356 Set its arguments alternately in bold face and italic, without a space
2357 between the arguments. Thus,
2360 .BI this "word and" that
2364 produces ``thisword andthat'' with ``this'' and ``that'' in bold face,
2365 and ``word and'' in italics.
2368 @Defmac {IB, text, man}
2369 Set its arguments alternately in italic and bold face, without a space
2370 between the arguments.
2373 @Defmac {RI, text, man}
2374 Set its arguments alternately in roman and italic, without a space between
2378 @Defmac {IR, text, man}
2379 Set its arguments alternately in italic and roman, without a space between
2383 @Defmac {BR, text, man}
2384 Set its arguments alternately in bold face and roman, without a space
2385 between the arguments.
2388 @Defmac {RB, text, man}
2389 Set its arguments alternately in roman and bold face, without a space
2390 between the arguments.
2393 @Defmac {B, [@Var{text}], man}
2394 Set @var{text} in bold face. If no text is present on the line where
2395 the macro is called, then the text of the next line appears in bold
2399 @Defmac {I, [@Var{text}], man}
2400 @cindex italic fonts [@code{man}]
2401 @cindex @code{man} macros, italic fonts
2402 Set @var{text} in italic. If no text is present on the line where the
2403 macro is called, then the text of the next line appears in italic.
2406 @c ---------------------------------------------------------------------
2408 @node Miscellaneous man macros, Predefined man strings, Man font macros, man
2409 @subsection Miscellaneous macros
2412 @cindex @code{man} macros, default indentation
2413 @cindex default indentation [@code{man}]
2414 The default indentation is 7.2@dmn{n} in troff mode and 7@dmn{n} in
2415 nroff mode except for @code{grohtml} which ignores indentation.
2418 @cindex tab stops [@code{man}]
2419 @cindex @code{man} macros, tab stops
2420 Set tabs every 0.5@tie{}inches. Since this macro is always executed
2421 during a call to the @code{TH} macro, it makes sense to call it only if
2422 the tab positions have been changed.
2425 @Defmac {PD, [@Var{nnn}], man}
2426 @cindex empty space before a paragraph [@code{man}]
2427 @cindex @code{man} macros, empty space before a paragraph
2428 Adjust the empty space before a new paragraph (or section). The
2429 optional argument gives the amount of space (default unit is
2430 @samp{v}); without parameter, the value is reset to its default value
2431 (1@tie{}line in nroff mode, 0.4@dmn{v}@tie{}otherwise).
2433 This affects the macros @code{SH}, @code{SS}, @code{TP}, @code{LP} (as
2434 well as @code{PP} and @code{P}), @code{IP}, and @code{HP}.
2437 The following two macros are included for
2440 @Defmac {AT, [@Var{system} [@Var{release}]], man}
2441 @cindex @code{man}macros, BSD compatibility
2442 Alter the footer for use with @acronym{AT&T} manpages.
2443 This command exists only for compatibility; don't use it.
2444 The first argument @var{system} can be:
2448 7th Edition (the default)
2457 An optional second argument @var{release} to @code{AT} specifies the
2458 release number (such as ``System V Release 3'').
2461 @Defmac {UC, [@Var{version}], man}
2462 @cindex @code{man}macros, BSD compatibility
2463 Alters the footer for use with @acronym{BSD} manpages.
2464 This command exists only for compatibility; don't use it.
2465 The argument can be:
2469 3rd Berkeley Distribution (the default)
2472 4th Berkeley Distribution
2475 4.2 Berkeley Distribution
2478 4.3 Berkeley Distribution
2481 4.4 Berkeley Distribution
2485 @c ---------------------------------------------------------------------
2487 @node Predefined man strings, Preprocessors in man pages, Miscellaneous man macros, man
2488 @subsection Predefined strings
2490 The following strings are defined:
2493 Switch back to the default font size.
2497 The typeface used for headings.
2498 The default is @samp{B}.
2502 The `registered' sign.
2506 The `trademark' sign.
2509 @DefstrList {lq, man}
2510 @DefstrListEnd {rq, man}
2511 @cindex @code{lq} glyph, and @code{lq} string [@code{man}]
2512 @cindex @code{rq} glyph, and @code{rq} string [@code{man}]
2513 Left and right quote. This is equal to @code{\(lq} and @code{\(rq},
2517 @c ---------------------------------------------------------------------
2519 @node Preprocessors in man pages, Optional man extensions, Predefined man strings, man
2520 @subsection Preprocessors in @file{man} pages
2522 @cindex preprocessor, calling convention
2523 @cindex calling convention of preprocessors
2524 If a preprocessor like @code{gtbl} or @code{geqn} is needed, it has
2525 become common usage to make the first line of the man page look like
2532 @pindex geqn@r{, invocation in manual pages}
2533 @pindex grefer@r{, invocation in manual pages}
2534 @pindex gtbl@r{, invocation in manual pages}
2535 @pindex man@r{, invocation of preprocessors}
2537 Note the single space character after the double quote. @var{word}
2538 consists of letters for the needed preprocessors: @samp{e} for
2539 @code{geqn}, @samp{r} for @code{grefer}, @samp{t} for @code{gtbl}.
2540 Modern implementations of the @code{man} program read this first line
2541 and automatically call the right preprocessor(s).
2543 @c ---------------------------------------------------------------------
2545 @node Optional man extensions, , Preprocessors in man pages, man
2546 @subsection Optional @file{man} extensions
2549 Use the file @file{man.local} for local extensions
2550 to the @code{man} macros or for style changes.
2552 @unnumberedsubsubsec Custom headers and footers
2553 @cindex @code{man} macros, custom headers and footers
2555 In groff versions 1.18.2 and later, you can specify custom
2556 headers and footers by redefining the following macros in
2560 Control the content of the headers.
2561 Normally, the header prints the command name
2562 and section number on either side, and the
2563 optional fifth argument to @code{TH} in the center.
2567 Control the content of the footers.
2568 Normally, the footer prints the page number
2569 and the third and fourth arguments to @code{TH}.
2571 Use the @code{FT} number register to specify the
2573 The default is @minus{}0.5@dmn{i}.
2576 @unnumberedsubsubsec Ultrix-specific man macros
2577 @cindex Ultrix-specific @code{man} macros
2578 @cindex @code{man} macros, Ultrix-specific
2581 The @code{groff} source distribution includes
2582 a file named @file{man.ultrix}, containing
2583 macros compatible with the Ultrix variant of
2585 Copy this file into @file{man.local} (or use the @code{mso} request to
2586 load it) to enable the following macros.
2588 @Defmac {CT, @Var{key}, man}
2589 Print @samp{<CTRL/@var{key}>}.
2593 Print subsequent text using the constant width (Courier) typeface.
2597 Begin a non-filled display.
2601 End a non-filled display started with @code{Ds}.
2604 @Defmac {EX, [@Var{indent}], man}
2605 Begins a non-filled display
2606 using the constant width (Courier) typeface.
2607 Use the optional @var{indent} argument to
2612 End a non-filled display started with @code{EX}.
2615 @Defmac {G, [@Var{text}], man}
2616 Sets @var{text} in Helvetica.
2617 If no text is present on the line where
2618 the macro is called, then the text of the
2619 next line appears in Helvetica.
2622 @Defmac {GL, [@Var{text}], man}
2623 Sets @var{text} in Helvetica Oblique.
2624 If no text is present on the line where
2625 the macro is called, then the text of the
2626 next line appears in Helvetica Oblique.
2629 @Defmac {HB, [@Var{text}], man}
2630 Sets @var{text} in Helvetica Bold.
2631 If no text is present on the line where
2632 the macro is called, then all text up to
2633 the next @code{HB} appears in Helvetica Bold.
2636 @Defmac {TB, [@Var{text}], man}
2637 Identical to @code{HB}.
2640 @Defmac {MS, @Var{title} @Var{sect} [@Var{punct}], man}
2641 Set a manpage reference in Ultrix format.
2642 The @var{title} is in Courier instead of italic.
2643 Optional punctuation follows the section number without
2644 an intervening space.
2647 @Defmac {NT, [@code{C}] [@Var{title}], man}
2649 Print the optional @Var{title}, or the word ``Note'',
2650 centered on the page.
2651 Text following the macro makes up the body of the note,
2652 and is indented on both sides.
2653 If the first argument is @code{C}, the body of the
2654 note is printed centered (the second argument replaces
2655 the word ``Note'' if specified).
2659 End a note begun with @code{NT}.
2662 @Defmac {PN, @Var{path} [@Var{punct}], man}
2663 Set the path name in constant width (Courier),
2664 followed by optional punctuation.
2667 @Defmac {Pn, [@Var{punct}] @Var{path} [@Var{punct}], man}
2668 When called with two arguments, identical to @code{PN}.
2669 When called with three arguments,
2670 set the second argument in constant width (Courier),
2671 bracketed by the first and third arguments in the current font.
2675 Switch to roman font and turn off any underlining in effect.
2679 Print the string @samp{<RETURN>}.
2682 @Defmac {VS, [@code{4}], man}
2683 Start printing a change bar in the margin if
2684 the number @code{4} is specified.
2685 Otherwise, this macro does nothing.
2689 End printing the change bar begun by @code{VS}.
2692 @unnumberedsubsubsec Simple example
2694 The following example @file{man.local} file
2695 alters the @code{SH} macro to add some extra
2696 vertical space before printing the heading.
2697 Headings are printed in Helvetica Bold.
2700 .\" Make the heading fonts Helvetica
2703 .\" Put more whitespace in front of headings.
2706 . if t .sp (u;\\n[PD]*2)
2711 @c =====================================================================
2713 @node mdoc, ms, man, Macro Packages
2714 @section @file{mdoc}
2715 @cindex @code{mdoc} macros
2717 @c XXX documentation
2718 @c XXX this is a placeholder until we get stuff knocked into shape
2719 See the @cite{groff_mdoc(7)} man page (type @command{man groff_mdoc}
2720 at the command line).
2723 @c =====================================================================
2725 @node ms, me, mdoc, Macro Packages
2727 @cindex @code{ms} macros
2730 macros are suitable for reports, letters, books,
2731 user manuals, and so forth.
2732 The package provides macros for cover pages, section headings,
2733 paragraphs, lists, footnotes, pagination,
2734 and a table of contents.
2738 * General ms Structure::
2739 * ms Document Control Registers::
2740 * ms Cover Page Macros::
2743 * Differences from AT&T ms::
2746 @c ---------------------------------------------------------------------
2748 @node ms Intro, General ms Structure, ms, ms
2749 @subsection Introduction to @file{ms}
2751 The original @file{-ms} macros were included with
2752 @acronym{AT&T} @code{troff} as well as the
2754 While the @file{man} package is intended for brief documents
2755 that can be read on-line as well as printed, the @file{ms}
2756 macros are suitable for longer documents that are meant to be
2757 printed rather than read on-line.
2759 The @file{ms} macro package included with @code{groff}
2760 is a complete, bottom-up re-implementation.
2761 Several macros (specific to @acronym{AT&T}
2762 or Berkeley) are not included, while several new commands are.
2763 @xref{Differences from AT&T ms}, for more information.
2765 @c ---------------------------------------------------------------------
2767 @node General ms Structure, ms Document Control Registers, ms Intro, ms
2768 @subsection General structure of an @file{ms} document
2769 @cindex @code{ms} macros, general structure
2771 The @file{ms} macro package expects a certain amount of structure,
2772 but not as much as packages such as @file{man} or @file{mdoc}.
2774 The simplest documents can begin with a paragraph macro
2775 (such as @code{LP} or @code{PP}),
2776 and consist of text separated by paragraph macros
2777 or even blank lines.
2778 Longer documents have a structure as follows:
2782 If you invoke the @code{RP}
2783 (report) macro on the first line of the document,
2784 @code{groff} prints the cover page information on its own page;
2785 otherwise it prints the information on the
2786 first page with your document text immediately following.
2787 Other document formats found in @acronym{AT&T} @code{troff}
2788 are specific to @acronym{AT&T} or Berkeley, and are not supported in
2791 @item Format and layout
2792 By setting number registers,
2793 you can change your document's type (font and size),
2794 margins, spacing, headers and footers, and footnotes.
2795 @xref{ms Document Control Registers}, for more details.
2798 A cover page consists of a title, the author's name and institution,
2799 an abstract, and the date.
2800 @footnote{Actually, only the title is required.}
2801 @xref{ms Cover Page Macros}, for more details.
2804 Following the cover page is your document.
2805 You can use the @file{ms}
2806 macros to write reports, letters, books, and so forth.
2807 The package is designed for structured documents,
2808 consisting of paragraphs interspersed with headings
2809 and augmented by lists, footnotes, tables, and other
2811 @xref{ms Body Text}, for more details.
2813 @item Table of contents
2814 Longer documents usually include a table of contents,
2815 which you can invoke by placing the
2817 macro at the end of your document.
2819 macros have minimal indexing facilities, consisting of the
2820 @code{IX} macro, which prints an entry on standard error.
2821 Printing the table of contents at the end is necessary since
2822 @code{groff} is a single-pass text formatter,
2823 thus it cannot determine the page number of each section
2824 until that section has actually been set and printed.
2825 Since @file{ms} output is intended for hardcopy,
2826 you can manually relocate the pages containing
2827 the table of contents between the cover page and the
2828 body text after printing.
2831 @c ---------------------------------------------------------------------
2833 @node ms Document Control Registers, ms Cover Page Macros, General ms Structure, ms
2834 @subsection Document control registers
2835 @cindex @code{ms} macros, document control registers
2837 The following is a list of document control number registers.
2838 For the sake of consistency,
2839 set registers related to margins at the beginning of your document,
2840 or just after the @code{RP} macro.
2841 You can set other registers later in your document,
2842 but you should keep them together at the beginning
2843 to make them easy to find and edit as necessary.
2845 @unnumberedsubsubsec Margin Settings
2848 Defines the page offset (i.e.@: the left margin).
2849 There is no explicit right margin setting; the combination of
2850 the @code{PO} and @code{LL} registers implicitly define the
2853 Effective: next page.
2855 Default value: 1@dmn{i}.
2859 Defines the line length (i.e.@: the width of the body text).
2861 Effective: next paragraph.
2867 Defines the title length (i.e.@: the header and footer width).
2868 This is usually the same as @code{LL}, but not necessarily.
2870 Effective: next paragraph.
2876 Defines the header margin height at the top of the page.
2878 Effective: next page.
2884 Defines the footer margin height at the bottom of the page.
2886 Effective: next page.
2891 @unnumberedsubsubsec Text Settings
2894 Defines the point size of the body text. If the value is larger than or
2895 equal to 1000, divide it by 1000 to get a fractional point size. For
2896 example, @samp{.nr PS 10250} sets the document's point size to 10.25@dmn{p}.
2898 Effective: next paragraph.
2904 Defines the space between lines (line height plus leading). If the value
2905 is larger than or equal to 1000, divide it by 1000 to get a fractional point
2906 size. Due to backwards compatibility, @code{VS} must be smaller than
2907 40000 (this is 40.0@dmn{p}).
2909 Effective: next paragraph.
2914 @Defmpreg {PSINCR, ms}
2915 Defines an increment in point size, which will be applied to section
2916 headings at nesting levels below the value specified in @code{GROWPS}. The
2917 value of @code{PSINCR} should be specified in points, with the @dmn{p}
2918 scaling factor, and may include a fractional component; for example,
2919 @w{@samp{.nr PSINCR 1.5p}} sets a point size increment of 1.5@dmn{p}.
2921 Effective: next section heading.
2926 @Defmpreg {GROWPS, ms}
2927 Defines the heading level below which the point size increment set by
2928 @code{PSINCR} becomes effective. Section headings at and above the level
2929 specified by @code{GROWPS} will be printed at the point size set by @code{PS};
2930 for each level below the value of @code{GROWPS}, the point size will be
2931 increased in steps equal to the value of @code{PSINCR}. Setting @code{GROWPS}
2932 to any value less than@tie{}2 disables the incremental heading size feature.
2934 Effective: next section heading.
2940 Defines the hyphenation level. @code{HY} sets safely the value of the
2941 low-level @code{.hy} register. Setting the value of @code{HY} to 0 is
2942 equivalent to using the @code{.nh} request.
2944 Effective: next paragraph.
2950 Defines the font family used to typeset the document.
2952 Effective: next paragraph.
2954 Default: as defined in the output device.
2957 @unnumberedsubsubsec Paragraph Settings
2960 Defines the initial indent of a @code{.PP} paragraph.
2962 Effective: next paragraph.
2968 Defines the space between paragraphs.
2970 Effective: next paragraph.
2972 Default: 0.3@dmn{v}.
2976 Defines the indent on both sides of a quoted (@code{.QP}) paragraph.
2978 Effective: next paragraph.
2983 @Defmpreg {PORPHANS, ms}
2984 Defines the minimum number of initial lines of any paragraph which should
2985 be kept together, to avoid orphan lines at the bottom of a page. If a new
2986 paragraph is started close to the bottom of a page, and there is insufficient
2987 space to accommodate @code{PORPHANS} lines before an automatic page break,
2988 then the page break will be forced, before the start of the paragraph.
2990 Effective: next paragraph.
2995 @Defmpreg {HORPHANS, ms}
2996 Defines the minimum number of lines of the following paragraph which should
2997 be kept together with any section heading introduced by the @code{NH} or
2998 @code{SH} macros. If a section heading is placed close to the bottom of a
2999 page, and there is insufficient space to accommodate both the heading and
3000 at least @code{HORPHANS} lines of the following paragraph, before an
3001 automatic page break, then the page break will be forced before the heading.
3003 Effective: next paragraph.
3008 @unnumberedsubsubsec Footnote Settings
3011 Defines the length of a footnote.
3013 Effective: next footnote.
3015 Default: @math{@code{@\n[LL]} * 5 / 6}.
3019 Defines the footnote indent.
3021 Effective: next footnote.
3027 The footnote format:
3030 Prints the footnote number as a superscript; indents the footnote (default).
3033 Prints the number followed by a period (like 1.)
3034 and indents the footnote.
3037 Like 1, without an indent.
3040 Like 1, but prints the footnote number as a hanging paragraph.
3043 Effective: next footnote.
3049 Defines the footnote point size. If the value is larger than or equal to
3050 1000, divide it by 1000 to get a fractional point size.
3052 Effective: next footnote.
3054 Default: @math{@code{@\n[PS]} - 2}.
3058 Defines the footnote vertical spacing. If the value is larger than or equal
3059 to 1000, divide it by 1000 to get a fractional point size.
3061 Effective: next footnote.
3063 Default: @math{@code{@\n[FPS]} + 2}.
3067 Defines the footnote paragraph spacing.
3069 Effective: next footnote.
3071 Default: @math{@code{@\n[PD]} / 2}.
3074 @unnumberedsubsubsec Miscellaneous Number Registers
3076 @Defmpreg {MINGW, ms}
3077 Defines the minimum width between columns in a multi-column document.
3079 Effective: next page.
3084 @c ---------------------------------------------------------------------
3086 @node ms Cover Page Macros, ms Body Text, ms Document Control Registers, ms
3087 @subsection Cover page macros
3088 @cindex @code{ms} macros, cover page
3089 @cindex cover page macros, [@code{ms}]
3091 Use the following macros to create a cover page for your document
3094 @Defmac {RP, [@code{no}], ms}
3095 Specifies the report format for your document.
3096 The report format creates a separate cover page.
3097 The default action (no @code{.RP}
3098 macro) is to print a subset of the
3099 cover page on page 1 of your document.
3101 If you use the word @code{no} as an optional argument,
3102 @code{groff} prints a title page but
3103 does not repeat any of the title page information
3104 (title, author, abstract, etc.)
3105 on page 1 of the document.
3108 @Defmac {DA, [@dots{}], ms}
3109 (optional) Print the current date, or the arguments to the macro if any,
3110 on the title page (if specified) and in the footers.
3111 This is the default for @code{nroff}.
3114 @Defmac {ND, [@dots{}], ms}
3115 (optional) Print the current date, or the arguments to the macro if any,
3116 on the title page (if specified) but not in the footers.
3117 This is the default for @code{troff}.
3121 Specifies the document title.
3122 @code{groff} collects text following the @code{.TL}
3123 macro into the title, until reaching the author name or abstract.
3127 Specifies the author's name, which appears on the
3128 line (or lines) immediately following.
3129 You can specify multiple authors as follows:
3135 University of West Bumblefuzz
3139 Monolithic Corporation
3146 Specifies the author's institution.
3147 You can specify multiple institutions in the same way
3148 that you specify multiple authors.
3151 @Defmac {AB, [@code{no}], ms}
3152 Begins the abstract.
3153 The default is to print the word @acronym{ABSTRACT},
3154 centered and in italics, above the text of the abstract.
3155 The word @code{no} as an optional argument suppresses this heading.
3162 The following is example mark-up for a title page.
3163 @cindex title page, example markup
3164 @cindex example markup, title page
3170 The Inevitability of Code Bloat
3171 in Commercial and Free Software
3175 University of West Bumblefuzz
3177 This report examines the long-term growth
3178 of the code bases in two large, popular software
3179 packages; the free Emacs and the commercial
3181 While differences appear in the type or order
3182 of features added, due to the different
3183 methodologies used, the results are the same
3186 The free software approach is shown to be
3187 superior in that while free software can
3188 become as bloated as commercial offerings,
3189 free software tends to have fewer serious
3190 bugs and the added features are in line with
3194 ... the rest of the paper follows ...
3198 @c ---------------------------------------------------------------------
3200 @node ms Body Text, ms Page Layout, ms Cover Page Macros, ms
3201 @subsection Body text
3202 @cindex @code{ms} macros, body text
3204 This section describes macros used to mark up the body of your document.
3205 Examples include paragraphs, sections, and other groups.
3208 * Paragraphs in ms::
3210 * Highlighting in ms::
3214 * ms Displays and Keeps::
3216 * Example multi-page table::
3220 @c ---------------------------------------------------------------------
3222 @node Paragraphs in ms, Headings in ms, ms Body Text, ms Body Text
3223 @subsubsection Paragraphs
3224 @cindex @code{ms} macros, paragraph handling
3226 The following paragraph types are available.
3229 Sets a paragraph with an initial indent.
3233 Sets a paragraph with no initial indent.
3237 Sets a paragraph that is indented at both left and right margins.
3238 The effect is identical to the @acronym{HTML} @code{<BLOCKQUOTE>} element.
3239 The next paragraph or heading returns margins to normal.
3243 Sets a paragraph whose lines are indented,
3244 except for the first line.
3245 This is a Berkeley extension.
3248 The following markup uses all four paragraph macros.
3253 Cases used in the study
3255 The following software and versions were
3256 considered for this report.
3258 For commercial software, we chose
3259 .B "Microsoft Word for Windows" ,
3260 starting with version 1.0 through the
3261 current version (Word 2000).
3263 For free software, we chose
3265 from its first appearance as a standalone
3266 editor through the current version (v20).
3267 See [Bloggs 2002] for details.
3269 Franklin's Law applied to software:
3270 software expands to outgrow both
3271 RAM and disk space over time.
3276 .I "Everyone's a Critic" ,
3277 Underground Press, March 2002.
3278 A definitive work that answers all questions
3279 and criticisms about the quality and usability of
3284 The @code{PORPHANS} register (@pxref{ms Document Control Registers})
3285 operates in conjunction with each of these macros, to inhibit the
3286 printing of orphan lines at the bottom of any page.
3288 @c ---------------------------------------------------------------------
3290 @node Headings in ms, Highlighting in ms, Paragraphs in ms, ms Body Text
3291 @subsubsection Headings
3292 @cindex @code{ms} macros, headings
3294 Use headings to create a hierarchical structure for your document.
3295 The @file{ms} macros print headings in @strong{bold},
3296 using the same font family and point size as the body text.
3298 The following describes the heading macros:
3300 @DefmacList {NH, @Var{curr-level}, ms}
3301 @DefmacListEnd {NH, @t{S} @Var{level0} @dots{}, ms}
3303 The argument is either a numeric argument to indicate the
3304 level of the heading, or the letter@tie{}@code{S} followed by numeric
3305 arguments to set the heading level explicitly.
3307 If you specify heading levels out of sequence, such as invoking
3308 @samp{.NH 3} after @samp{.NH 1}, @code{groff}
3309 prints a warning on standard error.
3312 @DefstrList {SN, ms}
3313 @DefstrItem {SN-DOT, ms}
3314 @DefstrListEnd {SN-NO-DOT, ms}
3315 After invocation of @code{NH}, the assigned section number is made
3316 available in the strings @code{SN-DOT} (exactly as it appears in the
3317 printed section heading) and @code{SN-NO-DOT} (with the final period
3318 omitted). The string @code{SN} is also defined, as an alias for
3319 @code{SN-DOT}; if preferred, you may redefine it as an alias for
3320 @code{SN-NO-DOT}, by including the initialization
3328 @strong{before} your first use of @code{NH}, or simply
3335 @strong{after} your first use of @code{NH}.
3338 @Defmac {SH, [@Var{match-level}], ms}
3339 Unnumbered subheading.
3341 The optional @code{match-level} argument is a GNU extension. It is a
3342 number indicating the level of the heading, in a manner analogous to
3343 the @code{curr-level} argument to @code{.NH}. Its purpose is to match
3344 the point size, at which the heading is printed, to the size of a
3345 numbered heading at the same level, when the @code{GROWPS}/@code{PSINCR}
3346 heading size adjustment mechanism is in effect.
3347 @xref{ms Document Control Registers}.
3350 The @code{HORPHANS} register (@pxref{ms Document Control Registers})
3351 operates in conjunction with the @code{NH} and @code{SH} macros, to
3352 inhibit the printing of orphaned section headings at the bottom of any
3355 @c ---------------------------------------------------------------------
3357 @node Highlighting in ms, Lists in ms, Headings in ms, ms Body Text
3358 @subsubsection Highlighting
3359 @cindex @code{ms} macros, highlighting
3361 The @file{ms} macros provide a variety of methods to highlight
3364 @Defmac {B, [@Var{txt} [@Var{post} [@Var{pre}]]], ms}
3365 Sets its first argument in @strong{bold type}.
3366 If you specify a second argument, @code{groff} prints it in the
3367 previous font after the bold text, with no intervening space
3368 (this allows you to set punctuation after the highlighted text
3369 without highlighting the punctuation).
3370 Similarly, it prints the third argument (if any) in the previous
3371 font @strong{before} the first argument.
3378 prints (@strong{foo}).
3380 If you give this macro no arguments, @code{groff}
3381 prints all text following in bold until
3382 the next highlighting, paragraph, or heading macro.
3385 @Defmac {R, [@Var{txt} [@Var{post} [@Var{pre}]]], ms}
3386 Sets its first argument in roman (or regular) type.
3387 It operates similarly to the @code{B}@tie{}macro otherwise.
3390 @Defmac {I, [@Var{txt} [@Var{post} [@Var{pre}]]], ms}
3391 Sets its first argument in @emph{italic type}.
3392 It operates similarly to the @code{B}@tie{}macro otherwise.
3395 @Defmac {CW, [@Var{txt} [@Var{post} [@Var{pre}]]], ms}
3396 Sets its first argument in a @code{constant width face}.
3397 It operates similarly to the @code{B}@tie{}macro otherwise.
3400 @Defmac {BI, [@Var{txt} [@Var{post} [@Var{pre}]]], ms}
3401 Sets its first argument in bold italic type.
3402 It operates similarly to the @code{B}@tie{}macro otherwise.
3405 @Defmac {BX, [@Var{txt}], ms}
3406 Prints its argument and draws a box around it.
3407 If you want to box a string that contains spaces,
3408 use a digit-width space (@code{\0}).
3411 @Defmac {UL, [@Var{txt} [@Var{post}]], ms}
3412 Prints its first argument with an underline.
3413 If you specify a second argument, @code{groff}
3414 prints it in the previous font after
3415 the underlined text, with no intervening space.
3419 Prints all text following in larger type
3420 (two points larger than the current point size) until
3421 the next font size, highlighting, paragraph, or heading macro.
3422 You can specify this macro multiple times
3423 to enlarge the point size as needed.
3427 Prints all text following in smaller type
3428 (two points smaller than the current point size) until
3429 the next type size, highlighting, paragraph, or heading macro.
3430 You can specify this macro multiple times
3431 to reduce the point size as needed.
3435 Prints all text following in the normal point size
3436 (that is, the value of the @code{PS} register).
3439 @c ---------------------------------------------------------------------
3441 @node Lists in ms, Indents in ms, Highlighting in ms, ms Body Text
3442 @subsubsection Lists
3443 @cindex @code{ms} macros, lists
3445 The @code{.IP} macro handles duties for all lists.
3447 @Defmac {IP, [@Var{marker} [@Var{width}]], ms}
3448 The @var{marker} is usually a bullet glyph (@code{\[bu]})
3449 for unordered lists, a number (or auto-incrementing number
3450 register) for numbered lists, or a word or phrase for indented
3451 (glossary-style) lists.
3453 The @var{width} specifies the indent for the body of each list item;
3454 its default unit is @samp{n}.
3455 Once specified, the indent remains the same for all
3456 list items in the document until specified again.
3458 The @code{PORPHANS} register (@pxref{ms Document Control Registers})
3459 operates in conjunction with the @code{IP} macro, to inhibit the
3460 printing of orphaned list markers at the bottom of any page.
3463 The following is an example of a bulleted list.
3464 @cindex example markup, bulleted list [@code{ms}]
3465 @cindex bulleted list, example markup [@code{ms}]
3491 The following is an example of a numbered list.
3492 @cindex example markup, numbered list [@code{ms}]
3493 @cindex numbered list, example markup [@code{ms}]
3518 Note the use of the auto-incrementing number
3519 register in this example.
3522 The following is an example of a glossary-style list.
3523 @cindex example markup, glossary-style list [@code{ms}]
3524 @cindex glossary-style list, example markup [@code{ms}]
3527 A glossary-style list:
3529 Two or more attorneys.
3531 Firearms, preferably
3541 A glossary-style list:
3544 Two or more attorneys.
3546 guns Firearms, preferably large-caliber.
3549 Gotta pay for those lawyers and guns!
3552 In the last example, the @code{IP} macro places the definition
3553 on the same line as the term if it has enough space; otherwise,
3554 it breaks to the next line and starts the definition below the
3556 This may or may not be the effect you want, especially if some
3557 of the definitions break and some do not.
3558 The following examples show two possible ways to force a break.
3560 The first workaround uses the @code{br}
3561 request to force a break after printing the term or label.
3565 A glossary-style list:
3567 Two or more attorneys.
3570 Firearms, preferably large-caliber.
3572 Gotta pay for those lawyers and guns!
3577 The second workaround uses the @code{\p} escape to force the break.
3578 Note the space following the escape; this is important.
3579 If you omit the space, @code{groff} prints the first word on
3580 the same line as the term or label (if it fits) @strong{then}
3585 A glossary-style list:
3587 Two or more attorneys.
3589 \p Firearms, preferably large-caliber.
3591 Gotta pay for those lawyers and guns!
3596 To set nested lists, use the @code{RS} and @code{RE} macros.
3597 @xref{Indents in ms}, for more information.
3598 @cindex @code{ms} macros, nested lists
3599 @cindex nested lists [@code{ms}]
3634 @c ---------------------------------------------------------------------
3636 @node Indents in ms, Tabstops in ms, Lists in ms, ms Body Text
3637 @subsubsection Indents
3640 you may need to indent a section of text
3641 while still wrapping and filling.
3643 for an example of nested lists.
3645 @DefmacList {RS, , ms}
3646 @DefmacListEnd {RE, , ms}
3647 These macros begin and end an indented section.
3648 The @code{PI} register controls the amount of indent,
3649 allowing the indented text to line up under hanging
3650 and indented paragraphs.
3653 @xref{ms Displays and Keeps},
3654 for macros to indent and turn off filling.
3656 @c ---------------------------------------------------------------------
3658 @node Tabstops in ms, ms Displays and Keeps, Indents in ms, ms Body Text
3659 @subsubsection Tab Stops
3661 Use the @code{ta} request to define tab stops as needed.
3662 @xref{Tabs and Fields}.
3665 Use this macro to reset the tab stops to the default for @file{ms}
3667 You can redefine the @code{TA} macro to create a different set
3668 of default tab stops.
3671 @c ---------------------------------------------------------------------
3673 @node ms Displays and Keeps, ms Insertions, Tabstops in ms, ms Body Text
3674 @subsubsection Displays and keeps
3675 @cindex @code{ms} macros, displays
3676 @cindex @code{ms} macros, keeps
3677 @cindex keeps [@code{ms}]
3678 @cindex displays [@code{ms}]
3680 Use displays to show text-based examples or figures
3681 (such as code listings).
3683 Displays turn off filling, so lines of code are displayed
3684 as-is without inserting @code{br} requests in between each line.
3685 Displays can be @dfn{kept} on a single page, or allowed
3686 to break across pages.
3688 @DefmacList {DS, @t{L}, ms}
3689 @DefmacItem {LD, , ms}
3690 @DefmacListEnd {DE, , ms}
3691 Left-justified display.
3692 The @samp{.DS L} call generates a page break, if necessary,
3693 to keep the entire display on one page.
3694 The @code{LD} macro allows the display to break across pages.
3695 The @code{DE} macro ends the display.
3698 @DefmacList {DS, @t{I}, ms}
3699 @DefmacItem {ID, , ms}
3700 @DefmacListEnd {DE, , ms}
3701 Indents the display as defined by the @code{DI} register.
3702 The @samp{.DS I} call generates a page break, if necessary,
3703 to keep the entire display on one page.
3704 The @code{ID} macro allows the display to break across pages.
3705 The @code{DE} macro ends the display.
3708 @DefmacList {DS, @t{B}, ms}
3709 @DefmacItem {BD, , ms}
3710 @DefmacListEnd {DE, , ms}
3711 Sets a block-centered display: the entire display is left-justified,
3712 but indented so that the longest line in the display is centered
3714 The @samp{.DS B} call generates a page break, if necessary,
3715 to keep the entire display on one page.
3716 The @code{BD} macro allows the display to break across pages.
3717 The @code{DE} macro ends the display.
3720 @DefmacList {DS, @t{C}, ms}
3721 @DefmacItem {CD, , ms}
3722 @DefmacListEnd {DE, , ms}
3723 Sets a centered display: each line in the display is centered.
3724 The @samp{.DS C} call generates a page break, if necessary,
3725 to keep the entire display on one page.
3726 The @code{CD} macro allows the display to break across pages.
3727 The @code{DE} macro ends the display.
3730 @DefmacList {DS, @t{R}, ms}
3731 @DefmacItem {RD, , ms}
3732 @DefmacListEnd {DE, , ms}
3733 Right-justifies each line in the display.
3734 The @samp{.DS R} call generates a page break, if necessary,
3735 to keep the entire display on one page.
3736 The @code{RD} macro allows the display to break across pages.
3737 The @code{DE} macro ends the display.
3740 @DefmacList {Ds, , ms}
3741 @DefmacListEnd {De, , ms}
3742 These two macros were formerly provided as aliases for
3743 @code{DS} and @code{DE}, respectively.
3744 They have been removed, and should no longer be used.
3745 The original implementations of @code{DS} and @code{DE}
3746 are retained, and should be used instead.
3747 X11 documents which actually use @code{Ds} and @code{De} always load a
3748 specific macro file from the X11 distribution (@file{macros.t}) which
3749 provides proper definitions for the two macros.
3753 On occasion, you may want to @dfn{keep} other text together on a page.
3754 For example, you may want to keep two paragraphs together, or
3755 a paragraph that refers to a table (or list, or other item)
3756 immediately following.
3757 The @file{ms} macros provide the @code{KS} and @code{KE}
3758 macros for this purpose.
3760 @DefmacList {KS, , ms}
3761 @DefmacListEnd {KE, , ms}
3762 The @code{KS} macro begins a block of text to be kept on a
3763 single page, and the @code{KE} macro ends the block.
3766 @DefmacList {KF, , ms}
3767 @DefmacListEnd {KE, , ms}
3768 Specifies a @dfn{floating keep};
3769 if the keep cannot fit on the current page, @code{groff}
3770 holds the contents of the keep and allows text following
3771 the keep (in the source file) to fill in the remainder of
3773 When the page breaks, whether by an explicit @code{bp}
3774 request or by reaching the end of the page, @code{groff}
3775 prints the floating keep at the top of the new page.
3776 This is useful for printing large graphics or tables
3777 that do not need to appear exactly where specified.
3780 You can also use the @code{ne} request to force a page break if
3781 there is not enough vertical space remaining on the page.
3784 Use the following macros to draw a box around a section of
3785 text (such as a display).
3787 @DefmacList {B1, , ms}
3788 @DefmacListEnd {B2, , ms}
3789 Marks the beginning and ending of text that is to have a
3790 box drawn around it.
3791 The @code{B1} macro begins the box; the @code{B2} macro ends it.
3792 Text in the box is automatically placed in a diversion (keep).
3795 @c ---------------------------------------------------------------------
3797 @node ms Insertions, Example multi-page table, ms Displays and Keeps, ms Body Text
3798 @subsubsection Tables, figures, equations, and references
3799 @cindex @code{ms} macros, tables
3800 @cindex @code{ms} macros, figures
3801 @cindex @code{ms} macros, equations
3802 @cindex @code{ms} macros, references
3803 @cindex tables [@code{ms}]
3804 @cindex figures [@code{ms}]
3805 @cindex equations [@code{ms}]
3806 @cindex references [@code{ms}]
3808 The @file{ms} macros support the standard
3809 @code{groff} preprocessors:
3810 @code{tbl}, @code{pic}, @code{eqn}, and @code{refer}.
3815 You mark text meant for preprocessors by enclosing it
3816 in pairs of tags as follows.
3818 @DefmacList {TS, [@code{H}], ms}
3819 @DefmacListEnd {TE, , ms}
3820 Denotes a table, to be processed by the @code{tbl} preprocessor.
3821 The optional argument@tie{}@code{H} to @code{TS} instructs @code{groff}
3822 to create a running header with the information
3823 up to the @code{TH} macro.
3824 @code{groff} prints the header at the beginning of the
3825 table; if the table runs onto another page, @code{groff}
3826 prints the header on the next page as well.
3829 @DefmacList {PS, , ms}
3830 @DefmacListEnd {PE, , ms}
3831 Denotes a graphic, to be processed by the @code{pic} preprocessor.
3832 You can create a @code{pic} file by hand, using the @acronym{AT&T}
3833 @code{pic} manual available on the Web as a reference, or by using
3834 a graphics program such as @code{xfig}.
3837 @DefmacList {EQ, [@Var{align}], ms}
3838 @DefmacListEnd {EN, , ms}
3839 Denotes an equation, to be processed by the @code{eqn} preprocessor.
3840 The optional @var{align} argument can be @code{C}, @code{L},
3841 or@tie{}@code{I} to center (the default), left-justify, or indent the
3845 @DefmacList {[, , ms}
3846 @DefmacListEnd {], , ms}
3847 Denotes a reference, to be processed by the @code{refer} preprocessor.
3848 The @acronym{GNU} @cite{refer(1)} man page provides a comprehensive
3849 reference to the preprocessor and the format of the bibliographic
3854 * Example multi-page table::
3857 @c ---------------------------------------------------------------------
3859 @node Example multi-page table, ms Footnotes, ms Insertions, ms Body Text
3860 @subsubsection An example multi-page table
3861 @cindex example markup, multi-page table [@code{ms}]
3862 @cindex multi-page table, example markup [@code{ms}]
3864 The following is an example of how to set up a
3865 table that may print across two or more pages.
3872 Text ...of heading...
3877 ... the rest of the table follows...
3883 @c ---------------------------------------------------------------------
3885 @node ms Footnotes, , Example multi-page table, ms Body Text
3886 @subsubsection Footnotes
3887 @cindex @code{ms} macros, footnotes
3888 @cindex footnotes [@code{ms}]
3890 The @file{ms} macro package has a flexible footnote system.
3891 You can specify either numbered footnotes or symbolic footnotes
3892 (that is, using a marker such as a dagger symbol).
3895 Specifies the location of a numbered footnote marker in the text.
3898 @DefmacList {FS, , ms}
3899 @DefmacListEnd {FE, , ms}
3900 Specifies the text of the footnote.
3901 The default action is to create a numbered footnote;
3902 you can create a symbolic footnote by specifying
3904 (such as @code{\[dg]} for the dagger glyph)
3905 in the body text and as an argument to the @code{FS} macro,
3906 followed by the text of the footnote
3907 and the @code{FE} macro.
3910 You can control how @code{groff}
3911 prints footnote numbers by changing the value of the
3912 @code{FF} register. @xref{ms Document Control Registers}.
3914 @c ---------------------------------------------------------------------
3916 @node ms Page Layout, Differences from AT&T ms, ms Body Text, ms
3917 @subsection Page layout
3918 @cindex @code{ms} macros, page layout
3919 @cindex page layout [@code{ms}]
3921 The default output from the @file{ms}
3922 macros provides a minimalist page layout:
3923 it prints a single column, with the page number centered at the top
3925 It prints no footers.
3927 You can change the layout by setting
3928 the proper number registers and strings.
3931 * ms Headers and Footers::
3933 * ms Multiple Columns::
3935 * ms Strings and Special Characters::
3938 @c ---------------------------------------------------------------------
3940 @node ms Headers and Footers, ms Margins, ms Page Layout, ms Page Layout
3941 @subsubsection Headers and footers
3942 @cindex @code{ms} macros, headers
3943 @cindex @code{ms} macros, footers
3944 @cindex headers [@code{ms}]
3945 @cindex footers [@code{ms}]
3947 For documents that do not distinguish between odd and even pages,
3948 set the following strings:
3950 @DefstrList {LH, ms}
3951 @DefstrItem {CH, ms}
3952 @DefstrListEnd {RH, ms}
3953 Sets the left, center, and right headers.
3956 @DefstrList {LF, ms}
3957 @DefstrItem {CF, ms}
3958 @DefstrListEnd {RF, ms}
3959 Sets the left, center, and right footers.
3963 For documents that need different information printed in the
3964 even and odd pages, use the following macros:
3966 @DefmacList {OH, @t{'}@Var{left}@t{'}@Var{center}@t{'}@Var{right}@t{'}, ms}
3967 @DefmacItem {EH, @t{'}@Var{left}@t{'}@Var{center}@t{'}@Var{right}@t{'}, ms}
3968 @DefmacItem {OF, @t{'}@Var{left}@t{'}@Var{center}@t{'}@Var{right}@t{'}, ms}
3969 @DefmacListEnd {EF, @t{'}@Var{left}@t{'}@Var{center}@t{'}@Var{right}@t{'}, ms}
3970 The @code{OH} and @code{EH} macros define headers for the odd and even pages;
3971 the @code{OF} and @code{EF} macros define footers for the odd and even pages.
3972 This is more flexible than defining the individual strings.
3974 You can replace the quote (@code{'}) marks with any character not
3975 appearing in the header or footer text.
3978 @c ---------------------------------------------------------------------
3980 @node ms Margins, ms Multiple Columns, ms Headers and Footers, ms Page Layout
3981 @subsubsection Margins
3982 @cindex @code{ms} macros, margins
3984 You control margins using a set of number registers.
3985 @xref{ms Document Control Registers}, for details.
3987 @c ---------------------------------------------------------------------
3989 @node ms Multiple Columns, ms TOC, ms Margins, ms Page Layout
3990 @subsubsection Multiple columns
3991 @cindex @code{ms} macros, multiple columns
3992 @cindex multiple columns [@code{ms}]
3994 The @file{ms} macros can set text in as many columns as will
3995 reasonably fit on the page.
3996 The following macros are available;
3997 all of them force a page break if a multi-column mode is already set.
3998 However, if the current mode is single-column, starting a multi-column
3999 mode does @strong{not} force a page break.
4009 @Defmac {MC, [@Var{width} [@Var{gutter}]], ms}
4011 If you specify no arguments, it is equivalent to the
4013 Otherwise, @var{width} is the width of each column and
4014 @var{gutter} is the space between columns.
4015 The @code{MINGW} number register controls the default gutter width.
4018 @c ---------------------------------------------------------------------
4020 @node ms TOC, ms Strings and Special Characters, ms Multiple Columns, ms Page Layout
4021 @subsubsection Creating a table of contents
4022 @cindex @code{ms} macros, creating table of contents
4023 @cindex table of contents, creating [@code{ms}]
4025 The facilities in the @file{ms} macro package for creating
4026 a table of contents are semi-automated at best.
4027 Assuming that you want the table of contents to consist of
4028 the document's headings, you need to repeat those headings
4029 wrapped in @code{XS} and @code{XE} macros.
4031 @DefmacList {XS, [@Var{page}], ms}
4032 @DefmacItem {XA, [@Var{page}], ms}
4033 @DefmacListEnd {XE, , ms}
4034 These macros define a table of contents
4035 or an individual entry in the table of contents,
4036 depending on their use.
4037 The macros are very simple; they cannot indent a heading based on its level.
4038 The easiest way to work around this is to add tabs
4039 to the table of contents string.
4040 The following is an example:
4062 You can manually create a table of contents
4063 by beginning with the @code{XS} macro for the first entry,
4064 specifying the page number for that entry as the argument to @code{XS}.
4065 Add subsequent entries using the @code{XA} macro,
4066 specifying the page number for that entry as the argument to @code{XA}.
4067 The following is an example:
4074 A Brief History of the Universe
4076 Details of Galactic Formation
4083 @Defmac {TC, [@code{no}], ms}
4084 Prints the table of contents on a new page,
4085 setting the page number to@tie{}@strong{i} (Roman numeral one).
4086 You should usually place this macro at the end of the
4087 file, since @code{groff} is a single-pass formatter and
4088 can only print what has been collected up to the point
4089 that the @code{TC} macro appears.
4091 The optional argument @code{no} suppresses printing
4092 the title specified by the string register @code{TOC}.
4095 @Defmac{PX, [@code{no}], ms}
4096 Prints the table of contents on a new page,
4097 using the current page numbering sequence.
4098 Use this macro to print a manually-generated table of contents
4099 at the beginning of your document.
4101 The optional argument @code{no} suppresses printing
4102 the title specified by the string register @code{TOC}.
4105 The @cite{Groff and Friends HOWTO}
4106 includes a @code{sed} script that automatically inserts
4107 @code{XS} and @code{XE} macro entries after each heading in a document.
4109 Altering the @code{NH} macro to automatically build the table
4110 of contents is perhaps initially more difficult, but would save
4111 a great deal of time in the long run if you use @file{ms} regularly.
4113 @c ---------------------------------------------------------------------
4115 @node ms Strings and Special Characters, , ms TOC, ms Page Layout
4116 @subsubsection Strings and Special Characters
4117 @cindex @code{ms} macros, strings
4118 @cindex @code{ms} macros, special characters
4119 @cindex @code{ms} macros, accent marks
4120 @cindex accent marks [@code{ms}]
4121 @cindex special characters [@code{ms}]
4122 @cindex strings [@code{ms}]
4124 The @file{ms} macros provide the following predefined strings.
4125 You can change the string definitions to help in creating
4126 documents in languages other than English.
4128 @Defstr {REFERENCES, ms}
4129 Contains the string printed at the beginning of the
4130 references (bibliography) page.
4131 The default is @samp{References}.
4134 @Defstr {ABSTRACT, ms}
4135 Contains the string printed at the beginning of the abstract.
4136 The default is @samp{ABSTRACT}.
4140 Contains the string printed at the beginning of the table of contents.
4143 @DefstrList {MONTH1, ms}
4144 @DefstrItem {MONTH2, ms}
4145 @DefstrItem {MONTH3, ms}
4146 @DefstrItem {MONTH4, ms}
4147 @DefstrItem {MONTH5, ms}
4148 @DefstrItem {MONTH6, ms}
4149 @DefstrItem {MONTH7, ms}
4150 @DefstrItem {MONTH8, ms}
4151 @DefstrItem {MONTH9, ms}
4152 @DefstrItem {MONTH10, ms}
4153 @DefstrItem {MONTH11, ms}
4154 @DefstrListEnd {MONTH12, ms}
4155 Prints the full name of the month in dates.
4156 The default is @samp{January}, @samp{February}, etc.
4159 The following special characters are available@footnote{For an
4160 explanation what special characters are see @ref{Special Characters}.}:
4166 @DefstrList {*Q, ms}
4167 @DefstrListEnd {*U, ms}
4168 Prints typographer's quotes in troff,
4169 plain quotes in nroff.
4170 @code{*Q} is the left quote and @code{*U} is the right quote.
4173 Improved accent marks are available in the @file{ms} macros.
4176 Specify this macro at the beginning of your document
4177 to enable extended accent marks and special characters.
4178 This is a Berkeley extension.
4180 To use the accent marks, place them @strong{after}
4181 the character being accented.
4184 The following accent marks are available
4185 after invoking the @code{AM} macro:
4207 @deffn String @t{\*[:]}
4209 @stindex : @r{[}ms@r{]}
4212 @stindex \*[@r{<colon>}] @r{[}ms@r{]}
4233 The following are standalone characters
4234 available after invoking the @code{AM} macro:
4237 Upside-down question mark.
4241 Upside-down exclamation point.
4273 Lowercase æ ligature.
4277 Uppercase Æ ligature.
4280 @c ---------------------------------------------------------------------
4282 @node Differences from AT&T ms, , ms Page Layout, ms
4283 @subsection Differences from @acronym{AT&T} @file{ms}
4284 @cindex @code{ms} macros, differences from @acronym{AT&T}
4285 @cindex @acronym{AT&T} @code{troff}, @code{ms} macro package differences
4287 This section lists the (minor) differences between the
4288 @code{groff -ms} macros and @acronym{AT&T}
4289 @code{troff -ms} macros.
4292 * Missing ms Macros::
4293 * Additional ms Macros::
4296 @c ---------------------------------------------------------------------
4298 @node Missing ms Macros, Additional ms Macros, Differences from AT&T ms, Differences from AT&T ms
4299 @subsubsection @code{troff} macros not appearing in @code{groff}
4301 Macros missing from @code{groff -ms}
4302 are cover page macros specific to Bell Labs.
4303 The macros known to be missing are:
4307 Technical memorandum; a cover sheet style
4310 Internal memorandum; a cover sheet style
4313 Memo for record; a cover sheet style
4316 Memo for file; a cover sheet style
4319 Engineer's notes; a cover sheet style
4322 Computing Science Tech Report; a cover sheet style
4328 Cover sheet information
4334 @c ---------------------------------------------------------------------
4336 @node Additional ms Macros, , Missing ms Macros, Differences from AT&T ms
4337 @subsubsection @code{groff} macros not appearing in @acronym{AT&T} @code{troff}
4339 The @code{groff -ms} macros have a few minor extensions
4340 compared to the @acronym{AT&T} @code{troff -ms} macros.
4343 Improved accent marks.
4344 @xref{ms Strings and Special Characters}, for details.
4347 @Defmac {DS, @t{I}, ms}
4349 The default behavior of @acronym{AT&T} @code{troff -ms}
4350 was to indent; the @code{groff} default prints displays
4351 flush left with the body text.
4355 Print text in @code{constant width} (Courier) font.
4359 Indexing term (printed on standard error).
4360 You can write a script to capture and process an index
4361 generated in this manner.
4365 The following additional number registers
4366 appear in @code{groff -ms}:
4368 @Defmpreg {MINGW, ms}
4369 Specifies a minimum space
4370 between columns (for multi-column output); this takes the
4371 place of the @code{GW} register that was documented but apparently
4372 not implemented in @acronym{AT&T} @code{troff}.
4376 Several new string registers are available as well.
4377 You can change these to handle (for example) the local language.
4378 @xref{ms Strings and Special Characters}, for details.
4381 @c =====================================================================
4383 @node me, mm, ms, Macro Packages
4385 @cindex @code{me} macro package
4387 @c XXX documentation
4388 @c XXX this is a placeholder until we get stuff knocked into shape
4389 See the @file{meintro.me} and @file{meref.me} documents in
4390 groff's @file{doc} directory.
4393 @c =====================================================================
4395 @node mm, , me, Macro Packages
4397 @cindex @code{mm} macro package
4399 @c XXX documentation
4400 @c XXX this is a placeholder until we get stuff knocked into shape
4401 See the @cite{groff_mm(7)} man page (type @command{man groff_mm} at
4405 @c =====================================================================
4406 @c =====================================================================
4408 @node gtroff Reference, Preprocessors, Macro Packages, Top
4409 @chapter @code{gtroff} Reference
4410 @cindex reference, @code{gtroff}
4411 @cindex @code{gtroff}, reference
4413 This chapter covers @strong{all} of the facilities of @code{gtroff}.
4414 Users of macro packages may skip it if not interested in details.
4422 * Embedded Commands::
4424 * Manipulating Filling and Adjusting::
4425 * Manipulating Hyphenation::
4426 * Manipulating Spacing::
4428 * Character Translations::
4429 * Troff and Nroff Mode::
4434 * Fonts and Symbols::
4437 * Conditionals and Loops::
4440 * Drawing Requests::
4444 * Suppressing output::
4447 * Postprocessor Access::
4449 * Gtroff Internals::
4451 * Implementation Differences::
4455 @c =====================================================================
4457 @node Text, Measurements, gtroff Reference, gtroff Reference
4459 @cindex text, @code{gtroff} processing
4461 @code{gtroff} input files contain text with control commands
4462 interspersed throughout. But, even without control codes, @code{gtroff}
4463 still does several things with the input text:
4467 filling and adjusting
4470 adding additional space after sentences
4476 inserting implicit line breaks
4480 * Filling and Adjusting::
4484 * Implicit Line Breaks::
4485 * Input Conventions::
4489 @c ---------------------------------------------------------------------
4491 @node Filling and Adjusting, Hyphenation, Text, Text
4492 @subsection Filling and Adjusting
4496 When @code{gtroff} reads text, it collects words from the input and fits
4497 as many of them together on one output line as it can. This is known as
4500 @cindex leading spaces
4501 @cindex spaces, leading and trailing
4502 @cindex extra spaces
4503 @cindex trailing spaces
4504 Once @code{gtroff} has a @dfn{filled} line, it tries to @dfn{adjust}
4505 it. This means it widens the spacing between words until the text
4506 reaches the right margin (in the default adjustment mode). Extra spaces
4507 between words are preserved, but spaces at the end of lines are ignored.
4508 Spaces at the front of a line cause a @dfn{break} (breaks are
4509 explained in @ref{Implicit Line Breaks}).
4511 @xref{Manipulating Filling and Adjusting}.
4513 @c ---------------------------------------------------------------------
4515 @node Hyphenation, Sentences, Filling and Adjusting, Text
4516 @subsection Hyphenation
4519 Since the odds are not great for finding a set of words, for every
4520 output line, which fit nicely on a line without inserting excessive
4521 amounts of space between words, @code{gtroff} hyphenates words so
4522 that it can justify lines without inserting too much space between
4523 words. It uses an internal hyphenation algorithm (a simplified version
4524 of the algorithm used within @TeX{}) to indicate which words can be
4525 hyphenated and how to do so. When a word is hyphenated, the first part
4526 of the word is added to the current filled line being output (with
4527 an attached hyphen), and the other portion is added to the next
4530 @xref{Manipulating Hyphenation}.
4532 @c ---------------------------------------------------------------------
4534 @node Sentences, Tab Stops, Hyphenation, Text
4535 @subsection Sentences
4538 Although it is often debated, some typesetting rules say there should be
4539 different amounts of space after various punctuation marks. For
4540 example, the @cite{Chicago typsetting manual} says that a period at the
4541 end of a sentence should have twice as much space following it as would
4542 a comma or a period as part of an abbreviation.
4544 @c XXX exact citation of Chicago manual
4546 @cindex sentence space
4547 @cindex space between sentences
4548 @cindex french-spacing
4549 @code{gtroff} does this by flagging certain characters (normally
4550 @samp{!}, @samp{?}, and @samp{.}) as @dfn{end-of-sentence} characters.
4551 When @code{gtroff} encounters one of these characters at the end of a
4552 line, it appends a normal space followed by a @dfn{sentence space} in
4553 the formatted output. (This justifies one of the conventions mentioned
4554 in @ref{Input Conventions}.)
4556 @cindex transparent characters
4557 @cindex character, transparent
4558 @cindex @code{dg} glyph, at end of sentence
4559 @cindex @code{rq} glyph, at end of sentence
4560 @cindex @code{"}, at end of sentence
4561 @cindex @code{'}, at end of sentence
4562 @cindex @code{)}, at end of sentence
4563 @cindex @code{]}, at end of sentence
4564 @cindex @code{*}, at end of sentence
4565 In addition, the following characters and symbols are treated
4566 transparently while handling end-of-sentence characters: @samp{"},
4567 @samp{'}, @samp{)}, @samp{]}, @samp{*}, @code{\[dg]}, and @code{\[rq]}.
4569 See the @code{cflags} request in @ref{Using Symbols}, for more details.
4571 @cindex @code{\&}, at end of sentence
4572 To prevent the insertion of extra space after an end-of-sentence
4573 character (at the end of a line), append @code{\&}.
4575 @c ---------------------------------------------------------------------
4577 @node Tab Stops, Implicit Line Breaks, Sentences, Text
4578 @subsection Tab Stops
4580 @cindex stops, tabulator
4581 @cindex tab character
4582 @cindex character, tabulator
4584 @cindex @acronym{EBCDIC} encoding
4585 @cindex encoding, @acronym{EBCDIC}
4586 @code{gtroff} translates @dfn{tabulator characters}, also called
4587 @dfn{tabs} (normally code point @acronym{ASCII} @code{0x09} or
4588 @acronym{EBCDIC} @code{0x05}), in the input into movements to the next
4589 tabulator stop. These tab stops are initially located every half inch
4590 across the page. Using this, simple tables can be made easily.
4591 However, it can often be deceptive as the appearance (and width) of the
4592 text on a terminal and the results from @code{gtroff} can vary greatly.
4594 Also, a possible sticking point is that lines beginning with tab
4595 characters are still filled, again producing unexpected results.
4596 For example, the following input
4598 @multitable {12345678} {12345678} {12345678} {12345678}
4600 @tab 1 @tab 2 @tab 3
4608 @multitable {12345678} {12345678} {12345678} {12345678} {12345678} {12345678} {12345678}
4610 @tab 1 @tab 2 @tab 3 @tab @tab 4 @tab 5
4613 @xref{Tabs and Fields}.
4615 @c ---------------------------------------------------------------------
4617 @node Implicit Line Breaks, Input Conventions, Tab Stops, Text
4618 @subsection Implicit Line Breaks
4619 @cindex implicit line breaks
4620 @cindex implicit breaks of lines
4621 @cindex line, implicit breaks
4622 @cindex break, implicit
4625 An important concept in @code{gtroff} is the @dfn{break}. When a break
4626 occurs, @code{gtroff} outputs the partially filled line
4627 (unjustified), and resumes collecting and filling text on the next output
4633 @cindex blank line macro (@code{blm})
4634 There are several ways to cause a break in @code{gtroff}. A blank
4635 line not only causes a break, but it also outputs a one-line vertical
4636 space (effectively a blank line). Note that this behaviour can be
4637 modified with the blank line macro request @code{blm}.
4638 @xref{Blank Line Traps}.
4642 A line that begins with a space causes a break and the space is
4643 output at the beginning of the next line. Note that this space isn't
4644 adjusted, even in fill mode.
4646 The end of file also causes a break -- otherwise the last line of
4647 the document may vanish!
4649 Certain requests also cause breaks, implicitly or explicitly. This is
4650 discussed in @ref{Manipulating Filling and Adjusting}.
4652 @c ---------------------------------------------------------------------
4654 @node Input Conventions, Input Encodings, Implicit Line Breaks, Text
4655 @subsection Input Conventions
4656 @cindex input conventions
4657 @cindex conventions for input
4659 Since @code{gtroff} does filling automatically, it is traditional in
4660 @code{groff} not to try and type things in as nicely formatted
4661 paragraphs. These are some conventions commonly used when typing
4666 Break lines after punctuation, particularly at the end of a sentence
4667 and in other logical places. Keep separate phrases on lines by
4668 themselves, as entire phrases are often added or deleted when editing.
4671 Try to keep lines less than 40-60@tie{}characters, to allow space for
4672 inserting more text.
4675 Do not try to do any formatting in a @acronym{WYSIWYG} manner (i.e.,
4676 don't try using spaces to get proper indentation).
4679 @c ---------------------------------------------------------------------
4681 @node Input Encodings, , Input Conventions, Text
4682 @subsection Input Encodings
4684 Currently, the following input encodings are available.
4688 @cindex encoding, input, @acronym{EBCDIC}
4689 @cindex @acronym{EBCDIC}, input encoding
4690 @cindex input encoding, @acronym{EBCDIC}
4691 @cindex encoding, input, cp1047
4692 @cindex cp1047, input encoding
4693 @cindex input encoding, cp1047
4694 @cindex IBM cp1047 input encoding
4696 This input encoding works only on @acronym{EBCDIC} platforms (and vice
4697 versa, the other input encodings don't work with @acronym{EBCDIC}); the
4698 file @file{cp1047.tmac} is by default loaded at start-up.
4701 @cindex encoding, input, @w{latin-1} (ISO @w{8859-1})
4702 @cindex @w{latin-1} (ISO @w{8859-1}), input encoding
4703 @cindex ISO @w{8859-1} (@w{latin-1}), input encoding
4704 @cindex input encoding, @w{latin-1} (ISO @w{8859-1})
4706 This is the default input encoding on non-@acronym{EBCDIC} platforms;
4707 the file @file{latin1.tmac} is loaded at start-up.
4710 @cindex encoding, input, @w{latin-2} (ISO @w{8859-2})
4711 @cindex @w{latin-2} (ISO @w{8859-2}), input encoding
4712 @cindex ISO @w{8859-2} (@w{latin-2}), input encoding
4713 @cindex input encoding, @w{latin-2} (ISO @w{8859-2})
4715 To use this encoding, either say @w{@samp{.mso latin2.tmac}} at the very
4716 beginning of your document or use @samp{-mlatin2} as a command line
4717 argument for @code{groff}.
4719 @item latin-9 (latin-0)
4720 @cindex encoding, input, @w{latin-9} (@w{latin-0}, ISO @w{8859-15})
4721 @cindex @w{latin-9} (@w{latin-0}, ISO @w{8859-15}), input encoding
4722 @cindex ISO @w{8859-15} (@w{latin-9}, @w{latin-0}), input encoding
4723 @cindex input encoding, @w{latin-9} (@w{latin-9}, ISO @w{8859-15})
4725 This encoding is intended (at least in Europe) to replace @w{latin-1}
4726 encoding. The main difference to @w{latin-1} is that @w{latin-9}
4727 contains the Euro character. To use this encoding, either say
4728 @w{@samp{.mso latin9.tmac}} at the very beginning of your document or
4729 use @samp{-mlatin9} as a command line argument for @code{groff}.
4732 Note that it can happen that some input encoding characters are not
4733 available for a particular output device. For example, saying
4736 groff -Tlatin1 -mlatin9 ...
4740 will fail if you use the Euro character in the input. Usually, this
4741 limitation is present only for devices which have a limited set of
4742 output glyphs (e.g.@: @option{-Tascii} and @option{-Tlatin1}); for other
4743 devices it is usually sufficient to install proper fonts which contain
4744 the necessary glyphs.
4746 @pindex freeeuro.pfa
4748 Due to the importance of the Euro glyph in Europe, the groff package now
4749 comes with a @sc{PostScript} font called @file{freeeuro.pfa} which
4750 provides various glyph shapes for the Euro. With other words,
4751 @w{latin-9} encoding is supported for the @option{-Tps} device out of
4752 the box (@w{latin-2} isn't).
4754 By its very nature, @option{-Tutf8} supports all input encodings;
4755 @option{-Tdvi} has support for both @w{latin-2} and @w{latin-9} if the
4756 command line @option{-mec} is used also to load the file @file{ec.tmac}
4757 (which flips to the EC fonts).
4760 @c =====================================================================
4762 @node Measurements, Expressions, Text, gtroff Reference
4763 @section Measurements
4764 @cindex measurements
4766 @cindex units of measurement
4767 @cindex basic unit (@code{u})
4768 @cindex machine unit (@code{u})
4769 @cindex measurement unit
4770 @cindex @code{u} unit
4771 @cindex unit, @code{u}
4772 @code{gtroff} (like many other programs) requires numeric parameters to
4773 specify various measurements. Most numeric parameters@footnote{those
4774 that specify vertical or horizontal motion or a type size} may have a
4775 @dfn{measurement unit} attached. These units are specified as a single
4776 character which immediately follows the number or expression. Each of
4777 these units are understood, by @code{gtroff}, to be a multiple of its
4778 @dfn{basic unit}. So, whenever a different measurement unit is
4779 specified @code{gtroff} converts this into its @dfn{basic units}. This
4780 basic unit, represented by a @samp{u}, is a device dependent measurement
4781 which is quite small, ranging from 1/75@dmn{th} to 1/72000@dmn{th} of an
4782 inch. The values may be given as fractional numbers; however,
4783 fractional basic units are always rounded to integers.
4785 Some of the measurement units are completely independent of any of the
4786 current settings (e.g.@: type size) of @code{gtroff}.
4790 @cindex inch unit (@code{i})
4791 @cindex @code{i} unit
4792 @cindex unit, @code{i}
4793 Inches. An antiquated measurement unit still in use in certain
4794 backwards countries with incredibly low-cost computer equipment. One
4795 inch is equal to@tie{}2.54@dmn{cm}.
4798 @cindex centimeter unit (@code{c})
4799 @cindex @code{c} unit
4800 @cindex unit, @code{c}
4801 Centimeters. One centimeter is equal to@tie{}0.3937@dmn{in}.
4804 @cindex point unit (@code{p})
4805 @cindex @code{p} unit
4806 @cindex unit, @code{p}
4807 Points. This is a typesetter's measurement used for measure type size.
4808 It is 72@tie{}points to an inch.
4811 @cindex pica unit (@code{P})
4812 @cindex @code{P} unit
4813 @cindex unit, @code{P}
4814 Pica. Another typesetting measurement. 6@tie{}Picas to an inch (and
4815 12@tie{}points to a pica).
4819 @cindex @code{s} unit
4820 @cindex unit, @code{s}
4821 @cindex @code{z} unit
4822 @cindex unit, @code{z}
4823 @xref{Fractional Type Sizes}, for a discussion of these units.
4826 @cindex @code{f} unit
4827 @cindex unit, @code{f}
4828 Fractions. Value is 65536.
4829 @xref{Colors}, for usage.
4832 The other measurements understood by @code{gtroff} depend on
4833 settings currently in effect in @code{gtroff}. These are very useful
4834 for specifying measurements which should look proper with any size of
4839 @cindex em unit (@code{m})
4840 @cindex @code{m} unit
4841 @cindex unit, @code{m}
4842 Ems. This unit is equal to the current font size in points. So called
4843 because it is @emph{approximately} the width of the letter@tie{}@samp{m}
4844 in the current font.
4847 @cindex en unit (@code{n})
4848 @cindex @code{n} unit
4849 @cindex unit, @code{n}
4850 Ens. In @code{groff}, this is half of an em.
4853 @cindex vertical space unit (@code{v})
4854 @cindex space, vertical, unit (@code{v})
4855 @cindex @code{v} unit
4856 @cindex unit, @code{v}
4857 Vertical space. This is equivalent to the current line spacing.
4858 @xref{Sizes}, for more information about this.
4861 @cindex @code{M} unit
4862 @cindex unit, @code{M}
4870 @c ---------------------------------------------------------------------
4872 @node Default Units, , Measurements, Measurements
4873 @subsection Default Units
4874 @cindex default units
4875 @cindex units, default
4877 Many requests take a default unit. While this can be helpful at times,
4878 it can cause strange errors in some expressions. For example, the line
4879 length request expects em units. Here are several attempts to get a
4880 line length of 3.5@tie{}inches and their results:
4886 (7 / 2)u @result{} 0i
4888 7i/2u @result{} 3.5i
4892 Everything is converted to basic units first. In the above example it
4893 is assumed that 1@dmn{i} equals@tie{}240@dmn{u}, and 1@dmn{m}
4894 equals@tie{}10@dmn{p} (thus 1@dmn{m} equals@tie{}33@dmn{u}). The value
4895 7@dmn{i}/2 is first handled as 7@dmn{i}/2@dmn{m}, then converted to
4896 1680@dmn{u}/66@dmn{u} which is 25@dmn{u}, and this is approximately
4897 0.1@dmn{i}. As can be seen, a scaling indicator after a closing
4898 parenthesis is simply ignored.
4900 @cindex measurements, specifying safely
4901 Thus, the safest way to specify measurements is to always
4902 attach a scaling indicator. If you want to multiply or divide by a
4903 certain scalar value, use @samp{u} as the unit for that value.
4906 @c =====================================================================
4908 @node Expressions, Identifiers, Measurements, gtroff Reference
4909 @section Expressions
4912 @code{gtroff} has most arithmetic operators common to other languages:
4916 @cindex arithmetic operators
4917 @cindex operators, arithmetic
4923 Arithmetic: @samp{+} (addition), @samp{-} (subtraction), @samp{/}
4924 (division), @samp{*} (multiplication), @samp{%} (modulo).
4926 @code{gtroff} only provides integer arithmetic. The internal type used
4927 for computing results is @samp{int}, which is usually a 32@dmn{bit}
4931 @cindex comparison operators
4932 @cindex operators, comparison
4939 Comparison: @samp{<} (less than), @samp{>} (greater than), @samp{<=}
4940 (less than or equal), @samp{>=} (greater than or equal), @samp{=}
4941 (equal), @samp{==} (the same as @samp{=}).
4944 @cindex logical operators
4945 @cindex operators, logical
4951 @opindex @r{<colon>}
4953 Logical: @samp{&} (logical and), @samp{:} (logical or).
4956 @cindex unary operators
4957 @cindex operators, unary
4961 @cindex @code{if} request, and the @samp{!} operator
4962 @cindex @code{while} request, and the @samp{!} operator
4963 Unary operators: @samp{-} (negating, i.e.@: changing the sign), @samp{+}
4964 (just for completeness; does nothing in expressions), @samp{!} (logical
4965 not; this works only within @code{if} and @code{while} requests). See
4966 below for the use of unary operators in motion requests.
4969 @cindex extremum operators (@code{>?}, @code{<?})
4970 @cindex operators, extremum (@code{>?}, @code{<?})
4973 Extrema: @samp{>?} (maximum), @samp{<?} (minimum).
4980 .nr z (\n[x] >? \n[y])
4984 The register@tie{}@code{z} now contains@tie{}5.
4987 @cindex scaling operator
4988 @cindex operator, scaling
4989 Scaling: @code{(@var{c};@var{e})}. Evaluate@tie{}@var{e} using@tie{}@var{c}
4990 as the default scaling indicator. If @var{c} is missing, ignore scaling
4991 indicators in the evaluation of@tie{}@var{e}.
4995 @cindex order of evaluation in expressions
4996 @cindex expression, order of evaluation
4999 Parentheses may be used as in any other language. However, in
5000 @code{gtroff} they are necessary to ensure order of evaluation.
5001 @code{gtroff} has no operator precedence; expressions are evaluated left
5002 to right. This means that @code{gtroff} evaluates @samp{3+5*4} as if it were
5003 parenthesized like @samp{(3+5)*4}, not as @samp{3+(5*4)}, as might be
5006 @cindex @code{+}, and page motion
5007 @cindex @code{-}, and page motion
5008 @cindex motion operators
5009 @cindex operators, motion
5010 For many requests which cause a motion on the page, the unary operators
5011 @samp{+} and @samp{-} work differently if leading an expression. They
5012 then indicate a motion relative to the current position (down or up,
5015 @cindex @code{|}, and page motion
5016 @cindex absolute position operator (@code{|})
5017 @cindex position, absolute, operator (@code{|})
5018 Similarly, a leading @samp{|} operator indicates an absolute position.
5019 For vertical movements, it specifies the distance from the top of the
5020 page; for horizontal movements, it gives the distance from the beginning
5021 of the @emph{input} line.
5023 @cindex @code{bp} request, using @code{+} and@tie{}@code{-}
5024 @cindex @code{in} request, using @code{+} and@tie{}@code{-}
5025 @cindex @code{ll} request, using @code{+} and@tie{}@code{-}
5026 @cindex @code{lt} request, using @code{+} and@tie{}@code{-}
5027 @cindex @code{nm} request, using @code{+} and@tie{}@code{-}
5028 @cindex @code{nr} request, using @code{+} and@tie{}@code{-}
5029 @cindex @code{pl} request, using @code{+} and@tie{}@code{-}
5030 @cindex @code{pn} request, using @code{+} and@tie{}@code{-}
5031 @cindex @code{po} request, using @code{+} and@tie{}@code{-}
5032 @cindex @code{ps} request, using @code{+} and@tie{}@code{-}
5033 @cindex @code{pvs} request, using @code{+} and@tie{}@code{-}
5034 @cindex @code{rt} request, using @code{+} and@tie{}@code{-}
5035 @cindex @code{ti} request, using @code{+} and@tie{}@code{-}
5036 @cindex @code{\H}, using @code{+} and@tie{}@code{-}
5037 @cindex @code{\R}, using @code{+} and@tie{}@code{-}
5038 @cindex @code{\s}, using @code{+} and@tie{}@code{-}
5039 @samp{+} and @samp{-} are also treated differently by the following
5040 requests and escapes: @code{bp}, @code{in}, @code{ll}, @code{lt},
5041 @code{nm}, @code{nr}, @code{pl}, @code{pn}, @code{po}, @code{ps},
5042 @code{pvs}, @code{rt}, @code{ti}, @code{\H}, @code{\R}, and @code{\s}.
5043 Here, leading plus and minus signs indicate increments and decrements.
5045 @xref{Setting Registers}, for some examples.
5047 @Defesc {\\B, ', anything, '}
5048 @cindex numeric expression, valid
5049 @cindex valid numeric expression
5050 Return@tie{}1 if @var{anything} is a valid numeric expression;
5051 or@tie{}0 if @var{anything} is empty or not a valid numeric expression.
5054 @cindex space characters, in expressions
5055 @cindex expressions, and space characters
5056 Due to the way arguments are parsed, spaces are not allowed in
5057 expressions, unless the entire expression is surrounded by parentheses.
5059 @xref{Request and Macro Arguments}, and @ref{Conditionals and Loops}.
5062 @c =====================================================================
5064 @node Identifiers, Embedded Commands, Expressions, gtroff Reference
5065 @section Identifiers
5068 Like any other language, @code{gtroff} has rules for properly formed
5069 @dfn{identifiers}. In @code{gtroff}, an identifier can be made up of
5070 almost any printable character, with the exception of the following
5075 @cindex whitespace characters
5076 @cindex newline character
5077 @cindex character, whitespace
5078 Whitespace characters (spaces, tabs, and newlines).
5081 @cindex character, backspace
5082 @cindex backspace character
5083 @cindex @acronym{EBCDIC} encoding of backspace
5084 Backspace (@acronym{ASCII}@tie{}@code{0x08} or
5085 @acronym{EBCDIC}@tie{}@code{0x16}) and character code @code{0x01}.
5088 @cindex invalid input characters
5089 @cindex input characters, invalid
5090 @cindex characters, invalid input
5092 The following input characters are invalid and are ignored if
5093 @code{groff} runs on a machine based on @acronym{ASCII}, causing a
5094 warning message of type @samp{input} (see @ref{Debugging}, for more
5095 details): @code{0x00}, @code{0x0B}, @code{0x0D}-@code{0x1F},
5096 @code{0x80}-@code{0x9F}.
5098 And here are the invalid input characters if @code{groff} runs on an
5099 @acronym{EBCDIC} host: @code{0x00}, @code{0x08}, @code{0x09},
5100 @code{0x0B}, @code{0x0D}-@code{0x14}, @code{0x17}-@code{0x1F},
5101 @code{0x30}-@code{0x3F}.
5103 Currently, some of these reserved codepoints are used internally, thus
5104 making it non-trivial to extend @code{gtroff} to cover Unicode or other
5105 character sets and encodings which use characters of these ranges.
5107 Note that invalid characters are removed before parsing; an
5108 identifier @code{foo}, followed by an invalid character, followed by
5109 @code{bar} is treated as @code{foobar}.
5112 For example, any of the following is valid.
5122 @cindex @code{]}, as part of an identifier
5124 Note that identifiers longer than two characters with a closing bracket
5125 (@samp{]}) in its name can't be accessed with escape sequences which
5126 expect an identifier as a parameter. For example, @samp{\[foo]]}
5127 accesses the glyph @samp{foo}, followed by @samp{]}, whereas
5128 @samp{\C'foo]'} really asks for glyph @samp{foo]}.
5130 @cindex @code{refer}, and macro names starting with @code{[} or @code{]}
5131 @cindex @code{[}, macro names starting with, and @code{refer}
5132 @cindex @code{]}, macro names starting with, and @code{refer}
5133 @cindex macro names, starting with @code{[} or @code{]}, and @code{refer}
5134 To avoid problems with the @code{refer} preprocessor, macro names
5135 should not start with @samp{[} or @samp{]}. Due to backwards
5136 compatibility, everything after @samp{.[} and @samp{.]} is handled as
5137 a special argument to @code{refer}. For example, @samp{.[foo} makes
5138 @code{refer} to start a reference, using @samp{foo} as a parameter.
5140 @Defesc {\\A, ', ident, '}
5141 Test whether an identifier @var{ident} is valid in @code{gtroff}. It
5142 expands to the character@tie{}1 or@tie{}0 according to whether its
5143 argument (usually delimited by quotes) is or is not acceptable as the
5144 name of a string, macro, diversion, number register, environment, or
5145 font. It returns@tie{}0 if no argument is given. This is useful for
5146 looking up user input in some sort of associative table.
5154 @xref{Escapes}, for details on parameter delimiting characters.
5156 Identifiers in @code{gtroff} can be any length, but, in some contexts,
5157 @code{gtroff} needs to be told where identifiers end and text begins
5158 (and in different ways depending on their length):
5164 @cindex @code{(}, starting a two-character identifier
5166 Two characters. Must be prefixed with @samp{(} in some situations.
5168 @cindex @code{[}, starting an identifier
5169 @cindex @code{]}, ending an identifier
5171 Arbitrary length (@code{gtroff} only). Must be bracketed with @samp{[}
5172 and@tie{}@samp{]} in some situations. Any length identifier can be put
5176 @cindex undefined identifiers
5177 @cindex identifiers, undefined
5178 Unlike many other programming languages, undefined identifiers are
5179 silently ignored or expanded to nothing.
5180 When @code{gtroff} finds an undefined identifier, it emits a
5181 warning, doing the following:
5185 If the identifier is a string, macro, or diversion,
5186 @code{gtroff} defines it as empty.
5189 If the identifier is a number register, @code{gtroff}
5190 defines it with a value of@tie{}0.
5193 @xref{Warnings}., @ref{Interpolating Registers}, and @ref{Strings}.
5195 Note that macros, strings, and diversions share the same name space.
5212 As can be seen in the previous example, @code{gtroff} reuses the
5213 identifier @samp{xxx}, changing it from a macro to a diversion.
5214 No warning is emitted! The contents of the first macro definition is
5217 @xref{Interpolating Registers}, and @ref{Strings}.
5220 @c =====================================================================
5222 @node Embedded Commands, Registers, Identifiers, gtroff Reference
5223 @section Embedded Commands
5224 @cindex embedded commands
5225 @cindex commands, embedded
5227 Most documents need more functionality beyond filling, adjusting and
5228 implicit line breaking. In order to gain further functionality,
5229 @code{gtroff} allows commands to be embedded into the text, in two ways.
5231 The first is a @dfn{request} which takes up an entire line, and does
5232 some large-scale operation (e.g.@: break lines, start new pages).
5234 The other is an @dfn{escape} which can be usually embedded anywhere
5235 in the text; most requests can accept it even as an argument.
5236 Escapes generally do more minor operations like sub- and superscripts,
5237 print a symbol, etc.
5245 @c ---------------------------------------------------------------------
5247 @node Requests, Macros, Embedded Commands, Embedded Commands
5248 @subsection Requests
5251 @cindex control character (@code{.})
5252 @cindex character, control (@code{.})
5253 @cindex no-break control character (@code{'})
5254 @cindex character, no-break control (@code{'})
5255 @cindex control character, no-break (@code{'})
5256 A request line begins with a control character, which is either a single
5257 quote (@samp{'}, the @dfn{no-break control character}) or a period
5258 (@samp{.}, the normal @dfn{control character}). These can be changed;
5259 see @ref{Character Translations}, for details. After this there may be
5260 optional tabs or spaces followed by an identifier which is the name of
5261 the request. This may be followed by any number of space-separated
5262 arguments (@emph{no} tabs here).
5264 @cindex structuring source code of documents or macro packages
5265 @cindex documents, structuring the source code
5266 @cindex macro packages, structuring the source code
5267 Since a control character followed by whitespace only is ignored, it
5268 is common practice to use this feature for structuring the source code
5269 of documents or macro packages.
5283 @cindex blank line macro (@code{blm})
5284 Another possibility is to use the blank line macro request @code{blm}
5285 by assigning an empty macro to it.
5290 .blm do-nothing \" activate blank line macro
5301 .blm \" deactivate blank line macro
5304 @xref{Blank Line Traps}.
5306 @cindex zero width space character (@code{\&})
5307 @cindex character, zero width space (@code{\&})
5308 @cindex space character, zero width (@code{\&})
5309 @cindex @code{\&}, escaping control characters
5310 To begin a line with a control character without it being interpreted,
5311 precede it with @code{\&}. This represents a zero width space, which
5312 means it does not affect the output.
5314 In most cases the period is used as a control character. Several
5315 requests cause a break implicitly; using the single quote control
5316 character prevents this.
5319 * Request and Macro Arguments::
5322 @node Request and Macro Arguments, , Requests, Requests
5323 @subsubsection Request and Macro Arguments
5324 @cindex request arguments
5325 @cindex macro arguments
5326 @cindex arguments to requests and macros
5328 Arguments to requests and macros are processed much like the shell:
5329 The line is split into arguments according to
5330 spaces.@footnote{Plan@tie{}9's @code{troff} implementation also allows
5331 tabs for argument separation -- @code{gtroff} intentionally doesn't
5334 @cindex spaces, in a macro argument
5335 An argument to a macro which is intended to contain spaces can either be
5336 enclosed in double quotes, or have the spaces @dfn{escaped} with
5337 backslashes. This is @emph{not} true for requests.
5339 Here are a few examples for a hypothetical macro @code{uh}:
5342 .uh The Mouse Problem
5343 .uh "The Mouse Problem"
5344 .uh The\ Mouse\ Problem
5347 @cindex @code{\~}, difference to @code{\@key{SP}}
5348 @cindex @code{\@key{SP}}, difference to @code{\~}
5350 The first line is the @code{uh} macro being called with 3 arguments,
5351 @samp{The}, @samp{Mouse}, and @samp{Problem}. The latter two have the
5352 same effect of calling the @code{uh} macro with one argument, @samp{The
5353 Mouse Problem}.@footnote{The last solution, i.e., using escaped spaces,
5354 is ``classical'' in the sense that it can be found in most @code{troff}
5355 documents. Nevertheless, it is not optimal in all situations, since
5356 @w{@samp{\ }} inserts a fixed-width, non-breaking space character which
5357 can't stretch. @code{gtroff} provides a different command @code{\~} to
5358 insert a stretchable, non-breaking space.}
5360 @cindex @code{"}, in a macro argument
5361 @cindex double quote, in a macro argument
5362 A double quote which isn't preceded by a space doesn't start a macro
5363 argument. If not closing a string, it is printed literally.
5368 .xxx a" "b c" "de"fg"
5372 has the arguments @samp{a"}, @w{@samp{b c}}, @samp{de}, and @samp{fg"}.
5373 Don't rely on this obscure behaviour!
5375 There are two possibilities to get a double quote reliably.
5379 Enclose the whole argument with double quotes and use two consecutive double
5380 quotes to represent a single one. This traditional solution has the
5381 disadvantage that double quotes don't survive argument expansion again if
5382 called in compatibility mode (using the @option{-C} option of @code{groff}):
5386 . tm xx: `\\$1' `\\$2' `\\$3'
5388 . yy "\\$1" "\\$2" "\\$3"
5391 . tm yy: `\\$1' `\\$2' `\\$3'
5393 .xx A "test with ""quotes""" .
5394 @result{} xx: `A' `test with "quotes"' `.'
5395 @result{} yy: `A' `test with ' `quotes""'
5399 If not in compatibility mode, you get the expected result
5402 xx: `A' `test with "quotes"' `.'
5403 yy: `A' `test with "quotes"' `.'
5407 since @code{gtroff} preserves the input level.
5410 Use the double quote glyph @code{\(dq}. This works with and without
5411 compatibility mode enabled since @code{gtroff} doesn't convert @code{\(dq}
5412 back to a double quote input character.
5414 Not that this method won't work with @acronym{UNIX} @code{troff} in general
5415 since the glyph `dq' isn't defined normally.
5418 @cindex @code{ds} request, and double quotes
5419 Double quotes in the @code{ds} request are handled differently.
5420 @xref{Strings}, for more details.
5422 @c ---------------------------------------------------------------------
5424 @node Macros, Escapes, Requests, Embedded Commands
5428 @code{gtroff} has a @dfn{macro} facility for defining a series of lines
5429 which can be invoked by name. They are called in the same manner as
5430 requests -- arguments also may be passed basically in the same manner.
5432 @xref{Writing Macros}, and @ref{Request and Macro Arguments}.
5434 @c ---------------------------------------------------------------------
5436 @node Escapes, , Macros, Embedded Commands
5440 Escapes may occur anywhere in the input to @code{gtroff}. They usually
5441 begin with a backslash and are followed by a single character which
5442 indicates the function to be performed. The escape character can be
5443 changed; see @ref{Character Translations}.
5445 Escape sequences which require an identifier as a parameter accept three
5446 possible syntax forms.
5450 The next single character is the identifier.
5452 @cindex @code{(}, starting a two-character identifier
5454 If this single character is an opening parenthesis, take the following
5455 two characters as the identifier. Note that there is no closing
5456 parenthesis after the identifier.
5458 @cindex @code{[}, starting an identifier
5459 @cindex @code{]}, ending an identifier
5461 If this single character is an opening bracket, take all characters
5462 until a closing bracket as the identifier.
5474 @cindex @code{'}, delimiting arguments
5475 @cindex argument delimiting characters
5476 @cindex characters, argument delimiting
5477 @cindex delimiting characters for arguments
5478 Other escapes may require several arguments and/or some special format.
5479 In such cases the argument is traditionally enclosed in single quotes
5480 (and quotes are always used in this manual for the definitions of escape
5481 sequences). The enclosed text is then processed according to what that
5482 escape expects. Example:
5488 @cindex @code{\o}, possible quote characters
5489 @cindex @code{\b}, possible quote characters
5490 @cindex @code{\X}, possible quote characters
5491 Note that the quote character can be replaced with any other character
5492 which does not occur in the argument (even a newline or a space
5493 character) in the following escapes: @code{\o}, @code{\b}, and
5494 @code{\X}. This makes e.g.
5503 @result{} A café in Paris
5507 possible, but it is better not to use this feature to avoid confusion.
5509 @cindex @code{\%}, used as delimiter
5510 @cindex @code{\@key{SP}}, used as delimiter
5511 @cindex @code{\|}, used as delimiter
5512 @cindex @code{\^}, used as delimiter
5513 @cindex @code{\@{}, used as delimiter
5514 @cindex @code{\@}}, used as delimiter
5515 @cindex @code{\'}, 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
5527 @cindex @code{\:}, used as delimiter
5530 @cindex @code{\@r{<colon>}}, used as delimiter
5532 @cindex @code{\~}, used as delimiter
5533 @cindex @code{\0}, used as delimiter
5534 @cindex @code{\a}, used as delimiter
5535 @cindex @code{\c}, used as delimiter
5536 @cindex @code{\d}, used as delimiter
5537 @cindex @code{\e}, used as delimiter
5538 @cindex @code{\E}, used as delimiter
5539 @cindex @code{\p}, used as delimiter
5540 @cindex @code{\r}, used as delimiter
5541 @cindex @code{\t}, used as delimiter
5542 @cindex @code{\u}, used as delimiter
5543 The following escapes sequences (which are handled similarly to
5544 characters since they don't take a parameter) are also allowed as
5545 delimiters: @code{\%}, @w{@samp{\ }}, @code{\|}, @code{\^}, @code{\@{},
5546 @code{\@}}, @code{\'}, @code{\`}, @code{\-}, @code{\_}, @code{\!},
5547 @code{\?}, @code{\@@}, @code{\)}, @code{\/}, @code{\,}, @code{\&},
5548 @code{\:}, @code{\~}, @code{\0}, @code{\a}, @code{\c}, @code{\d},
5549 @code{\e}, @code{\E}, @code{\p}, @code{\r}, @code{\t}, and @code{\u}.
5550 Again, don't use these if possible.
5552 @cindex @code{\A}, allowed delimiters
5553 @cindex @code{\B}, allowed delimiters
5554 @cindex @code{\Z}, allowed delimiters
5555 @cindex @code{\C}, allowed delimiters
5556 @cindex @code{\w}, allowed delimiters
5557 No newline characters as delimiters are allowed in the following
5558 escapes: @code{\A}, @code{\B}, @code{\Z}, @code{\C}, and @code{\w}.
5560 @cindex @code{\D}, allowed delimiters
5561 @cindex @code{\h}, allowed delimiters
5562 @cindex @code{\H}, allowed delimiters
5563 @cindex @code{\l}, allowed delimiters
5564 @cindex @code{\L}, allowed delimiters
5565 @cindex @code{\N}, allowed delimiters
5566 @cindex @code{\R}, allowed delimiters
5567 @cindex @code{\s}, allowed delimiters
5568 @cindex @code{\S}, allowed delimiters
5569 @cindex @code{\v}, allowed delimiters
5570 @cindex @code{\x}, allowed delimiters
5571 Finally, the escapes @code{\D}, @code{\h}, @code{\H}, @code{\l},
5572 @code{\L}, @code{\N}, @code{\R}, @code{\s}, @code{\S}, @code{\v},
5573 and @code{\x} can't use the following characters as delimiters:
5577 @cindex numbers, and delimiters
5578 @cindex digits, and delimiters
5579 The digits @code{0}-@code{9}.
5582 @cindex operators, as delimiters
5583 @cindex @code{+}, as delimiter
5584 @cindex @code{-}, as delimiter
5585 @cindex @code{/}, as delimiter
5586 @cindex @code{*}, as delimiter
5587 @cindex @code{%}, as delimiter
5588 @cindex @code{<}, as delimiter
5589 @cindex @code{>}, as delimiter
5590 @cindex @code{=}, as delimiter
5591 @cindex @code{&}, as delimiter
5593 @cindex @code{:}, as delimiter
5596 @cindex <colon>, as delimiter
5598 @cindex @code{(}, as delimiter
5599 @cindex @code{)}, as delimiter
5600 @cindex @code{.}, as delimiter
5601 The (single-character) operators @samp{+-/*%<>=&:().}.
5604 @cindex space character
5605 @cindex character, space
5606 @cindex tab character
5607 @cindex character, tab
5608 @cindex newline character
5609 @cindex character, newline
5610 The space, tab, and newline characters.
5613 @cindex @code{\%}, used as delimiter
5615 @cindex @code{\:}, used as delimiter
5618 @cindex @code{\@r{<colon>}}, used as delimiter
5620 @cindex @code{\@{}, used as delimiter
5621 @cindex @code{\@}}, used as delimiter
5622 @cindex @code{\'}, used as delimiter
5623 @cindex @code{\`}, used as delimiter
5624 @cindex @code{\-}, 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{\c}, used as delimiter
5630 @cindex @code{\e}, used as delimiter
5631 @cindex @code{\p}, used as delimiter
5632 All escape sequences except @code{\%}, @code{\:}, @code{\@{}, @code{\@}},
5633 @code{\'}, @code{\`}, @code{\-}, @code{\_}, @code{\!}, @code{\@@},
5634 @code{\/}, @code{\c}, @code{\e}, and @code{\p}.
5637 @cindex printing backslash (@code{\\}, @code{\e}, @code{\E}, @code{\[rs]})
5638 @cindex backslash, printing (@code{\\}, @code{\e}, @code{\E}, @code{\[rs]})
5639 To have a backslash (actually, the current escape character) appear in the
5640 output several escapes are defined: @code{\\}, @code{\e} or @code{\E}.
5641 These are very similar, and only differ with respect to being used in
5642 macros or diversions. @xref{Character Translations}, for an exact
5643 description of those escapes.
5645 @xref{Implementation Differences}, @ref{Copy-in Mode}, and @ref{Diversions},
5646 @ref{Identifiers}, for more information.
5652 @node Comments, , Escapes, Escapes
5653 @subsubsection Comments
5656 Probably one of the most@footnote{Unfortunately, this is a lie. But
5657 hopefully future @code{gtroff} hackers will believe it @code{:-)}}
5658 common forms of escapes is the comment.
5661 Start a comment. Everything to the end of the input line is ignored.
5663 This may sound simple, but it can be tricky to keep the comments from
5664 interfering with the appearance of the final output.
5666 @cindex @code{ds}, @code{ds1} requests, and comments
5667 @cindex @code{as}, @code{as1} requests, and comments
5668 If the escape is to the right of some text or a request, that portion
5669 of the line is ignored, but the space leading up to it is noticed by
5670 @code{gtroff}. This only affects the @code{ds} and @code{as}
5671 request and its variants.
5673 @cindex tabs, before comments
5674 @cindex comments, lining up with tabs
5675 One possibly irritating idiosyncracy is that tabs must not be used to
5676 line up comments. Tabs are not treated as whitespace between the
5677 request and macro arguments.
5679 @cindex undefined request
5680 @cindex request, undefined
5681 A comment on a line by itself is treated as a blank line, because
5682 after eliminating the comment, that is all that remains:
5699 To avoid this, it is common to start the line with @code{.\"} which
5700 causes the line to be treated as an undefined request and thus ignored
5703 @cindex @code{'}, as a comment
5704 Another commenting scheme seen sometimes is three consecutive single
5705 quotes (@code{'''}) at the beginning of a line. This works, but
5706 @code{gtroff} gives a warning about an undefined macro (namely
5707 @code{''}), which is harmless, but irritating.
5711 To avoid all this, @code{gtroff} has a new comment mechanism using the
5712 @code{\#} escape. This escape works the same as @code{\"} except that
5713 the newline is also ignored:
5732 @Defreq {ig, [@Var{end}]}
5733 Ignore all input until @code{gtroff} encounters the macro named
5734 @code{.}@var{end} on a line by itself (or @code{..} if @var{end} is not
5735 specified). This is useful for commenting out large blocks of text:
5740 This is part of a large block
5741 of text that has been
5742 temporarily(?) commented out.
5744 We can restore it simply by removing
5745 the .ig request and the ".." at the
5748 More text text text...
5755 text text text@dots{} More text text text@dots{}
5759 Note that the commented-out block of text does not
5762 The input is read in copy-mode; auto-incremented registers @emph{are}
5763 affected (@pxref{Auto-increment}).
5767 @c =====================================================================
5769 @node Registers, Manipulating Filling and Adjusting, Embedded Commands, gtroff Reference
5773 Numeric variables in @code{gtroff} are called @dfn{registers}. There
5774 are a number of built-in registers, supplying anything from the date to
5775 details of formatting parameters.
5777 @xref{Identifiers}, for details on register identifiers.
5780 * Setting Registers::
5781 * Interpolating Registers::
5783 * Assigning Formats::
5784 * Built-in Registers::
5787 @c ---------------------------------------------------------------------
5789 @node Setting Registers, Interpolating Registers, Registers, Registers
5790 @subsection Setting Registers
5791 @cindex setting registers (@code{nr}, @code{\R})
5792 @cindex registers, setting (@code{nr}, @code{\R})
5794 Define or set registers using the @code{nr} request or the
5797 @DefreqList {nr, ident value}
5798 @DefescListEnd {\\R, ', ident value, '}
5799 Set number register @var{ident} to @var{value}. If @var{ident}
5800 doesn't exist, @code{gtroff} creates it.
5802 The argument to @code{\R} usually has to be enclosed in quotes.
5803 @xref{Escapes}, for details on parameter delimiting characters.
5805 The @code{\R} escape doesn't produce an input token in @code{gtroff};
5806 with other words, it vanishes completely after @code{gtroff} has
5810 For example, the following two lines are equivalent:
5813 .nr a (((17 + (3 * 4))) % 4)
5814 \R'a (((17 + (3 * 4))) % 4)'
5818 Both @code{nr} and @code{\R} have two additional special forms to
5819 increment or decrement a register.
5821 @DefreqList {nr, ident @t{+}@Var{value}}
5822 @DefreqItem {nr, ident @t{-}@Var{value}}
5823 @DefescItem {\\R, ', ident @t{+}value, '}
5824 @DefescListEnd {\\R, ', ident @t{-}value, '}
5825 Increment (decrement) register @var{ident} by @var{value}.
5834 @cindex negating register values
5835 To assign the negated value of a register to another register, some care
5836 must be taken to get the desired result:
5850 The surrounding parentheses prevent the interpretation of the minus sign
5851 as a decrementing operator. An alternative is to start the assignment
5867 @cindex removing number register (@code{rr})
5868 @cindex number register, removing (@code{rr})
5869 @cindex register, removing (@code{rr})
5870 Remove number register @var{ident}. If @var{ident} doesn't exist, the
5874 @Defreq {rnn, ident1 ident2}
5875 @cindex renaming number register (@code{rnn})
5876 @cindex number register, renaming (@code{rnn})
5877 @cindex register, renaming (@code{rnn})
5878 Rename number register @var{ident1} to @var{ident2}. If either
5879 @var{ident1} or @var{ident2} doesn't exist, the request is ignored.
5882 @Defreq {aln, ident1 ident2}
5883 @cindex alias, number register, creating (@code{aln})
5884 @cindex creating alias, for number register (@code{aln})
5885 @cindex number register, creating alias (@code{aln})
5886 @cindex register, creating alias (@code{aln})
5887 Create an alias @var{ident1} for a number register @var{ident2}. The
5888 new name and the old name are exactly equivalent. If @var{ident1} is
5889 undefined, a warning of type @samp{reg} is generated, and the request
5890 is ignored. @xref{Debugging}, for information about warnings.
5893 @c ---------------------------------------------------------------------
5895 @node Interpolating Registers, Auto-increment, Setting Registers, Registers
5896 @subsection Interpolating Registers
5897 @cindex interpolating registers (@code{\n})
5898 @cindex registers, interpolating (@code{\n})
5900 Numeric registers can be accessed via the @code{\n} escape.
5902 @DefescList {\\n, , i, }
5903 @DefescItem {\\n, @Lparen{}, id, }
5904 @DefescListEnd {\\n, @Lbrack{}, ident, @Rbrack{}}
5905 @cindex nested assignments
5906 @cindex assignments, nested
5907 @cindex indirect assignments
5908 @cindex assignments, indirect
5909 Interpolate number register with name @var{ident} (one-character
5910 name@tie{}@var{i}, two-character name @var{id}). This means that the value
5911 of the register is expanded in-place while @code{gtroff} is parsing the
5912 input line. Nested assignments (also called indirect assignments) are
5934 @c ---------------------------------------------------------------------
5936 @node Auto-increment, Assigning Formats, Interpolating Registers, Registers
5937 @subsection Auto-increment
5938 @cindex auto-increment
5939 @cindex increment, automatic
5941 Number registers can also be auto-incremented and auto-decremented.
5942 The increment or decrement value can be specified with a third
5943 argument to the @code{nr} request or @code{\R} escape.
5945 @Defreq {nr, ident value incr}
5946 @cindex @code{\R}, difference to @code{nr}
5947 Set number register @var{ident} to @var{value}; the increment for
5948 auto-incrementing is set to @var{incr}. Note that the @code{\R}
5949 escape doesn't support this notation.
5952 To activate auto-incrementing, the escape @code{\n} has a special
5955 @DefescList {\\n, +, i, }
5956 @DefescItem {\\n, -, i, }
5957 @DefescItem {\\n, @Lparen{}+, id, }
5958 @DefescItem {\\n, @Lparen{}-, id, }
5959 @DefescItem {\\n, +@Lparen{}, id, }
5960 @DefescItem {\\n, -@Lparen{}, id, }
5961 @DefescItem {\\n, @Lbrack{}+, ident, @Rbrack{}}
5962 @DefescItem {\\n, @Lbrack{}-, ident, @Rbrack{}}
5963 @DefescItem {\\n, +@Lbrack{}, ident, @Rbrack{}}
5964 @DefescListEnd {\\n, -@Lbrack{}, ident, @Rbrack{}}
5965 Before interpolating, increment or decrement @var{ident}
5966 (one-character name@tie{}@var{i}, two-character name @var{id}) by the
5967 auto-increment value as specified with the @code{nr} request (or the
5968 @code{\R} escape). If no auto-increment value has been specified,
5969 these syntax forms are identical to @code{\n}.
5978 \n+a, \n+a, \n+a, \n+a, \n+a
5980 \n-(xx, \n-(xx, \n-(xx, \n-(xx, \n-(xx
5982 \n+[foo], \n+[foo], \n+[foo], \n+[foo], \n+[foo]
5990 -5, -10, -15, -20, -25
5994 @cindex increment value without changing the register
5995 @cindex value, incrementing without changing the register
5996 To change the increment value without changing the value of a register
5997 (@var{a} in the example), the following can be used:
6003 @c ---------------------------------------------------------------------
6005 @node Assigning Formats, Built-in Registers, Auto-increment, Registers
6006 @subsection Assigning Formats
6007 @cindex assigning formats (@code{af})
6008 @cindex formats, assigning (@code{af})
6010 When a register is used in the text of an input file (as opposed to
6011 part of an expression), it is textually replaced (or interpolated)
6012 with a representation of that number. This output format can be
6013 changed to a variety of formats (numbers, Roman numerals, etc.). This
6014 is done using the @code{af} request.
6016 @Defreq {af, ident format}
6017 Change the output format of a number register. The first argument
6018 @var{ident} is the name of the number register to be changed, and the
6019 second argument @var{format} is the output format. The following
6020 output formats are available:
6024 Decimal arabic numbers. This is the default format: 0, 1, 2,
6028 Decimal numbers with as many digits as specified. So, @samp{00} would
6029 result in printing numbers as 01, 02, 03,@tie{}@enddots{}
6031 In fact, any digit instead of zero will do; @code{gtroff} only counts
6032 how many digits are specified. As a consequence, @code{af}'s default
6033 format @samp{1} could be specified as @samp{0} also (and exactly this is
6034 returned by the @code{\g} escape, see below).
6037 @cindex Roman numerals
6038 @cindex numerals, Roman
6039 Upper-case Roman numerals: 0, I, II, III, IV,@tie{}@enddots{}
6042 Lower-case Roman numerals: 0, i, ii, iii, iv,@tie{}@enddots{}
6045 Upper-case letters: 0, A, B, C, @dots{},@tie{}Z, AA, AB,@tie{}@enddots{}
6048 Lower-case letters: 0, a, b, c, @dots{},@tie{}z, aa, ab,@tie{}@enddots{}
6051 Omitting the number register format causes a warning of type
6052 @samp{missing}. @xref{Debugging}, for more details. Specifying a
6053 nonexistent format causes an error.
6055 The following example produces @samp{10, X, j, 010}:
6059 .af a 1 \" the default format
6069 @cindex Roman numerals, maximum and minimum
6070 @cindex maximum values of Roman numerals
6071 @cindex minimum values of Roman numerals
6072 The largest number representable for the @samp{i} and @samp{I} formats
6073 is 39999 (or @minus{}39999); @acronym{UNIX} @code{troff} uses @samp{z}
6074 and @samp{w} to represent 10000 and 5000 in Roman numerals, and so does
6075 @code{gtroff}. Currently, the correct glyphs of Roman numeral five
6076 thousand and Roman numeral ten thousand (Unicode code points
6077 @code{U+2182} and @code{U+2181}, respectively) are not available.
6079 If @var{ident} doesn't exist, it is created.
6081 @cindex read-only register, changing format
6082 @cindex changing format, and read-only registers
6083 Changing the output format of a read-only register causes an error. It
6084 is necessary to first copy the register's value to a writeable register,
6085 then apply the @code{af} request to this other register.
6088 @DefescList {\\g, , i, }
6089 @DefescItem {\\g, @Lparen{}, id, }
6090 @DefescListEnd {\\g, @Lbrack{}, ident, @Rbrack{}}
6091 @cindex format of register (@code{\g})
6092 @cindex register, format (@code{\g})
6093 Return the current format of the specified register @var{ident}
6094 (one-character name@tie{}@var{i}, two-character name @var{id}). For
6095 example, @samp{\ga} after the previous example would produce the
6096 string @samp{000}. If the register hasn't been defined yet, nothing
6100 @c ---------------------------------------------------------------------
6102 @node Built-in Registers, , Assigning Formats, Registers
6103 @subsection Built-in Registers
6104 @cindex built-in registers
6105 @cindex registers, built-in
6107 The following lists some built-in registers which are not described
6108 elsewhere in this manual. Any register which begins with a @samp{.} is
6109 read-only. A complete listing of all built-in registers can be found in
6110 @ref{Register Index}.
6114 @cindex current input file name register (@code{.F})
6115 @cindex input file name, current, register (@code{.F})
6117 This string-valued register returns the current input file name.
6120 @cindex horizontal resolution register (@code{.H})
6121 @cindex resolution, horizontal, register (@code{.H})
6123 Horizontal resolution in basic units.
6129 @cindex mode, unsafe
6130 If @code{gtroff} is called with the @option{-U} command line option, the
6131 number register @code{.U} is set to@tie{}1, and zero otherwise.
6132 @xref{Groff Options}.
6135 @cindex vertical resolution register (@code{.V})
6136 @cindex resolution, vertical, register (@code{.V})
6138 Vertical resolution in basic units.
6141 @cindex seconds, current time (@code{seconds})
6142 @cindex time, current, seconds (@code{seconds})
6143 @cindex current time, seconds (@code{seconds})
6145 The number of seconds after the minute, normally in the range@tie{}0
6146 to@tie{}59, but can be up to@tie{}61 to allow for leap seconds. Initialized
6147 at start-up of @code{gtroff}.
6150 @cindex minutes, current time (@code{minutes})
6151 @cindex time, current, minutes (@code{minutes})
6152 @cindex current time, minutes (@code{minutes})
6154 The number of minutes after the hour, in the range@tie{}0 to@tie{}59.
6155 Initialized at start-up of @code{gtroff}.
6158 @cindex hours, current time (@code{hours})
6159 @cindex time, current, hours (@code{hours})
6160 @cindex current time, hours (@code{hours})
6162 The number of hours past midnight, in the range@tie{}0 to@tie{}23.
6163 Initialized at start-up of @code{gtroff}.
6166 @cindex day of the week register (@code{dw})
6167 @cindex date, day of the week register (@code{dw})
6169 Day of the week (1-7).
6172 @cindex day of the month register (@code{dy})
6173 @cindex date, day of the month register (@code{dy})
6175 Day of the month (1-31).
6178 @cindex month of the year register (@code{mo})
6179 @cindex date, month of the year register (@code{mo})
6181 Current month (1-12).
6184 @cindex date, year register (@code{year}, @code{yr})
6185 @cindex year, current, register (@code{year}, @code{yr})
6191 The current year minus@tie{}1900. Unfortunately, the documentation of
6192 @acronym{UNIX} Version@tie{}7's @code{troff} had a year@tie{}2000 bug: It
6193 incorrectly claimed that @code{yr} contains the last two digits of the
6194 year. That claim has never been true of either @acronym{AT&T}
6195 @code{troff} or GNU @code{troff}. Old @code{troff} input that looks
6199 '\" The following line stopped working after 1999
6200 This document was formatted in 19\n(yr.
6204 can be corrected as follows:
6207 This document was formatted in \n[year].
6211 or, to be portable to older @code{troff} versions, as follows:
6215 This document was formatted in \n(y4.
6222 @cindex input line number register (@code{.c}, @code{c.})
6223 @cindex line number, input, register (@code{.c}, @code{c.})
6224 The current @emph{input} line number. Register @samp{.c} is read-only,
6225 whereas @samp{c.} (a @code{gtroff} extension) is writable also,
6226 affecting both @samp{.c} and @samp{c.}.
6230 @cindex output line number register (@code{ln})
6231 @cindex line number, output, register (@code{ln})
6232 The current @emph{output} line number after a call to the @code{nm}
6233 request to activate line numbering.
6235 @xref{Miscellaneous}, for more information about line numbering.
6239 @cindex major version number register (@code{.x})
6240 @cindex version number, major, register (@code{.x})
6241 The major version number. For example, if the version number
6242 is 1.03 then @code{.x} contains@tie{}@samp{1}.
6246 @cindex minor version number register (@code{.y})
6247 @cindex version number, minor, register (@code{.y})
6248 The minor version number. For example, if the version number
6249 is 1.03 then @code{.y} contains@tie{}@samp{03}.
6253 @cindex revision number register (@code{.Y})
6254 The revision number of @code{groff}.
6258 @cindex process ID of @code{gtroff} register (@code{$$})
6259 @cindex @code{gtroff}, process ID register (@code{$$})
6260 The process ID of @code{gtroff}.
6264 @cindex @code{gtroff}, identification register (@code{.g})
6265 @cindex GNU-specific register (@code{.g})
6266 Always@tie{}1. Macros should use this to determine whether they are
6267 running under GNU @code{troff}.
6271 @cindex @acronym{ASCII} approximation output register (@code{.A})
6272 If the command line option @option{-a} is used to produce an
6273 @acronym{ASCII} approximation of the output, this is set to@tie{}1, zero
6274 otherwise. @xref{Groff Options}.
6278 This register is set to@tie{}1 (and to@tie{}0 otherwise) if the current
6279 page is actually being printed, i.e., if the @option{-o} option is being
6280 used to only print selected pages. @xref{Groff Options}, for more
6285 If @code{gtroff} is called with the @option{-T} command line option, the
6286 number register @code{.T} is set to@tie{}1, and zero otherwise.
6287 @xref{Groff Options}.
6291 @cindex output device name string register (@code{.T})
6292 A single read-write string register which contains the current output
6293 device (for example, @samp{latin1} or @samp{ps}). This is the only
6294 string register defined by @code{gtroff}.
6298 @c =====================================================================
6300 @node Manipulating Filling and Adjusting, Manipulating Hyphenation, Registers, gtroff Reference
6301 @section Manipulating Filling and Adjusting
6302 @cindex manipulating filling and adjusting
6303 @cindex filling and adjusting, manipulating
6304 @cindex adjusting and filling, manipulating
6305 @cindex justifying text
6306 @cindex text, justifying
6310 @cindex @code{bp} request, causing implicit linebreak
6311 @cindex @code{ce} request, causing implicit linebreak
6312 @cindex @code{cf} request, causing implicit linebreak
6313 @cindex @code{fi} request, causing implicit linebreak
6314 @cindex @code{fl} request, causing implicit linebreak
6315 @cindex @code{in} request, causing implicit linebreak
6316 @cindex @code{nf} request, causing implicit linebreak
6317 @cindex @code{rj} request, causing implicit linebreak
6318 @cindex @code{sp} request, causing implicit linebreak
6319 @cindex @code{ti} request, causing implicit linebreak
6320 @cindex @code{trf} request, causing implicit linebreak
6321 Various ways of causing @dfn{breaks} were given in @ref{Implicit Line
6322 Breaks}. The @code{br} request likewise causes a break. Several
6323 other requests also cause breaks, but implicitly. These are
6324 @code{bp}, @code{ce}, @code{cf}, @code{fi}, @code{fl}, @code{in},
6325 @code{nf}, @code{rj}, @code{sp}, @code{ti}, and @code{trf}.
6328 Break the current line, i.e., the input collected so far is emitted
6331 If the no-break control character is used, @code{gtroff} suppresses
6342 Initially, @code{gtroff} fills and adjusts text to both margins.
6343 Filling can be disabled via the @code{nf} request and re-enabled with
6344 the @code{fi} request.
6348 @cindex fill mode (@code{fi})
6349 @cindex mode, fill (@code{fi})
6350 Activate fill mode (which is the default). This request implicitly
6351 enables adjusting; it also inserts a break in the text currently being
6352 filled. The read-only number register @code{.u} is set to@tie{}1.
6354 The fill mode status is associated with the current environment
6355 (@pxref{Environments}).
6357 See @ref{Line Control}, for interaction with the @code{\c} escape.
6361 @cindex no-fill mode (@code{nf})
6362 @cindex mode, no-fill (@code{nf})
6363 Activate no-fill mode. Input lines are output as-is, retaining line
6364 breaks and ignoring the current line length. This command implicitly
6365 disables adjusting; it also causes a break. The number register
6366 @code{.u} is set to@tie{}0.
6368 The fill mode status is associated with the current environment
6369 (@pxref{Environments}).
6371 See @ref{Line Control}, for interaction with the @code{\c} escape.
6374 @DefreqList {ad, [@Var{mode}]}
6378 Activation and deactivation of adjusting is done implicitly with
6379 calls to the @code{fi} or @code{nf} requests.
6381 @var{mode} can have one of the following values:
6385 @cindex ragged-right
6386 Adjust text to the left margin. This produces what is traditionally
6387 called ragged-right text.
6391 Adjust text to the right margin, producing ragged-left text.
6394 @cindex centered text
6395 @cindex @code{ce} request, difference to @samp{.ad@tie{}c}
6396 Center filled text. This is different to the @code{ce} request which
6397 only centers text without filling.
6401 Justify to both margins. This is the default used by @code{gtroff}.
6404 Finally, @var{mode} can be the numeric argument returned by the @code{.j}
6407 With no argument, @code{gtroff} adjusts lines in the same way it did
6408 before adjusting was deactivated (with a call to @code{na}, for
6420 .ad \" back to centering
6422 .ad \n[ad] \" back to right justifying
6425 @cindex adjustment mode register (@code{.j})
6426 The current adjustment mode is available in the read-only number
6427 register @code{.j}; it can be stored and subsequently used to set
6430 The adjustment mode status is associated with the current environment
6431 (@pxref{Environments}).
6435 Disable adjusting. This request won't change the current adjustment
6436 mode: A subsequent call to @code{ad} uses the previous adjustment
6439 The adjustment mode status is associated with the current environment
6440 (@pxref{Environments}).
6444 @DefescListEnd {\\p, , , }
6445 Adjust the current line and cause a break.
6447 In most cases this produces very ugly results since @code{gtroff}
6448 doesn't have a sophisticated paragraph building algorithm (as @TeX{}
6449 have, for example); instead, @code{gtroff} fills and adjusts a paragraph
6453 This is an uninteresting sentence.
6454 This is an uninteresting sentence.\p
6455 This is an uninteresting sentence.
6462 This is an uninteresting sentence. This is an
6463 uninteresting sentence.
6464 This is an uninteresting sentence.
6468 @DefreqList {ss, word_space_size [@Var{sentence_space_size}]}
6470 @DefregListEnd {.sss}
6471 @cindex word space size register (@code{.ss})
6472 @cindex size of word space register (@code{.ss})
6473 @cindex space between words register (@code{.ss})
6474 @cindex sentence space size register (@code{.sss})
6475 @cindex size of sentence space register (@code{.sss})
6476 @cindex space between sentences register (@code{.sss})
6477 Change the size of a space between words. It takes its units as one
6478 twelfth of the space width parameter for the current font.
6479 Initially both the @var{word_space_size} and @var{sentence_space_size}
6480 are@tie{}12. In fill mode, the values specify the minimum distance.
6484 If two arguments are given to the @code{ss} request, the second
6485 argument sets the sentence space size. If the second argument is not
6486 given, sentence space size is set to @var{word_space_size}. The
6487 sentence space size is used in two circumstances: If the end of a
6488 sentence occurs at the end of a line in fill mode, then both an
6489 inter-word space and a sentence space are added; if two spaces follow
6490 the end of a sentence in the middle of a line, then the second space
6491 is a sentence space. If a second argument is never given to the
6492 @code{ss} request, the behaviour of @acronym{UNIX} @code{troff} is the
6493 same as that exhibited by GNU @code{troff}. In GNU @code{troff}, as
6494 in @acronym{UNIX} @code{troff}, a sentence should always be followed
6495 by either a newline or two spaces.
6497 The read-only number registers @code{.ss} and @code{.sss} hold the
6498 values of the parameters set by the first and second arguments of the
6501 The word space and sentence space values are associated with the current
6502 environment (@pxref{Environments}).
6504 Contrary to @acronym{AT&T} @code{troff}, this request is @emph{not}
6505 ignored if a TTY output device is used; the given values are then
6506 rounded down to a multiple of@tie{}12 (@pxref{Implementation Differences}).
6508 The request is ignored if there is no parameter.
6510 @cindex discardable horizontal space
6511 @cindex space, discardable, horizontal
6512 @cindex horizontal discardable space
6513 Another useful application of the @code{ss} request is to insert
6514 discardable horizontal space, i.e., space which is discarded at a line
6515 break. For example, paragraph-style footnotes could be separated this
6520 1.\ This is the first footnote.\c
6524 2.\ This is the second footnote.
6531 1. This is the first footnote. 2. This
6532 is the second footnote.
6536 Note that the @code{\h} escape produces unbreakable space.
6539 @DefreqList {ce, [@Var{nnn}]}
6540 @DefregListEnd {.ce}
6541 @cindex centering lines (@code{ce})
6542 @cindex lines, centering (@code{ce})
6543 Center text. While the @w{@samp{.ad c}} request also centers text,
6544 it fills the text as well. @code{ce} does not fill the
6545 text it affects. This request causes a break. The number of lines
6546 still to be centered is associated with the current environment
6547 (@pxref{Environments}).
6549 The following example demonstrates the differences.
6555 This is a small text fragment which shows the differences
6556 between the `.ce' and the `.ad c' request.
6560 This is a small text fragment which shows the differences
6561 between the `.ce' and the `.ad c' request.
6565 And here the result:
6568 This is a small text fragment which
6569 shows the differences
6570 between the `.ce' and the `.ad c' request.
6572 This is a small text fragment which
6573 shows the differences between the `.ce'
6574 and the `.ad c' request.
6577 With no arguments, @code{ce} centers the next line of text. @var{nnn}
6578 specifies the number of lines to be centered. If the argument is zero
6579 or negative, centering is disabled.
6581 The basic length for centering text is the line length (as set with the
6582 @code{ll} request) minus the indentation (as set with the @code{in}
6583 request). Temporary indentation is ignored.
6585 As can be seen in the previous example, it is a common idiom to turn
6586 on centering for a large number of lines, and to turn off centering
6587 after text to be centered. This is useful for any request which takes
6588 a number of lines as an argument.
6590 The @code{.ce} read-only number register contains the number of lines
6591 remaining to be centered, as set by the @code{ce} request.
6594 @DefreqList {rj, [@Var{nnn}]}
6595 @DefregListEnd {.rj}
6596 @cindex justifying text (@code{rj})
6597 @cindex text, justifying (@code{rj})
6598 @cindex right-justifying (@code{rj})
6599 Justify unfilled text to the right margin. Arguments are identical to
6600 the @code{ce} request. The @code{.rj} read-only number register is
6601 the number of lines to be right-justified as set by the @code{rj}
6602 request. This request causes a break. The number of lines still to be
6603 right-justified is associated with the current environment
6604 (@pxref{Environments}).
6608 @c =====================================================================
6610 @node Manipulating Hyphenation, Manipulating Spacing, Manipulating Filling and Adjusting, gtroff Reference
6611 @section Manipulating Hyphenation
6612 @cindex manipulating hyphenation
6613 @cindex hyphenation, manipulating
6616 Here a description of requests which influence hyphenation.
6618 @DefreqList {hy, [@Var{mode}]}
6619 @DefregListEnd {.hy}
6620 Enable hyphenation. The request has an optional numeric argument,
6621 @var{mode}, to restrict hyphenation if necessary:
6625 The default argument if @var{mode} is omitted. Hyphenate without
6626 restrictions. This is also the start-up value of @code{gtroff}.
6629 Do not hyphenate the last word on a page or column.
6632 Do not hyphenate the last two characters of a word.
6635 Do not hyphenate the first two characters of a word.
6638 Values in the previous table are additive. For example, the
6639 value@tie{}12 causes @code{gtroff} to neither hyphenate the last
6640 two nor the first two characters of a word.
6642 @cindex hyphenation restrictions register (@code{.hy})
6643 The current hyphenation restrictions can be found in the read-only
6644 number register @samp{.hy}.
6646 The hyphenation mode is associated with the current environment
6647 (@pxref{Environments}).
6651 Disable hyphenation (i.e., set the hyphenation mode to zero). Note
6652 that the hyphenation mode of the last call to @code{hy} is not
6655 The hyphenation mode is associated with the current environment
6656 (@pxref{Environments}).
6659 @DefreqList {hlm, [@Var{nnn}]}
6661 @DefregListEnd {.hlc}
6662 @cindex explicit hyphen (@code{\%})
6663 @cindex hyphen, explicit (@code{\%})
6664 @cindex consecutive hyphenated lines (@code{hlm})
6665 @cindex lines, consecutive hyphenated (@code{hlm})
6666 @cindex hyphenated lines, consecutive (@code{hlm})
6667 Set the maximum number of consecutive hyphenated lines to @var{nnn}.
6668 If this number is negative, there is no maximum. The default value
6669 is@tie{}@minus{}1 if @var{nnn} is omitted. This value is associated
6670 with the current environment (@pxref{Environments}). Only lines
6671 output from a given environment count towards the maximum associated
6672 with that environment. Hyphens resulting from @code{\%} are counted;
6673 explicit hyphens are not.
6675 The current setting of @code{hlm} is available in the @code{.hlm}
6676 read-only number register. Also the number of immediately preceding
6677 consecutive hyphenated lines are available in the read-only number
6678 register @samp{.hlc}.
6681 @Defreq {hw, word1 word2 @dots{}}
6682 Define how @var{word1}, @var{word2}, etc.@: are to be hyphenated. The
6683 words must be given with hyphens at the hyphenation points. For
6691 Besides the space character, any character whose hyphenation code value
6692 is zero can be used to separate the arguments of @code{hw} (see the
6693 documentation for the @code{hcode} request below for more information).
6694 In addition, this request can be used more than once.
6696 Hyphenation exceptions specified with the @code{hw} request are
6697 associated with the current hyphenation language; it causes an error
6698 if there is no current hyphenation language.
6700 This request is ignored if there is no parameter.
6702 In old versions of @code{troff} there was a limited amount of space to
6703 store such information; fortunately, with @code{gtroff}, this is no
6704 longer a restriction.
6707 @DefescList {\\%, , , }
6708 @deffnx Escape @t{\:}
6713 @esindex \@r{<colon>}
6715 @cindex hyphenation character (@code{\%})
6716 @cindex character, hyphenation (@code{\%})
6717 @cindex disabling hyphenation (@code{\%})
6718 @cindex hyphenation, disabling (@code{\%})
6719 To tell @code{gtroff} how to hyphenate words on the fly, use the
6720 @code{\%} escape, also known as the @dfn{hyphenation character}.
6721 Preceding a word with this character prevents it from being
6722 hyphenated; putting it inside a word indicates to @code{gtroff} that
6723 the word may be hyphenated at that point. Note that this mechanism
6724 only affects that one occurrence of the word; to change the
6725 hyphenation of a word for the entire document, use the @code{hw}
6728 The @code{\:} escape inserts a zero-width break point
6729 (that is, the word breaks but without adding a hyphen).
6732 ... check the /var/log/\:httpd/\:access_log file ...
6735 @cindex @code{\X}, followed by @code{\%}
6736 @cindex @code{\Y}, followed by @code{\%}
6737 @cindex @code{\%}, following @code{\X} or @code{\Y}
6738 Note that @code{\X} and @code{\Y} start a word, that is, the @code{\%}
6739 escape in (say) @w{@samp{\X'...'\%foobar}} and
6740 @w{@samp{\Y'...'\%foobar}} no longer prevents hyphenation but inserts
6741 a hyphenation point at the beginning of @samp{foobar}; most likely
6742 this isn't what you want to do.
6745 @Defreq {hc, [@Var{char}]}
6746 Change the hyphenation character to @var{char}. This character then
6747 works the same as the @code{\%} escape, and thus, no longer appears in
6748 the output. Without an argument, @code{hc} resets the hyphenation
6749 character to be @code{\%} (the default) only.
6751 The hyphenation character is associated with the current environment
6752 (@pxref{Environments}).
6755 @DefreqList {hpf, pattern_file}
6756 @DefreqItem {hpfa, pattern_file}
6757 @DefreqListEnd {hpfcode, a b [c d @dots{}]}
6758 @cindex hyphenation patterns (@code{hpf})
6759 @cindex patterns for hyphenation (@code{hpf})
6760 Read in a file of hyphenation patterns. This file is searched for in
6761 the same way as @file{@var{name}.tmac} (or @file{tmac.@var{name}}) is
6762 searched for if the @option{-m@var{name}} option is specified.
6764 It should have the same format as (simple) @TeX{} patterns files.
6765 More specifically, the following scanning rules are implemented.
6769 A percent sign starts a comment (up to the end of the line)
6770 even if preceded by a backslash.
6773 No support for `digraphs' like @code{\$}.
6776 @code{^^@var{xx}} (@var{x} is 0-9 or a-f) and @code{^^@var{x}} (character
6777 code of @var{x} in the range 0-127) are recognized; other use of @code{^}
6784 @code{hpf} checks for the expression @code{\patterns@{@dots{}@}}
6785 (possibly with whitespace before and after the braces).
6786 Everything between the braces is taken as hyphenation patterns.
6787 Consequently, @code{@{} and @code{@}} are not allowed in patterns.
6790 Similarly, @code{\hyphenation@{@dots{}@}} gives a list of hyphenation
6794 @code{\endinput} is recognized also.
6797 For backwards compatibility, if @code{\patterns} is missing,
6798 the whole file is treated as a list of hyphenation patterns
6799 (only recognizing the @code{%} character as the start of a comment).
6802 If no @code{hpf} request is specified (either in the document or in a
6803 macro package), @code{gtroff} won't hyphenate at all.
6805 The @code{hpfa} request appends a file of patterns to the current list.
6807 The @code{hpfcode} request defines mapping values for character codes in
6808 hyphenation patterns. @code{hpf} or @code{hpfa} then apply the mapping
6809 (after reading the patterns) before replacing or appending them to
6810 the current list of patterns. Its arguments are pairs of character codes
6811 -- integers from 0 to@tie{}255. The request maps character code@tie{}@var{a}
6812 to code@tie{}@var{b}, code@tie{}@var{c} to code@tie{}@var{d}, and so on. You
6813 can use character codes which would be invalid otherwise.
6819 The set of hyphenation patterns is associated with the current language
6820 set by the @code{hla} request. The @code{hpf} request is usually
6821 invoked by the @file{troffrc} or @file{troffrc-end} file; by default,
6822 @file{troffrc} loads hyphenation patterns and exceptions for American
6823 English (in files @file{hyphen.us} and @file{hyphenex.us}).
6825 A second call to @code{hpf} (for the same language) will replace the
6826 hyphenation patterns with the new ones.
6828 Invoking @code{hpf} causes an error if there is no current hyphenation
6832 @Defreq {hcode, c1 code1 [c2 code2 @dots{}]}
6833 @cindex hyphenation code (@code{hcode})
6834 @cindex code, hyphenation (@code{hcode})
6835 Set the hyphenation code of character @var{c1} to @var{code1}, that of
6836 @var{c2} to @var{code2}, etc. A hyphenation code must be a single
6837 input character (not a special character) other than a digit or a
6840 To make hyphenation work, hyphenation codes must be set up. At
6841 start-up, groff only assigns hyphenation codes to the letters
6842 @samp{a}-@samp{z} (mapped to themselves) and to the letters
6843 @samp{A}-@samp{Z} (mapped to @samp{a}-@samp{z}); all other hyphenation
6844 codes are set to zero. Normally, hyphenation patterns contain only
6845 lowercase letters which should be applied regardless of case. With
6846 other words, the words `FOO' and `Foo' should be hyphenated exactly the
6847 same way as the word `foo' is hyphenated, and this is what @code{hcode}
6848 is good for. Words which contain other letters won't be hyphenated
6849 properly if the corresponding hyphenation patterns actually do contain
6850 them. For example, the following @code{hcode} requests are necessary to
6851 assign hyphenation codes to the letters @samp{ÄäÖöÜüß} (this is needed
6861 Without those assignments, groff treats German words like
6862 @w{`Kindergärten'} (the plural form of `kindergarten') as two
6863 substrings @w{`kinderg'} and @w{`rten'} because the hyphenation code
6864 of the umlaut@tie{}a is zero by default. There is a German
6865 hyphenation pattern which covers @w{`kinder'}, so groff finds the
6866 hyphenation `kin-der'. The other two hyphenation points
6867 (`kin-der-gär-ten') are missed.
6869 This request is ignored if it has no parameter.
6872 @DefreqList {hym, [@Var{length}]}
6873 @DefregListEnd {.hym}
6874 @cindex hyphenation margin (@code{hym})
6875 @cindex margin for hyphenation (@code{hym})
6876 @cindex @code{ad} request, and hyphenation margin
6877 Set the (right) hyphenation margin to @var{length}. If the current
6878 adjustment mode is not @samp{b} or @samp{n}, the line is not
6879 hyphenated if it is shorter than @var{length}. Without an argument,
6880 the hyphenation margin is reset to its default value, which is@tie{}0.
6881 The default scaling indicator for this request is @samp{m}. The
6882 hyphenation margin is associated with the current environment
6883 (@pxref{Environments}).
6885 A negative argument resets the hyphenation margin to zero, emitting
6886 a warning of type @samp{range}.
6888 @cindex hyphenation margin register (@code{.hym})
6889 The current hyphenation margin is available in the @code{.hym} read-only
6893 @DefreqList {hys, [@Var{hyphenation_space}]}
6894 @DefregListEnd {.hys}
6895 @cindex hyphenation space (@code{hys})
6896 @cindex @code{ad} request, and hyphenation space
6897 Set the hyphenation space to @var{hyphenation_space}. If the current
6898 adjustment mode is @samp{b} or @samp{n}, don't hyphenate the line
6899 if it can be justified by adding no more than @var{hyphenation_space}
6900 extra space to each word space. Without argument, the hyphenation
6901 space is set to its default value, which is@tie{}0. The default
6902 scaling indicator for this request is @samp{m}. The hyphenation
6903 space is associated with the current environment
6904 (@pxref{Environments}).
6906 A negative argument resets the hyphenation space to zero, emitting a
6907 warning of type @samp{range}.
6909 @cindex hyphenation space register (@code{.hys})
6910 The current hyphenation space is available in the @code{.hys} read-only
6914 @Defreq {shc, [@Var{glyph}]}
6915 @cindex soft hyphen character, setting (@code{shc})
6916 @cindex character, soft hyphen, setting (@code{shc})
6917 @cindex glyph, soft hyphen (@code{hy})
6918 @cindex soft hyphen glyph (@code{hy})
6919 @cindex @code{char} request, and soft hyphen character
6920 @cindex @code{tr} request, and soft hyphen character
6921 Set the @dfn{soft hyphen character} to @var{glyph}.@footnote{@dfn{Soft
6922 hyphen character} is a misnomer since it is an output glyph.} If the
6923 argument is omitted, the soft hyphen character is set to the default
6924 glyph @code{\(hy} (this is the start-up value of @code{gtroff} also).
6925 The soft hyphen character is the glyph that is inserted when a word is
6926 hyphenated at a line break. If the soft hyphen character does not
6927 exist in the font of the character immediately preceding a potential
6928 break point, then the line is not broken at that point. Neither
6929 definitions (specified with the @code{char} request) nor translations
6930 (specified with the @code{tr} request) are considered when finding the
6931 soft hyphen character.
6934 @DefreqList {hla, language}
6935 @DefregListEnd {.hla}
6936 @cindex @code{hpf} request, and hyphenation language
6937 @cindex @code{hw} request, and hyphenation language
6940 Set the current hyphenation language to the string @var{language}.
6941 Hyphenation exceptions specified with the @code{hw} request and
6942 hyphenation patterns specified with the @code{hpf} and @code{hpfa}
6943 requests are both associated with the current hyphenation language.
6944 The @code{hla} request is usually invoked by the @file{troffrc} or the
6945 @file{troffrc-end} files; @file{troffrc} sets the default language to
6948 @cindex hyphenation language register (@code{.hla})
6949 The current hyphenation language is available as a string in the
6950 read-only number register @samp{.hla}.
6953 .ds curr_language \n[.hla]
6960 @c =====================================================================
6962 @node Manipulating Spacing, Tabs and Fields, Manipulating Hyphenation, gtroff Reference
6963 @section Manipulating Spacing
6964 @cindex manipulating spacing
6965 @cindex spacing, manipulating
6967 @Defreq {sp, [@Var{distance}]}
6968 Space downwards @var{distance}. With no argument it advances
6969 1@tie{}line. A negative argument causes @code{gtroff} to move up the page
6970 the specified distance. If the argument is preceded by a @samp{|}
6971 then @code{gtroff} moves that distance from the top of the page. This
6972 request causes a line break. The default scaling indicator is @samp{v}.
6974 If a vertical trap is sprung during execution of @code{sp}, the amount of
6975 vertical space after the trap is discarded. For example, this
7003 @cindex @code{sp} request, and traps
7004 @cindex discarded space in traps
7005 @cindex space, discarded, in traps
7006 @cindex traps, and discarded space
7007 The amount of discarded space is available in the number register
7010 To protect @code{sp} against vertical traps, use the @code{vpt} request:
7019 @DefreqList {ls, [@Var{nnn}]}
7021 @cindex double-spacing (@code{ls})
7022 Output @w{@var{nnn}@minus{}1} blank lines after each line of text.
7023 With no argument, @code{gtroff} uses the previous value before the
7024 last @code{ls} call.
7027 .ls 2 \" This causes double-spaced output
7028 .ls 3 \" This causes triple-spaced output
7029 .ls \" Again double-spaced
7032 The line spacing is associated with the current environment
7033 (@pxref{Environments}).
7035 @cindex line spacing register (@code{.L})
7036 The read-only number register @code{.L} contains the current line
7040 @xref{Changing Type Sizes}, for the requests @code{vs} and @code{pvs}
7041 as alternatives to @code{ls}.
7043 @DefescList {\\x, ', spacing, '}
7045 Sometimes, extra vertical spacing is only needed occasionally, e.g.@:
7046 to allow space for a tall construct (like an equation). The @code{\x}
7047 escape does this. The escape is given a numerical argument, usually
7048 enclosed in quotes (like @samp{\x'3p'}); the default scaling indicator
7049 is @samp{v}. If this number is positive extra vertical space is
7050 inserted below the current line. A negative number adds space above.
7051 If this escape is used multiple times on the same line, the maximum of
7054 @xref{Escapes}, for details on parameter delimiting characters.
7056 @cindex extra post-vertical line space register (@code{.a})
7057 The @code{.a} read-only number register contains the most recent
7058 (nonnegative) extra vertical line space.
7060 Using @code{\x} can be necessary in combination with the @code{\b}
7061 escape, as the following example shows.
7064 This is a test with the \[rs]b escape.
7066 This is a test with the \[rs]b escape.
7068 This is a test with \b'xyz'\x'-1m'\x'1m'.
7070 This is a test with the \[rs]b escape.
7072 This is a test with the \[rs]b escape.
7079 This is a test with the \b escape.
7080 This is a test with the \b escape.
7082 This is a test with y.
7084 This is a test with the \b escape.
7085 This is a test with the \b escape.
7091 @DefregListEnd {.ns}
7092 @cindex @code{sp} request, and no-space mode
7093 @cindex no-space mode (@code{ns})
7094 @cindex mode, no-space (@code{ns})
7095 @cindex blank lines, disabling
7096 @cindex lines, blank, disabling
7097 Enable @dfn{no-space mode}. In this mode, spacing (either via
7098 @code{sp} or via blank lines) is disabled. The @code{bp} request to
7099 advance to the next page is also disabled, except if it is accompanied
7100 by a page number (see @ref{Page Control}, for more information). This
7101 mode ends when actual text is output or the @code{rs} request is
7102 encountered which ends no-space mode. The read-only number register
7103 @code{.ns} is set to@tie{}1 as long as no-space mode is active.
7105 This request is useful for macros that conditionally
7106 insert vertical space before the text starts
7107 (for example, a paragraph macro could insert some space
7108 except when it is the first paragraph after a section header).
7112 @c =====================================================================
7114 @node Tabs and Fields, Character Translations, Manipulating Spacing, gtroff Reference
7115 @section Tabs and Fields
7116 @cindex tabs, and fields
7117 @cindex fields, and tabs
7119 @cindex @acronym{EBCDIC} encoding of a tab
7120 A tab character (@acronym{ASCII} char@tie{}9, @acronym{EBCDIC}
7121 char@tie{}5) causes a horizontal movement to the next tab stop (much
7122 like it did on a typewriter).
7125 @cindex tab character, non-interpreted (@code{\t})
7126 @cindex character, tab, non-interpreted (@code{\t})
7127 This escape is a non-interpreted tab character. In copy mode
7128 (@pxref{Copy-in Mode}), @code{\t} is the same as a real tab character.
7131 @DefreqList {ta, [@Var{n1} @Var{n2} @dots{} @Var{nn} @t{T} @Var{r1} @Var{r2} @dots{} @Var{rn}]}
7132 @DefregListEnd {.tabs}
7133 Change tab stop positions. This request takes a series of tab
7134 specifiers as arguments (optionally divided into two groups with the
7135 letter @samp{T}) which indicate where each tab stop is to be
7136 (overriding any previous settings).
7138 Tab stops can be specified absolutely, i.e., as the distance from the
7139 left margin. For example, the following sets 6@tie{}tab stops every
7143 .ta 1i 2i 3i 4i 5i 6i
7146 Tab stops can also be specified using a leading @samp{+}
7147 which means that the specified tab stop is set relative to
7148 the previous tab stop. For example, the following is equivalent to the
7152 .ta 1i +1i +1i +1i +1i +1i
7155 @code{gtroff} supports an extended syntax to specify repeat values after
7156 the @samp{T} mark (these values are always taken as relative) -- this is
7157 the usual way to specify tabs set at equal intervals. The following is,
7158 yet again, the same as the previous examples. It does even more since
7159 it defines an infinite number of tab stops separated by one inch.
7165 Now we are ready to interpret the full syntax given at the beginning:
7166 Set tabs at positions @var{n1}, @var{n2}, @dots{}, @var{nn} and then set
7167 tabs at @var{nn}+@var{r1}, @var{nn}+@var{r2}, @dots{}, @var{nn}+@var{rn}
7168 and then at @var{nn}+@var{rn}+@var{r1}, @var{nn}+@var{rn}+@var{r2},
7169 @dots{}, @var{nn}+@var{rn}+@var{rn}, and so on.
7171 Example: @samp{4c +6c T 3c 5c 2c} is equivalent to @samp{4c 10c 13c 18c
7172 20c 23c 28c 30c @dots{}}.
7174 The material in each tab column (i.e., the column between two tab stops)
7175 may be justified to the right or left or centered in the column. This
7176 is specified by appending @samp{R}, @samp{L}, or @samp{C} to the tab
7177 specifier. The default justification is @samp{L}. Example:
7187 The default unit of the @code{ta} request is @samp{m}.
7190 A tab stop is converted into a non-breakable horizontal movement which
7191 can be neither stretched nor squeezed. For example,
7200 creates a single line which is a bit longer than 10@tie{}inches (a string
7201 is used to show exactly where the tab characters are). Now consider the
7211 @code{gtroff} first converts the tab stops of the line into unbreakable
7212 horizontal movements, then splits the line after the second @samp{b}
7213 (assuming a sufficiently short line length). Usually, this isn't what
7217 Superfluous tabs (i.e., tab characters which do not correspond to a tab
7218 stop) are ignored except the first one which delimits the characters
7219 belonging to the last tab stop for right-justifying or centering.
7220 Consider the following example
7224 .ds ZZ foo\tbar\tfoobar
7225 .ds ZZZ foo\tbar\tfoo\tbar
7236 which produces the following output:
7245 The first line right-justifies the second `foo' relative to the tab
7246 stop. The second line right-justifies `foobar'. The third line finally
7247 right-justifies only `foo' because of the additional tab character which
7248 marks the end of the string belonging to the last defined tab stop.
7251 Tab stops are associated with the current environment
7252 (@pxref{Environments}).
7255 Calling @code{ta} without an argument removes all tab stops.
7258 @cindex tab stops, for TTY output devices
7259 The start-up value of @code{gtroff} is @w{@samp{T 0.8i}}.
7262 @cindex tab settings register (@code{.tabs})
7263 The read-only number register @code{.tabs} contains a string
7264 representation of the current tab settings suitable for use as an
7265 argument to the @code{ta} request.
7268 .ds tab-string \n[.tabs]
7273 @cindex @code{.S} register, Plan@tie{}9 alias for @code{.tabs}
7274 @cindex @code{.tabs} register, Plan@tie{}9 alias (@code{.S})
7275 The @code{troff} version of the Plan@tie{}9 operating system uses
7276 register @code{.S} for the same purpose.
7279 @Defreq {tc, [@Var{fill-glyph}]}
7280 @cindex tab repetition character (@code{tc})
7281 @cindex character, tab repetition (@code{tc})
7282 @cindex glyph, tab repetition (@code{tc})
7283 Normally @code{gtroff} fills the space to the next tab stop with
7284 whitespace. This can be changed with the @code{tc} request. With no
7285 argument @code{gtroff} reverts to using whitespace, which is the
7286 default. The value of this @dfn{tab repetition character} is
7287 associated with the current environment
7288 (@pxref{Environments}).@footnote{@dfn{Tab repetition character} is a
7289 misnomer since it is an output glyph.}
7292 @DefreqList {linetabs, n}
7293 @DefregListEnd {.linetabs}
7294 @cindex tab, line-tabs mode
7295 @cindex line-tabs mode
7296 @cindex mode, line-tabs
7297 If @var{n} is missing or not zero, enable @dfn{line-tabs} mode,
7298 or disable it otherwise (the default).
7299 In line-tabs mode, @code{gtroff} computes tab distances
7300 relative to the (current) output line instead of the input line.
7302 For example, the following code:
7315 in normal mode, results in the output
7322 in line-tabs mode, the same code outputs
7328 Line-tabs mode is associated with the current environment.
7329 The read-only register @code{.linetabs} is set to@tie{}1 if in line-tabs
7330 mode, and 0 in normal mode.
7338 @c ---------------------------------------------------------------------
7340 @node Leaders, Fields, Tabs and Fields, Tabs and Fields
7344 Sometimes it may may be desirable to use the @code{tc} request to fill a
7345 particular tab stop with a given glyph (for example dots in a table
7346 of contents), but also normal tab stops on the rest of the line. For
7347 this @code{gtroff} provides an alternate tab mechanism, called
7348 @dfn{leaders} which does just that.
7350 @cindex leader character
7351 A leader character (character code@tie{}1) behaves similarly to a tab
7352 character: It moves to the next tab stop. The only difference is that
7353 for this movement, the fill glyph defaults to a period character and
7357 @cindex leader character, non-interpreted (@code{\a})
7358 @cindex character, leader, non-interpreted (@code{\a})
7359 This escape is a non-interpreted leader character. In copy mode
7360 (@pxref{Copy-in Mode}), @code{\a} is the same as a real leader
7364 @Defreq {lc, [@Var{fill-glyph}]}
7365 @cindex leader repetition character (@code{lc})
7366 @cindex character, leader repetition (@code{lc})
7367 @cindex glyph, leader repetition (@code{lc})
7368 Declare the @dfn{leader repetition character}.@footnote{@dfn{Leader
7369 repetition character} is a misnomer since it is an output glyph.}
7370 Without an argument, leaders act the same as tabs (i.e., using
7371 whitespace for filling). @code{gtroff}'s start-up value is a dot
7372 (@samp{.}). The value of the leader repetition character is
7373 associated with the current environment (@pxref{Environments}).
7376 @cindex table of contents
7377 @cindex contents, table of
7378 For a table of contents, to name an example, tab stops may be defined so
7379 that the section number is one tab stop, the title is the second with
7380 the remaining space being filled with a line of dots, and then the page
7381 number slightly separated from the dots.
7384 .ds entry 1.1\tFoo\a\t12
7394 1.1 Foo.......................................... 12
7397 @c ---------------------------------------------------------------------
7399 @node Fields, , Leaders, Tabs and Fields
7403 @cindex field delimiting character (@code{fc})
7404 @cindex delimiting character, for fields (@code{fc})
7405 @cindex character, field delimiting (@code{fc})
7406 @cindex field padding character (@code{fc})
7407 @cindex padding character, for fields (@code{fc})
7408 @cindex character, field padding (@code{fc})
7409 @dfn{Fields} are a more general way of laying out tabular data. A field
7410 is defined as the data between a pair of @dfn{delimiting characters}.
7411 It contains substrings which are separated by @dfn{padding characters}.
7412 The width of a field is the distance on the @emph{input} line from the
7413 position where the field starts to the next tab stop. A padding
7414 character inserts stretchable space similar to @TeX{}'s @code{\hss}
7415 command (thus it can even be negative) to make the sum of all substring
7416 lengths plus the stretchable space equal to the field width. If more
7417 than one padding character is inserted, the available space is evenly
7418 distributed among them.
7420 @Defreq {fc, [@Var{delim-char} [@Var{padding-char}]]}
7421 Define a delimiting and a padding character for fields. If the latter
7422 is missing, the padding character defaults to a space character. If
7423 there is no argument at all, the field mechanism is disabled (which is
7424 the default). Note that contrary to e.g.@: the tab repetition
7425 character, delimiting and padding characters are @emph{not} associated
7426 to the current environment (@pxref{Environments}).
7439 and here the result:
7448 @c =====================================================================
7450 @node Character Translations, Troff and Nroff Mode, Tabs and Fields, gtroff Reference
7451 @section Character Translations
7452 @cindex character translations
7453 @cindex translations of characters
7455 @cindex control character, changing (@code{cc})
7456 @cindex character, control, changing (@code{cc})
7457 @cindex no-break control character, changing (@code{c2})
7458 @cindex character, no-break control, changing (@code{c2})
7459 @cindex control character, no-break, changing (@code{c2})
7460 The control character (@samp{.}) and the no-break control character
7461 (@samp{'}) can be changed with the @code{cc} and @code{c2} requests,
7464 @Defreq {cc, [@Var{c}]}
7465 Set the control character to@tie{}@var{c}. With no argument the default
7466 control character @samp{.} is restored. The value of the control
7467 character is associated with the current environment
7468 (@pxref{Environments}).
7471 @Defreq {c2, [@Var{c}]}
7472 Set the no-break control character to@tie{}@var{c}. With no argument the
7473 default control character @samp{'} is restored. The value of the
7474 no-break control character is associated with the current environment
7475 (@pxref{Environments}).
7479 @cindex disabling @code{\} (@code{eo})
7480 @cindex @code{\}, disabling (@code{eo})
7481 Disable the escape mechanism completely. After executing this
7482 request, the backslash character @samp{\} no longer starts an escape
7485 This request can be very helpful in writing macros since it is not
7486 necessary then to double the escape character. Here an example:
7489 .\" This is a simplified version of the
7490 .\" .BR request from the man macro package
7494 . while (\n[.$] >= 2) \@{\
7495 . as result \fB\$1\fR\$2
7498 . if \n[.$] .as result \fB\$1
7506 @Defreq {ec, [@Var{c}]}
7507 @cindex escape character, changing (@code{ec})
7508 @cindex character, escape, changing (@code{ec})
7509 Set the escape character to@tie{}@var{c}. With no argument the default
7510 escape character @samp{\} is restored. It can be also used to
7511 re-enable the escape mechanism after an @code{eo} request.
7513 Note that changing the escape character globally will likely break
7514 macro packages since @code{gtroff} has no mechanism to `intern' macros,
7515 i.e., to convert a macro definition into an internal form which is
7516 independent of its representation (@TeX{} has this mechanism).
7517 If a macro is called, it is executed literally.
7521 @DefreqListEnd {ecr, }
7522 The @code{ecs} request saves the current escape character
7523 in an internal register.
7524 Use this request in combination with the @code{ec} request to
7525 temporarily change the escape character.
7527 The @code{ecr} request restores the escape character
7528 saved with @code{ecs}.
7529 Without a previous call to @code{ecs}, this request
7530 sets the escape character to @code{\}.
7533 @DefescList {\\\\, , , }
7534 @DefescItem {\\e, , , }
7535 @DefescListEnd {\\E, , , }
7536 Print the current escape character (which is the backslash character
7537 @samp{\} by default).
7539 @code{\\} is a `delayed' backslash; more precisely, it is the default
7540 escape character followed by a backslash, which no longer has special
7541 meaning due to the leading escape character. It is @emph{not} an escape
7542 sequence in the usual sense! In any unknown escape sequence
7543 @code{\@var{X}} the escape character is ignored and @var{X} is printed.
7544 But if @var{X} is equal to the current escape character, no warning is
7547 As a consequence, only at top-level or in a diversion a backslash glyph is
7548 printed; in copy-in mode, it expands to a single backslash which then
7549 combines with the following character to an escape sequence.
7551 The @code{\E} escape differs from @code{\e} by printing an escape
7552 character that is not interpreted in copy mode.
7553 Use this to define strings with escapes that work
7554 when used in copy mode (for example, as a macro argument).
7555 The following example defines strings to begin and end
7559 .ds @{ \v'-.3m'\s'\En[.s]*60/100'
7563 Another example to demonstrate the differences between the various escape
7564 sequences, using a strange escape character, @samp{-}.
7576 The result is surprising for most users, expecting @samp{1} since
7577 @samp{foo} is a valid identifier. What has happened? As mentioned
7578 above, the leading escape character makes the following character
7579 ordinary. Written with the default escape character the sequence
7580 @samp{--} becomes @samp{\-} -- this is the minus sign.
7582 If the escape character followed by itself is a valid escape sequence,
7583 only @code{\E} yields the expected result:
7596 Similar to @code{\\}, the sequence @code{\.} isn't a real escape sequence.
7597 As before, a warning message is suppressed if the escape character is
7598 followed by a dot, and the dot itself is printed.
7615 The first backslash is consumed while the macro is read, and the second
7616 is swallowed while exexuting macro @code{foo}.
7619 A @dfn{translation} is a mapping of an input character to an output
7620 glyph. The mapping occurs at output time, i.e., the input character
7621 gets assigned the metric information of the mapped output character
7622 right before input tokens are converted to nodes (@pxref{Gtroff
7623 Internals}, for more on this process).
7625 @DefreqList {tr, @Var{a}@Var{b}@Var{c}@Var{d}@dots{}}
7626 @DefreqListEnd {trin, @Var{a}@Var{b}@Var{c}@Var{d}@dots{}}
7627 Translate character @var{a} to glyph@tie{}@var{b}, character @var{c} to
7628 glyph@tie{}@var{d}, etc. If there is an odd number of arguments, the
7629 last one is translated to an unstretchable space (@w{@samp{\ }}).
7631 The @code{trin} request is identical to @code{tr},
7632 but when you unformat a diversion with @code{asciify}
7633 it ignores the translation.
7634 @xref{Diversions}, for details about the @code{asciify} request.
7640 @cindex @code{\(}, and translations
7641 @cindex @code{\[}, and translations
7642 @cindex @code{\'}, and translations
7643 @cindex @code{\`}, and translations
7644 @cindex @code{\-}, and translations
7645 @cindex @code{\_}, and translations
7646 @cindex @code{\C}, and translations
7647 @cindex @code{\N}, and translations
7648 @cindex @code{char} request, and translations
7649 @cindex special characters
7650 @cindex character, special
7651 @cindex numbered glyph (@code{\N})
7652 @cindex glyph, numbered (@code{\N})
7653 Special characters (@code{\(@var{xx}}, @code{\[@var{xxx}]},
7654 @code{\C'@var{xxx}'}, @code{\'}, @code{\`}, @code{\-}, @code{\_}),
7655 glyphs defined with the @code{char} request, and numbered glyphs
7656 (@code{\N'@var{xxx}'}) can be translated also.
7659 @cindex @code{\e}, and translations
7660 The @code{\e} escape can be translated also.
7663 @cindex @code{\%}, and translations
7664 @cindex @code{\~}, and translations
7665 Characters can be mapped onto the @code{\%} and @code{\~} escapes (but
7666 @code{\%} and @code{\~} can't be mapped onto another glyph).
7669 @cindex backspace character, and translations
7670 @cindex character, backspace, and translations
7671 @cindex leader character, and translations
7672 @cindex character, leader, and translations
7673 @cindex newline character, and translations
7674 @cindex character, newline, and translations
7675 @cindex tab character, and translations
7676 @cindex character, tab, and translations
7677 @cindex @code{\a}, and translations
7678 @cindex @code{\t}, and translations
7679 The following characters can't be translated: space (with one exception,
7680 see below), backspace, newline, leader (and @code{\a}), tab (and
7684 @cindex @code{shc} request, and translations
7685 Translations are not considered for finding the soft hyphen character
7686 set with the @code{shc} request.
7689 @cindex @code{\&}, and translations
7690 The pair @samp{@var{c}\&} (this is an arbitrary character@tie{}@var{c}
7691 followed by the zero width space character) maps this character to nothing.
7700 It is even possible to map the space character to nothing:
7709 As shown in the example, the space character can't be the first
7710 character/glyph pair as an argument of @code{tr}. Additionally, it is
7711 not possible to map the space character to any other glyph; requests
7712 like @w{@samp{.tr aa x}} undo @w{@samp{.tr aa \&}} instead.
7714 If justification is active, lines are justified in spite of the
7715 `empty' space character (but there is no minimal distance, i.e.@: the
7716 space character, between words).
7719 After an output glyph has been constructed (this happens at the
7720 moment immediately before the glyph is appended to an output
7721 glyph list, either by direct output, in a macro, diversion, or
7722 string), it is no longer affected by @code{tr}.
7725 Translating character to glyphs where one of them or both are
7726 undefined is possible also; @code{tr} does not check whether the
7727 entities in its argument do exist.
7729 @xref{Gtroff Internals}.
7732 @code{troff} no longer has a hard-coded dependency on @w{Latin-1};
7733 all @code{char@var{XXX}} entities have been removed from the font
7734 description files. This has a notable consequence which shows up in
7735 warnings like @code{can't find character with input code @var{XXX}}
7736 if the @code{tr} request isn't handled properly.
7738 Consider the following translation:
7745 This maps input character @code{é} onto glyph @code{É}, which is
7746 identical to glyph @code{char201}. But this glyph intentionally
7747 doesn't exist! Instead, @code{\[char201]} is treated as an input
7748 character entity and is by default mapped onto @code{\['E]}, and
7749 @code{gtroff} doesn't handle translations of translations.
7751 The right way to write the above translation is
7758 With other words, the first argument of @code{tr} should be an input
7759 character or entity, and the second one a glyph entity.
7762 Without an argument, the @code{tr} request is ignored.
7766 @Defreq {trnt, @Var{a}@Var{b}@Var{c}@Var{d}@dots{}}
7767 @cindex @code{\!}, and @code{trnt}
7768 @code{trnt} is the same as the @code{tr} request except that the
7769 translations do not apply to text that is transparently throughput
7770 into a diversion with @code{\!}. @xref{Diversions}, for more
7784 prints @samp{b} to the standard error stream; if @code{trnt} is used
7785 instead of @code{tr} it prints @samp{a}.
7789 @c =====================================================================
7791 @node Troff and Nroff Mode, Line Layout, Character Translations, gtroff Reference
7792 @section Troff and Nroff Mode
7798 Originally, @code{nroff} and @code{troff} were two separate programs,
7799 the former for TTY output, the latter for everything else. With GNU
7800 @code{troff}, both programs are merged into one executable, sending
7801 its output to a device driver (@code{grotty} for TTY devices,
7802 @code{grops} for @sc{PostScript}, etc.) which interprets the
7803 intermediate output of @code{gtroff}. For @acronym{UNIX} @code{troff}
7804 it makes sense to talk about @dfn{Nroff mode} and @dfn{Troff mode}
7805 since the differences are hardcoded. For GNU @code{troff}, this
7806 distinction is not appropriate because @code{gtroff} simply takes the
7807 information given in the font files for a particular device without
7808 handling requests specially if a TTY output device is used.
7810 Usually, a macro package can be used with all output devices.
7811 Nevertheless, it is sometimes necessary to make a distinction between
7812 TTY and non-TTY devices: @code{gtroff} provides two built-in
7813 conditions @samp{n} and @samp{t} for the @code{if}, @code{ie}, and
7814 @code{while} requests to decide whether @code{gtroff} shall behave
7815 like @code{nroff} or like @code{troff}.
7820 Make the @samp{t} built-in condition true (and the @samp{n} built-in
7821 condition false) for @code{if}, @code{ie}, and @code{while}
7822 conditional requests. This is the default if @code{gtroff}
7823 (@emph{not} @code{groff}) is started with the @option{-R} switch to
7824 avoid loading of the start-up files @file{troffrc} and
7825 @file{troffrc-end}. Without @option{-R}, @code{gtroff} stays in troff
7826 mode if the output device is not a TTY (e.g.@: `ps').
7831 Make the @samp{n} built-in condition true (and the @samp{t} built-in
7832 condition false) for @code{if}, @code{ie}, and @code{while}
7833 conditional requests. This is the default if @code{gtroff} uses a TTY
7834 output device; the code for switching to nroff mode is in the file
7835 @file{tty.tmac} which is loaded by the start-up file @code{troffrc}.
7838 @xref{Conditionals and Loops}, for more details on built-in
7842 @c =====================================================================
7844 @node Line Layout, Line Control, Troff and Nroff Mode, gtroff Reference
7845 @section Line Layout
7847 @cindex layout, line
7849 @cindex dimensions, line
7850 @cindex line dimensions
7851 The following drawing shows the dimensions which @code{gtroff} uses for
7852 placing a line of output onto the page. They are labeled with the
7853 request which manipulates each dimension.
7857 |<-----------ll------------>|
7858 +----+----+----------------------+----+
7860 +----+----+----------------------+----+
7862 |<--------paper width---------------->|
7866 These dimensions are:
7870 @cindex left margin (@code{po})
7871 @cindex margin, left (@code{po})
7872 @cindex page offset (@code{po})
7873 @cindex offset, page (@code{po})
7874 @dfn{Page offset} -- this is the leftmost position of text on the final
7875 output, defining the @dfn{left margin}.
7878 @cindex indentation (@code{in})
7879 @cindex line indentation (@code{in})
7880 @dfn{Indentation} -- this is the distance from the left margin where
7884 @cindex line length (@code{ll})
7885 @cindex length of line (@code{ll})
7886 @dfn{Line length} -- this is the distance from the left margin to right
7890 A simple demonstration:
7894 This is text without indentation.
7895 The line length has been set to 3\~inch.
7898 Now the left and right margins are both increased.
7901 Calling .in and .ll without parameters restore
7902 the previous values.
7908 This is text without indenta-
7909 tion. The line length has
7914 Calling .in and .ll without
7915 parameters restore the previ-
7919 @DefreqList {po, [@Var{offset}]}
7920 @DefreqItem {po, @t{+}@Var{offset}}
7921 @DefreqItem {po, @t{-}@Var{offset}}
7924 Set horizontal page offset to @var{offset} (or increment or decrement
7925 the current value by @var{offset}). Note that this request does not
7926 cause a break, so changing the page offset in the middle of text being
7927 filled may not yield the expected result. The initial value is
7928 1@dmn{i}. For TTY output devices, it is set to 0 in the startup file
7929 @file{troffrc}; the default scaling indicator is @samp{m} (and
7930 not @samp{v} as incorrectly documented in the original
7931 @acronym{UNIX} troff manual).
7933 The current page offset can be found in the read-only number register
7936 If @code{po} is called without an argument, the page offset is reset to
7937 the previous value before the last call to @code{po}.
7952 @DefreqList {in, [@Var{indent}]}
7953 @DefreqItem {in, @t{+}@Var{indent}}
7954 @DefreqItem {in, @t{-}@Var{indent}}
7956 Set indentation to @var{indent} (or increment or decrement the
7957 current value by @var{indent}). This request causes a break.
7958 Initially, there is no indentation.
7960 If @code{in} is called without an argument, the indentation is reset to
7961 the previous value before the last call to @code{in}. The default
7962 scaling indicator is @samp{m}.
7964 The indentation is associated with the current environment
7965 (@pxref{Environments}).
7967 If a negative indentation value is specified (which is not allowed),
7968 @code{gtroff} emits a warning of type @samp{range} and sets the
7969 indentation to zero.
7971 The effect of @code{in} is delayed until a partially collected line (if
7972 it exists) is output. A temporary indent value is reset to zero also.
7974 The current indentation (as set by @code{in}) can be found in the
7975 read-only number register @samp{.i}.
7978 @DefreqList {ti, offset}
7979 @DefreqItem {ti, @t{+}@Var{offset}}
7980 @DefreqItem {ti, @t{-}@Var{offset}}
7981 @DefregListEnd {.in}
7982 Temporarily indent the next output line by @var{offset}. If an
7983 increment or decrement value is specified, adjust the temporary
7984 indentation relative to the value set by the @code{in} request.
7986 This request causes a break; its value is associated with the current
7987 environment (@pxref{Environments}). The default scaling indicator
7988 is @samp{m}. A call of @code{ti} without an argument is ignored.
7990 If the total indentation value is negative (which is not allowed),
7991 @code{gtroff} emits a warning of type @samp{range} and sets the
7992 temporary indentation to zero. `Total indentation' is either
7993 @var{offset} if specified as an absolute value, or the temporary plus
7994 normal indentation, if @var{offset} is given as a relative value.
7996 The effect of @code{ti} is delayed until a partially collected line (if
7997 it exists) is output.
7999 The read-only number register @code{.in} is the indentation that applies
8000 to the current output line.
8002 The difference between @code{.i} and @code{.in} is that the latter takes
8003 into account whether a partially collected line still uses the old
8004 indentation value or a temporary indentation value is active.
8007 @DefreqList {ll, [@Var{length}]}
8008 @DefreqItem {ll, @t{+}@Var{length}}
8009 @DefreqItem {ll, @t{-}@Var{length}}
8011 @DefregListEnd {.ll}
8012 Set the line length to @var{length} (or increment or decrement the
8013 current value by @var{length}). Initially, the line length is set to
8014 6.5@dmn{i}. The effect of @code{ll} is delayed until a partially
8015 collected line (if it exists) is output. The default scaling
8016 indicator is @samp{m}.
8018 If @code{ll} is called without an argument, the line length is reset to
8019 the previous value before the last call to @code{ll}. If a negative
8020 line length is specified (which is not allowed), @code{gtroff} emits a
8021 warning of type @samp{range} and sets the line length to zero.
8023 The line length is associated with the current environment
8024 (@pxref{Environments}).
8026 @cindex line length register (@code{.l})
8027 The current line length (as set by @code{ll}) can be found in the
8028 read-only number register @samp{.l}. The read-only number register
8029 @code{.ll} is the line length that applies to the current output line.
8031 Similar to @code{.i} and @code{.in}, the difference between @code{.l}
8032 and @code{.ll} is that the latter takes into account whether a partially
8033 collected line still uses the old line length value.
8037 @c =====================================================================
8039 @node Line Control, Page Layout, Line Layout, gtroff Reference
8040 @section Line Control
8041 @cindex line control
8042 @cindex control, line
8044 It is important to understand how @code{gtroff} handles input and output
8047 Many escapes use positioning relative to the input line. For example,
8051 This is a \h'|1.2i'test.
8066 The main usage of this feature is to define macros which act exactly
8067 at the place where called.
8070 .\" A simple macro to underline a word
8072 . nop \\$1\l'|0\[ul]'
8077 In the above example, @samp{|0} specifies a negative distance from the
8078 current position (at the end of the just emitted argument @code{\$1}) back
8079 to the beginning of the input line. Thus, the @samp{\l} escape draws a
8080 line from right to left.
8082 @cindex input line continuation (@code{\})
8083 @cindex line, input, continuation (@code{\})
8084 @cindex continuation, input line (@code{\})
8085 @cindex output line, continuation (@code{\c})
8086 @cindex line, output, continuation (@code{\c})
8087 @cindex continuation, output line (@code{\c})
8088 @cindex interrupted line
8089 @cindex line, interrupted
8090 @code{gtroff} makes a difference between input and output line
8091 continuation; the latter is also called @dfn{interrupting} a line.
8093 @DefescList {\\@key{RET}, , ,}
8094 @DefescItem {\\c, , ,}
8095 @DefregListEnd{.int}
8096 Continue a line. @code{\@key{RET}} (this is a backslash at the end
8097 of a line immediately followed by a newline) works on the input level,
8098 suppressing the effects of the following newline in the input.
8103 @result{} This is a .test
8106 The @samp{|} operator is also affected.
8108 @cindex @code{\R}, after @code{\c}
8109 @code{\c} works on the output level. Anything after this escape on the
8110 same line is ignored, except @code{\R} which works as usual. Anything
8111 before @code{\c} on the same line will be appended to the current partial
8112 output line. The next non-command line after an interrupted line counts
8113 as a new input line.
8115 The visual results depend on whether no-fill mode is active.
8119 @cindex @code{\c}, and no-fill mode
8120 @cindex no-fill mode, and @code{\c}
8121 @cindex mode, no-fill, and @code{\c}
8122 If no-fill mode is active (using the @code{nf} request), the next input
8123 text line after @code{\c} will be handled as a continuation of the same
8130 @result{} This is a test.
8134 @cindex @code{\c}, and fill mode
8135 @cindex fill mode, and @code{\c}
8136 @cindex mode, fill, and @code{\c}
8137 If fill mode is active (using the @code{fi} request), a word interrupted
8138 with @code{\c} will be continued with the text on the next input text line,
8139 without an intervening space.
8144 @result{} This is a test.
8148 Note that an intervening control line which causes a break is stronger
8149 than @code{\c}, flushing out the current partial line in the usual way.
8151 @cindex interrupted line register (@code{.int})
8152 The @code{.int} register contains a positive value
8153 if the last output line was interrupted with @code{\c}; this is
8154 associated with the current environment (@pxref{Environments}).
8157 @c =====================================================================
8159 @node Page Layout, Page Control, Line Control, gtroff Reference
8160 @section Page Layout
8162 @cindex layout, page
8164 @code{gtroff} provides some very primitive operations for controlling
8167 @DefreqList {pl, [@Var{length}]}
8168 @DefreqItem {pl, @t{+}@Var{length}}
8169 @DefreqItem {pl, @t{-}@Var{length}}
8171 @cindex page length (@code{pl})
8172 @cindex length of page (@code{pl})
8173 Set the @dfn{page length} to @var{length} (or increment or decrement
8174 the current value by @var{length}). This is the length of the
8175 physical output page. The default scaling indicator is @samp{v}.
8177 @cindex page length register (@code{.p})
8178 The current setting can be found in the read-only number register
8183 @cindex bottom margin
8184 @cindex margin, bottom
8185 Note that this only specifies the size of the page, not the top and
8186 bottom margins. Those are not set by @code{gtroff} directly.
8187 @xref{Traps}, for further information on how to do this.
8189 Negative @code{pl} values are possible also, but not very useful: No
8190 trap is sprung, and each line is output on a single page (thus
8191 suppressing all vertical spacing).
8193 If no argument or an invalid argument is given, @code{pl} sets the page
8194 length to 11@dmn{i}.
8200 @code{gtroff} provides several operations which help in setting up top
8201 and bottom titles (or headers and footers).
8203 @Defreq {tl, @t{'}@Var{left}@t{'}@Var{center}@t{'}@Var{right}@t{'}}
8204 @cindex title line (@code{tl})
8205 @cindex three-part title (@code{tl})
8206 @cindex page number character (@code{%})
8207 Print a @dfn{title line}. It consists of three parts: a left
8208 justified portion, a centered portion, and a right justified portion.
8209 The argument separator @samp{'} can be replaced with any character not
8210 occurring in the title line. The @samp{%} character is replaced with
8211 the current page number. This character can be changed with the
8212 @code{pc} request (see below).
8214 Without argument, @code{tl} is ignored.
8220 A title line is not restricted to the top or bottom of a page.
8223 @code{tl} prints the title line immediately, ignoring a partially filled
8224 line (which stays untouched).
8227 It is not an error to omit closing delimiters. For example,
8228 @w{@samp{.tl /foo}} is equivalent to @w{@samp{.tl /foo///}}: It prints a
8229 title line with the left justified word @samp{foo}; the centered and
8230 right justfied parts are empty.
8233 @code{tl} accepts the same parameter delimiting characters as the
8234 @code{\A} escape; see @ref{Escapes}.
8238 @DefreqList {lt, [@Var{length}]}
8239 @DefreqItem {lt, @t{+}@Var{length}}
8240 @DefreqItem {lt, @t{-}@Var{length}}
8241 @DefregListEnd {.lt}
8242 @cindex length of title line (@code{lt})
8243 @cindex title line, length (@code{lt})
8244 @cindex title line length register (@code{.lt})
8245 The title line is printed using its own line length, which is
8246 specified (or incremented or decremented) with the @code{lt} request.
8247 Initially, the title line length is set to 6.5@dmn{i}. If a negative
8248 line length is specified (which is not allowed), @code{gtroff} emits a
8249 warning of type @samp{range} and sets the title line length to zero.
8250 The default scaling indicator is @samp{m}. If @code{lt} is called
8251 without an argument, the title length is reset to the previous value
8252 before the last call to @code{lt}.
8254 The current setting of this is available in the @code{.lt} read-only
8255 number register; it is associated with the current environment
8256 (@pxref{Environments}).
8259 @DefreqList {pn, page}
8260 @DefreqItem {pn, @t{+}@Var{page}}
8261 @DefreqItem {pn, @t{-}@Var{page}}
8262 @DefregListEnd {.pn}
8263 @cindex page number (@code{pn})
8264 @cindex number, page (@code{pn})
8265 Change (increase or decrease) the page number of the @emph{next} page.
8266 The only argument is the page number; the request is ignored without a
8269 The read-only number register @code{.pn} contains the number of the next
8270 page: either the value set by a @code{pn} request, or the number of the
8271 current page plus@tie{}1.
8274 @Defreq {pc, [@Var{char}]}
8275 @cindex changing the page number character (@code{pc})
8276 @cindex page number character, changing (@code{pc})
8278 Change the page number character (used by the @code{tl} request) to a
8279 different character. With no argument, this mechanism is disabled.
8280 Note that this doesn't affect the number register@tie{}@code{%}.
8286 @c =====================================================================
8288 @node Page Control, Fonts and Symbols, Page Layout, gtroff Reference
8289 @section Page Control
8290 @cindex page control
8291 @cindex control, page
8293 @DefreqList {bp, [@Var{page}]}
8294 @DefreqItem {bp, @t{+}@Var{page}}
8295 @DefreqItem {bp, @t{-}@Var{page}}
8297 @cindex new page (@code{bp})
8298 @cindex page, new (@code{bp})
8299 Stop processing the current page and move to the next page. This
8300 request causes a break. It can also take an argument to set
8301 (increase, decrease) the page number of the next page (which actually
8302 becomes the current page after @code{bp} has finished). The
8303 difference between @code{bp} and @code{pn} is that @code{pn} does not
8304 cause a break or actually eject a page. @xref{Page Layout}.
8307 .de newpage \" define macro
8309 'sp .5i \" vertical space
8310 .tl 'left top'center top'right top' \" title
8311 'sp .3i \" vertical space
8315 @cindex @code{bp} request, and top-level diversion
8316 @cindex top-level diversion, and @code{bp}
8317 @cindex diversion, top-level, and @code{bp}
8318 @code{bp} has no effect if not called within the top-level diversion
8319 (@pxref{Diversions}).
8321 @cindex page number register (@code{%})
8322 @cindex current page number (@code{%})
8323 The read-write register@tie{}@code{%} holds the current page number.
8325 The number register @code{.pe} is set to@tie{}1 while @code{bp} is
8326 active. @xref{Page Location Traps}.
8329 @Defreq {ne, [@Var{space}]}
8330 @cindex orphan lines, preventing with @code{ne}
8331 @cindex conditional page break (@code{ne})
8332 @cindex page break, conditional (@code{ne})
8333 It is often necessary to force a certain amount of space before a new
8334 page occurs. This is most useful to make sure that there is not a
8335 single @dfn{orphan} line left at the bottom of a page. The @code{ne}
8336 request ensures that there is a certain distance, specified by the
8337 first argument, before the next page is triggered (see @ref{Traps},
8338 for further information). The default scaling indicator for @code{ne}
8339 is @samp{v}; the default value of @var{space} is@tie{}1@dmn{v} if no
8342 For example, to make sure that no fewer than 2@tie{}lines get orphaned,
8343 do the following before each paragraph:
8350 @code{ne} will then automatically cause a page break if there is space
8354 @DefreqList {sv, [@Var{space}]}
8355 @DefreqListEnd {os, }
8356 @cindex @code{ne} request, comparison with @code{sv}
8357 @code{sv} is similar to the @code{ne} request; it reserves the
8358 specified amount of vertical space. If the desired amount of space
8359 exists before the next trap (or the bottom page boundary if no trap is
8360 set), the space is output immediately (ignoring a partially filled line
8361 which stays untouched). If there is not enough space, it is stored for
8362 later output via the @code{os} request. The default value is@tie{}1@dmn{v}
8363 if no argument is given; the default scaling indicator is @samp{v}.
8365 @cindex @code{sv} request, and no-space mode
8366 @cindex @code{os} request, and no-space mode
8367 Both @code{sv} and @code{os} ignore no-space mode. While the @code{sv}
8368 request allows negative values for @var{space}, @code{os} will ignore
8373 @cindex current vertical position (@code{nl})
8374 @cindex vertical position, current (@code{nl})
8375 @cindex position, vertical, current (@code{nl})
8376 This register contains the current vertical position. If the vertical
8377 position is zero and the top of page transition hasn't happened yet,
8378 @code{nl} is set to negative value. @code{gtroff} itself does this at
8379 the very beginning of a document before anything has been printed, but
8380 the main usage is to plant a header trap on a page if this page has
8383 Consider the following:
8415 Without resetting @code{nl} to a negative value, the just planted trap
8416 would be active beginning with the @emph{next} page, not the current
8419 @xref{Diversions}, for a comparison with the @code{.h} and @code{.d}
8423 @c =====================================================================
8425 @node Fonts and Symbols, Sizes, Page Control, gtroff Reference
8426 @section Fonts and Symbols
8429 @code{gtroff} can switch fonts at any point in the text.
8431 The basic set of fonts is @samp{R}, @samp{I}, @samp{B}, and @samp{BI}.
8432 These are Times Roman, Italic, Bold, and Bold Italic. For non-TTY
8433 devices, there is also at least one symbol font which contains various
8434 special symbols (Greek, mathematics).
8442 * Artificial Fonts::
8443 * Ligatures and Kerning::
8446 @c ---------------------------------------------------------------------
8448 @node Changing Fonts, Font Families, Fonts and Symbols, Fonts and Symbols
8449 @subsection Changing Fonts
8452 @DefreqList {ft, [@Var{font}]}
8453 @DefescItem {\\f, , f, }
8454 @DefescItem {\\f, @Lparen{}, fn, }
8455 @DefescItem {\\f, @Lbrack{}, font, @Rbrack{}}
8456 @DefregListEnd {.sty}
8457 @cindex changing fonts (@code{ft}, @code{\f})
8458 @cindex fonts, changing (@code{ft}, @code{\f})
8459 @cindex @code{sty} request, and changing fonts
8460 @cindex @code{fam} request, and changing fonts
8461 @cindex @code{\F}, and changing fonts
8465 The @code{ft} request and the @code{\f} escape change the current font
8466 to @var{font} (one-character name@tie{}@var{f}, two-character name
8469 If @var{font} is a style name (as set with the @code{sty} request or
8470 with the @code{styles} command in the @file{DESC} file), use it within
8471 the current font family (as set with the @code{fam} request, @code{\F}
8472 escape, or with the @code{family} command in the @file{DESC} file).
8474 @cindex previous font (@code{ft}, @code{\f[]}, @code{\fP})
8475 @cindex font, previous (@code{ft}, @code{\f[]}, @code{\fP})
8476 With no argument or using @samp{P} as an argument, @code{.ft} switches
8477 to the previous font. Use @code{\f[]} to do this with the escape. The
8478 old syntax forms @code{\fP} or @code{\f[P]} are also supported.
8480 Fonts are generally specified as upper-case strings, which are usually
8481 1@tie{}to 4 characters representing an abbreviation or acronym of the
8482 font name. This is no limitation, just a convention.
8484 The example below produces two identical lines.
8493 eggs, bacon, \fBspam\fP and sausage.
8496 Note that @code{\f} doesn't produce an input token in @code{gtroff}.
8497 As a consequence, it can be used in requests like @code{mc} (which
8498 expects a single character as an argument) to change the font on
8505 The current style name is available in the read-only number register
8506 @samp{.sty} (this is a string-valued register); if the current font
8507 isn't a style, the empty string is returned. It is associated with
8508 the current environment.
8510 @xref{Font Positions}, for an alternative syntax.
8513 @Defreq {ftr, f [@Var{g}]}
8514 @cindex @code{ft} request, and font translations
8515 @cindex @code{ul} request, and font translations
8516 @cindex @code{bd} request, and font translations
8517 @cindex @code{\f}, and font translations
8518 @cindex @code{cs} request, and font translations
8519 @cindex @code{tkf} request, and font translations
8520 @cindex @code{special} request, and font translations
8521 @cindex @code{fspecial} request, and font translations
8522 @cindex @code{fp} request, and font translations
8523 @cindex @code{sty} request, and font translations
8524 @cindex @code{if} request, and font translations
8525 @cindex @code{ie} request, and font translations
8526 @cindex @code{while} request, and font translations
8527 Translate font@tie{}@var{f} to font@tie{}@var{g}. Whenever a font
8528 named@tie{}@var{f} is referred to in a @code{\f} escape sequence,
8529 in the @code{F} and @code{S} conditional operators, or in the
8530 @code{ft}, @code{ul}, @code{bd}, @code{cs}, @code{tkf},
8531 @code{special}, @code{fspecial}, @code{fp}, or @code{sty} requests,
8532 font@tie{}@var{g} is used. If @var{g} is missing or equal to@tie{}@var{f}
8533 the translation is undone.
8536 @c ---------------------------------------------------------------------
8538 @node Font Families, Font Positions, Changing Fonts, Fonts and Symbols
8539 @subsection Font Families
8540 @cindex font families
8541 @cindex families, font
8543 @cindex styles, font
8545 Due to the variety of fonts available, @code{gtroff} has added the
8546 concept of @dfn{font families} and @dfn{font styles}. The fonts are
8547 specified as the concatenation of the font family and style. Specifying
8548 a font without the family part causes @code{gtroff} to use that style of
8551 @cindex PostScript fonts
8552 @cindex fonts, PostScript
8553 Currently, fonts for the devices @option{-Tps}, @option{-Tdvi},
8554 @option{-Tlj4}, @option{-Tlbp}, and the X11 fonts are set up to this
8555 mechanism. By default, @code{gtroff} uses the Times family with the four
8556 styles @samp{R}, @samp{I}, @samp{B}, and @samp{BI}.
8558 This way, it is possible to use the basic four fonts and to select a
8559 different font family on the command line (@pxref{Groff Options}).
8561 @DefreqList {fam, [@Var{family}]}
8563 @DefescItem {\\F, , f, }
8564 @DefescItem {\\F, @Lparen{}, fm, }
8565 @DefescItem {\\F, @Lbrack{}, family, @Rbrack{}}
8566 @DefregListEnd {.fn}
8567 @cindex changing font family (@code{fam}, @code{\F})
8568 @cindex font family, changing (@code{fam}, @code{\F})
8569 Switch font family to @var{family} (one-character name@tie{}@var{f},
8570 two-character name @var{fm}). If no argument is given, switch
8571 back to the previous font family. Use @code{\F[]} to do this with the
8572 escape. Note that @code{\FP} doesn't work; it selects font family
8575 The value at start-up is @samp{T}.
8576 The current font family is available in the read-only number register
8577 @samp{.fam} (this is a string-valued register); it is associated with
8578 the current environment.
8582 .fam H \" helvetica family
8583 spam, \" used font is family H + style R = HR
8584 .ft B \" family H + style B = font HB
8586 .fam T \" times family
8587 spam, \" used font is family T + style B = TB
8588 .ft AR \" font AR (not a style)
8590 .ft R \" family T + style R = font TR
8594 Note that @code{\F} doesn't produce an input token in @code{gtroff}.
8595 As a consequence, it can be used in requests like @code{mc} (which
8596 expects a single character as an argument) to change the font family on
8603 The @samp{.fn} register contains the current @dfn{real font name}
8604 of the current font.
8605 This is a string-valued register.
8606 If the current font is a style, the value of @code{\n[.fn]}
8607 is the proper concatenation of family and style name.
8610 @Defreq {sty, n style}
8611 @cindex changing font style (@code{sty})
8612 @cindex font style, changing (@code{sty})
8613 @cindex @code{cs} request, and font styles
8614 @cindex @code{bd} request, and font styles
8615 @cindex @code{tkf} request, and font styles
8616 @cindex @code{uf} request, and font styles
8617 @cindex @code{fspecial} request, and font styles
8618 Associate @var{style} with font position@tie{}@var{n}. A font position
8619 can be associated either with a font or with a style. The current
8620 font is the index of a font position and so is also either a font or a
8621 style. If it is a style, the font that is actually used is the font
8622 which name is the concatenation of the name of the current
8623 family and the name of the current style. For example, if the current
8624 font is@tie{}1 and font position@tie{}1 is associated with style
8625 @samp{R} and the current font family is @samp{T}, then font
8626 @samp{TR} will be used. If the current font is not a style, then the
8627 current family is ignored. If the requests @code{cs}, @code{bd},
8628 @code{tkf}, @code{uf}, or @code{fspecial} are applied to a style,
8629 they will instead be applied to the member of the current family
8630 corresponding to that style.
8632 @var{n}@tie{}must be a non-negative integer value.
8636 The default family can be set with the @option{-f} option
8637 (@pxref{Groff Options}). The @code{styles} command in the @file{DESC}
8638 file controls which font positions (if any) are initially associated
8639 with styles rather than fonts. For example, the default setting for
8640 @sc{PostScript} fonts
8656 @code{fam} and @code{\F} always check whether the current font position
8657 is valid; this can give surprising results if the current font position is
8658 associated with a style.
8660 In the following example, we want to access the @sc{PostScript} font
8661 @code{FooBar} from the font family @code{Foo}:
8666 @result{} warning: can't find font `FooR'
8670 The default font position at start-up is@tie{}1; for the
8671 @sc{PostScript} device, this is associated with style @samp{R}, so
8672 @code{gtroff} tries to open @code{FooR}.
8674 A solution to this problem is to use a dummy font like the following:
8677 .fp 0 dummy TR \" set up dummy font at position 0
8678 .sty \n[.fp] Bar \" register style `Bar'
8679 .ft 0 \" switch to font at position 0
8680 .fam Foo \" activate family `Foo'
8681 .ft Bar \" switch to font `FooBar'
8684 @xref{Font Positions}.
8687 @c ---------------------------------------------------------------------
8689 @node Font Positions, Using Symbols, Font Families, Fonts and Symbols
8690 @subsection Font Positions
8691 @cindex font positions
8692 @cindex positions, font
8694 For the sake of old phototypesetters and compatibility with old versions
8695 of @code{troff}, @code{gtroff} has the concept of font @dfn{positions},
8696 on which various fonts are mounted.
8698 @DefreqList {fp, pos font [@Var{external-name}]}
8700 @DefregListEnd {.fp}
8701 @cindex mounting font (@code{fp})
8702 @cindex font, mounting (@code{fp})
8703 Mount font @var{font} at position @var{pos} (which must be a
8704 non-negative integer). This numeric position can then be referred to
8705 with font changing commands. When @code{gtroff} starts it is using
8706 font position@tie{}1 (which must exist; position@tie{}0 is unused
8707 usually at start-up).
8709 @cindex font position register (@code{.f})
8710 The current font in use, as a font position, is available in the
8711 read-only number register @samp{.f}. This can be useful to remember the
8712 current font for later recall. It is associated with the current
8713 environment (@pxref{Environments}).
8716 .nr save-font \n[.f]
8718 ... text text text ...
8722 @cindex next free font position register (@code{.fp})
8723 The number of the next free font position is available in the read-only
8724 number register @samp{.fp}. This is useful when mounting a new font,
8728 .fp \n[.fp] NEATOFONT
8731 @pindex DESC@r{, and font mounting}
8732 Fonts not listed in the @file{DESC} file are automatically mounted on
8733 the next available font position when they are referenced. If a font
8734 is to be mounted explicitly with the @code{fp} request on an unused
8735 font position, it should be mounted on the first unused font position,
8736 which can be found in the @code{.fp} register. Although @code{gtroff}
8737 does not enforce this strictly, it is not allowed to mount a font at a
8738 position whose number is much greater (approx.@: 1000 positions) than
8739 that of any currently used position.
8741 The @code{fp} request has an optional third argument. This argument
8742 gives the external name of the font, which is used for finding the font
8743 description file. The second argument gives the internal name of the
8744 font which is used to refer to the font in @code{gtroff} after it has
8745 been mounted. If there is no third argument then the internal name is
8746 used as the external name. This feature makes it possible to use
8747 fonts with long names in compatibility mode.
8750 Both the @code{ft} request and the @code{\f} escape have alternative
8751 syntax forms to access font positions.
8753 @DefreqList {ft, nnn}
8754 @DefescItem {\\f, , n, }
8755 @DefescItem {\\f, @Lparen{}, nn, }
8756 @DefescListEnd {\\f, @Lbrack{}, nnn, @Rbrack{}}
8757 @cindex changing font position (@code{\f})
8758 @cindex font position, changing (@code{\f})
8759 @cindex @code{sty} request, and font positions
8760 @cindex @code{fam} request, and font positions
8761 @cindex @code{\F}, and font positions
8765 Change the current font position to @var{nnn} (one-digit
8766 position@tie{}@var{n}, two-digit position @var{nn}), which must be a
8767 non-negative integer.
8769 If @var{nnn} is associated with a style (as set with the @code{sty}
8770 request or with the @code{styles} command in the @file{DESC} file), use
8771 it within the current font family (as set with the @code{fam} request,
8772 the @code{\F} escape, or with the @code{family} command in the @file{DESC}
8779 .ft \" switch back to font 1
8783 this is font 1 again
8786 @xref{Changing Fonts}, for the standard syntax form.
8789 @c ---------------------------------------------------------------------
8791 @node Using Symbols, Special Fonts, Font Positions, Fonts and Symbols
8792 @subsection Using Symbols
8793 @cindex using symbols
8794 @cindex symbols, using
8799 A @dfn{glyph} is a graphical representation of a @dfn{character}.
8800 While a character is an abstract entity containing semantic
8801 information, a glyph is something which can be actually seen on screen
8802 or paper. It is possible that a character has multiple glyph
8803 representation forms (for example, the character `A' can be either
8804 written in a roman or an italic font, yielding two different glyphs);
8805 sometimes more than one character maps to a single glyph (this is a
8806 @dfn{ligature} -- the most common is `fi').
8809 @cindex special fonts
8812 @cindex @code{special} request, and glyph search order
8813 @cindex @code{fspecial} request, and glyph search order
8814 A @dfn{symbol} is simply a named glyph. Within @code{gtroff}, all
8815 glyph names of a particular font are defined in its font file. If the
8816 user requests a glyph not available in this font, @code{gtroff} looks
8817 up an ordered list of @dfn{special fonts}. By default, the
8818 @sc{PostScript} output device supports the two special fonts @samp{SS}
8819 (slanted symbols) and @samp{S} (symbols) (the former is looked up
8820 before the latter). Other output devices use different names for
8821 special fonts. Fonts mounted with the @code{fonts} keyword in the
8822 @file{DESC} file are globally available. To install additional
8823 special fonts locally (i.e.@: for a particular font), use the
8824 @code{fspecial} request.
8826 Here the exact rules how @code{gtroff} searches a given symbol:
8830 If the symbol has been defined with the @code{char} request, use it.
8831 This hides a symbol with the same name in the current font.
8834 Check the current font.
8837 If the symbol has been defined with the @code{fchar} request, use it.
8840 Check whether the current font has a font-specific list of special fonts;
8841 test all fonts in the order of appearance in the last @code{fspecial}
8842 call if appropriate.
8845 If the symbol has been defined with the @code{fschar} request for the
8846 current font, use it.
8849 Check all fonts in the order of appearance in the last @code{special}
8853 If the symbol has been defined with the @code{schar} request, use it.
8856 As a last resort, consult all fonts loaded up to now for special fonts
8857 and check them, starting with the lowest font number. Note that this can
8858 sometimes lead to surprising results since the @code{fonts} line in the
8859 @file{DESC} file often contains empty positions which are filled later
8860 on. For example, consider the following:
8867 This mounts font @code{foo} at font position@tie{}3. We assume that
8868 @code{FOO} is a special font, containing glyph @code{foo},
8869 and that no font has been loaded yet. The line
8876 makes font @code{BAZ} special only if font @code{BAR} is active. We
8877 further assume that @code{BAZ} is really a special font, i.e., the font
8878 description file contains the @code{special} keyword, and that it
8879 also contains glyph @code{foo} with a special shape fitting to font
8880 @code{BAR}. After executing @code{fspecial}, font @code{BAR} is loaded at
8881 font position@tie{}1, and @code{BAZ} at position@tie{}2.
8883 We now switch to a new font @code{XXX}, trying to access glyph @code{foo}
8884 which is assumed to be missing. There are neither font-specific special
8885 fonts for @code{XXX} nor any other fonts made special with the
8886 @code{special} request, so @code{gtroff} starts the search for special
8887 fonts in the list of already mounted fonts, with increasing font
8888 positions. Consequently, it finds @code{BAZ} before @code{FOO} even for
8889 @code{XXX} which is not the intended behaviour.
8892 @xref{Font Files}, and @ref{Special Fonts}, for more details.
8894 @cindex list of available glyphs (@cite{groff_char(7)} man page)
8895 @cindex available glyphs, list (@cite{groff_char(7)} man page)
8896 @cindex glyphs, available, list (@cite{groff_char(7)} man page)
8897 The list of available symbols is device dependent; see the
8898 @cite{groff_char(7)} man page for a complete list of all glyphs. For
8902 man -Tdvi groff_char > groff_char.dvi
8906 for a list using the default DVI fonts (not all versions of the
8907 @code{man} program support the @option{-T} option). If you want to
8908 use an additional macro package to change the used fonts, @code{groff}
8909 must be called directly:
8912 groff -Tdvi -mec -man groff_char.7 > groff_char.dvi
8915 @cindex composite glyph names
8916 @cindex glyph names, composite
8917 @cindex groff glyph list (GGL)
8918 @cindex GGL (groff glyph list)
8919 @cindex adobe glyph list (AGL)
8920 @cindex AGL (adobe glyph list)
8921 Glyph names not listed in groff_char(7) are derived algorithmically,
8922 using a simplified version of the Adobe Glyph List (AGL) algorithm
8923 which is described in
8924 @uref{http://partners.adobe.com@//asn@//tech@//type@//unicodegn.jsp}.
8925 The (frozen) set of glyph names which can't be derived algorithmically
8926 is called @dfn{groff glyph list (GGL)}.
8930 A glyph for Unicode character U+@var{XXXX}[@var{X}[@var{X}]] which is
8931 not a composite character will be named
8932 @code{u@var{XXXX}@r{[}@var{X}@r{[}@var{X}@r{]]}}. @var{X} must be an
8933 uppercase hexadecimal digit. Examples: @code{u1234}, @code{u008E},
8934 @code{u12DB8}. The largest Unicode value is 0x10FFFF. There must be at
8935 least four @code{X} digits; if necessary, add leading zeroes (after the
8936 @samp{u}). No zero padding is allowed for character codes greater than
8937 0xFFFF. Surrogates (i.e., Unicode values greater than 0xFFFF
8938 represented with character codes from the surrogate area U+D800-U+DFFF)
8939 are not allowed too.
8942 A glyph representing more than a single input character will be named
8945 @samp{u} @var{component1} @samp{_} @var{component2} @samp{_} @var{component3} @dots{}
8949 Example: @code{u0045_0302_0301}.
8951 For simplicity, all Unicode characters which are composites must be
8952 decomposed maximally (this is normalization form@tie{}D in the Unicode
8953 standard); for example, @code{u00CA_0301} is not a valid glyph name
8954 since U+00CA (@sc{latin capital letter e with circumflex}) can be
8955 further decomposed into U+0045 (@sc{latin capital letter e}) and U+0302
8956 (@sc{combining circumflex accent}). @code{u0045_0302_0301} is thus the
8957 glyph name for U+1EBE, @sc{latin capital letter e with circumflex and
8961 groff maintains a table to decompose all algorithmically derived glyph
8962 names which are composites itself. For example, @code{u0100} (@sc{latin
8963 letter a with macron}) will be automatically decomposed into
8964 @code{u0041_0304}. Additionally, a glyph name of the GGL is preferred
8965 to an algorithmically derived glyph name; groff also automatically does
8966 the mapping. Example: The glyph @code{u0045_0302} will be mapped to
8970 glyph names of the GGL can't be used in composite glyph names; for
8971 example, @code{^E_u0301} is invalid.
8974 @DefescList {\\, @Lparen{}, nm, }
8975 @DefescItem {\\, @Lbrack{}, name, @Rbrack{}}
8976 @DefescListEnd {\\, @Lbrack{}, component1 component2 @dots{}, @Rbrack{}}
8977 Insert a symbol @var{name} (two-character name @var{nm}) or a composite
8978 glyph with component glyphs @var{component1}, @var{component2},
8979 @enddots{} There is no special syntax for one-character names -- the
8980 natural form @samp{\@var{n}} would collide with escapes.@footnote{Note
8981 that a one-character symbol is not the same as an input character, i.e.,
8982 the character @code{a} is not the same as @code{\[a]}. By default,
8983 @code{groff} defines only a single one-character symbol, @code{\[-]}; it
8984 is usually accessed as @code{\-}. On the other hand, @code{gtroff} has
8985 the special feature that @code{\[char@var{XXX}]} is the same as the
8986 input character with character code @var{XXX}. For example,
8987 @code{\[char97]} is identical to the letter @code{a} if @acronym{ASCII}
8988 encoding is active.}
8990 If @var{name} is undefined, a warning of type @samp{char} is generated,
8991 and the escape is ignored. @xref{Debugging}, for information about
8994 groff resolves @code{\[...]} with more than a single component as
8999 Any component which is found in the GGL will be converted to the
9000 @code{u@var{XXXX}} form.
9003 Any component @code{u@var{XXXX}} which is found in the list of
9004 decomposable glyphs will be decomposed.
9007 The resulting elements are then concatenated with @samp{_} inbetween,
9008 dropping the leading @samp{u} in all elements but the first.
9011 No check for the existence of any component (similar to @code{tr}
9012 request) will be done.
9018 @samp{A} maps to @code{u0041}, @samp{ho} maps to @code{u02DB}, thus the
9019 final glyph name would be @code{u0041_02DB}. Note this is not the
9020 expected result: The ogonek glyph @samp{ho} is a spacing ogonek, but for
9021 a proper composite a non-spacing ogonek (U+0328) is necessary. Looking
9022 into the file @file{composite.tmac} one can find @w{@samp{.composite ho
9023 u0328}} which changes the mapping of @samp{ho} while a composite glyph
9024 name is constructed, causing the final glyph name to be
9031 @samp{^E} maps to @code{u0045_0302}, thus the final glyph name is
9032 @code{u0045_0302_0301} in all forms (assuming proper calls of the
9033 @code{composite} request).
9036 It is not possible to define glyphs with names like @w{@samp{A ho}}
9037 within a groff font file. This is not really a limitation; instead, you
9038 have to define @code{u0041_0328}.
9041 @Defesc {\\C, ', xxx, '}
9042 @cindex named character (@code{\C})
9043 @cindex character, named (@code{\C})
9044 Typeset the glyph named @var{xxx}.@footnote{@code{\C} is actually a
9045 misnomer since it accesses an output glyph.} Normally it is more
9046 convenient to use @code{\[@var{xxx}]}, but @code{\C} has the advantage
9047 that it is compatible with newer versions of @acronym{AT&T}
9048 @code{troff} and is available in compatibility mode.
9051 @Defreq {composite, from to}
9052 @pindex composite.tmac
9053 Map glyph name @var{from} to glyph name @var{to} if it is used in
9054 @code{\[...]} with more than one component. See above for examples.
9056 This mapping is based on glyph names only; no check for the existence of
9057 either glyph is done.
9059 A set of default mappings for many accents can be found in the file
9060 @file{composite.tmac} which is loaded at start-up.
9063 @Defesc {\\N, ', n, '}
9064 @cindex numbered glyph (@code{\N})
9065 @cindex glyph, numbered (@code{\N})
9066 @cindex @code{char} request, used with @code{\N}
9068 Typeset the glyph with code@tie{}@var{n} in the current font
9069 (@code{n}@tie{}is @strong{not} the input character code). The
9070 number @var{n}@tie{}can be any non-negative decimal integer. Most devices
9071 only have glyphs with codes between 0 and@tie{}255; the Unicode
9072 output device uses codes in the range 0--65535. If the current
9073 font does not contain a glyph with that code, special fonts are
9074 @emph{not} searched. The @code{\N} escape sequence can be
9075 conveniently used in conjunction with the @code{char} request:
9078 .char \[phone] \f[ZD]\N'37'
9083 @cindex unnamed glyphs
9084 @cindex glyphs, unnamed
9085 The code of each glyph is given in the fourth column in the font
9086 description file after the @code{charset} command. It is possible to
9087 include unnamed glyphs in the font description file by using a
9088 name of @samp{---}; the @code{\N} escape sequence is the only way to
9091 No kerning is applied to glyphs accessed with @code{\N}.
9094 Some escape sequences directly map onto special glyphs.
9097 This is a backslash followed by the apostrophe character, @acronym{ASCII}
9098 character @code{0x27} (@acronym{EBCDIC} character @code{0x7D}). The same
9099 as @code{\[aa]}, the acute accent.
9103 This is a backslash followed by @acronym{ASCII} character @code{0x60}
9104 (@acronym{EBCDIC} character @code{0x79} usually). The same as
9105 @code{\[ga]}, the grave accent.
9109 This is the same as @code{\[-]}, the minus sign in the current font.
9112 @Defreq {cflags, n c1 c2 @dots{}}
9113 @cindex glyph properties (@code{cflags})
9114 @cindex character properties (@code{cflags})
9115 @cindex properties of glyphs (@code{cflags})
9116 @cindex properties of characters (@code{cflags})
9117 Input characters and symbols have certain properties associated
9118 with it.@footnote{Note that the output glyphs themselves don't have
9119 such properties. For @code{gtroff}, a glyph is a numbered box with
9120 a given width, depth, and height, nothing else. All manipulations
9121 with the @code{cflags} request work on the input level.} These
9122 properties can be modified with the @code{cflags} request. The
9123 first argument is the sum of the desired flags and the remaining
9124 arguments are the characters or symbols to have those properties.
9125 It is possible to omit the spaces between the characters or symbols.
9129 @cindex end-of-sentence characters
9130 @cindex characters, end-of-sentence
9131 The character ends sentences (initially characters @samp{.?!} have this
9135 @cindex hyphenating characters
9136 @cindex characters, hyphenation
9137 Lines can be broken before the character (initially no characters have
9141 @cindex @code{hy} glyph, and @code{cflags}
9142 @cindex @code{em} glyph, and @code{cflags}
9143 Lines can be broken after the character (initially the character
9144 @samp{-} and the symbols @samp{\[hy]} and @samp{\[em]} have this property).
9147 @cindex overlapping characters
9148 @cindex characters, overlapping
9149 @cindex @code{ul} glyph, and @code{cflags}
9150 @cindex @code{rn} glyph, and @code{cflags}
9151 @cindex @code{ru} glyph, and @code{cflags}
9152 @cindex @code{radicalex} glyph, and @code{cflags}
9153 @cindex @code{sqrtex} glyph, and @code{cflags}
9154 The character overlaps horizontally if used as a horizontal line building
9155 element. Initially the symbols @samp{\[ul]}, @samp{\[rn]}, @samp{\[ru]},
9156 @samp{\[radicalex]}, and @samp{\[sqrtex]} have this property.
9159 @cindex @code{br} glyph, and @code{cflags}
9160 The character overlaps vertically if used as vertical line building element.
9161 Initially symbol @samp{\[br]} has this property.
9164 @cindex transparent characters
9165 @cindex character, transparent
9166 @cindex @code{"}, at end of sentence
9167 @cindex @code{'}, at end of sentence
9168 @cindex @code{)}, at end of sentence
9169 @cindex @code{]}, at end of sentence
9170 @cindex @code{*}, at end of sentence
9171 @cindex @code{dg} glyph, at end of sentence
9172 @cindex @code{rq} glyph, at end of sentence
9173 An end-of-sentence character followed by any number of characters with
9174 this property is treated as the end of a sentence if followed by a
9175 newline or two spaces; in other words the character is
9176 @dfn{transparent} for the purposes of end-of-sentence recognition --
9177 this is the same as having a zero space factor in @TeX{} (initially
9178 characters @samp{"')]*} and the symbols @samp{\[dg]} and @samp{\[rq]} have
9183 @DefreqList {char, g [@Var{string}]}
9184 @DefreqItem {fchar, g [@Var{string}]}
9185 @DefreqItem {fschar, f g [@Var{string}]}
9186 @DefreqListEnd {schar, g [@Var{string}]}
9187 @cindex defining character (@code{char})
9188 @cindex defining fallback character (@code{fchar}, @code{fschar}, @code{schar})
9189 @cindex character, defining (@code{char})
9190 @cindex character, defining fallback (@code{fchar}, @code{fschar}, @code{schar})
9191 @cindex fallback character, defining (@code{fchar}, @code{fschar}, @code{schar})
9192 @cindex creating new characters (@code{char})
9193 @cindex defining symbol (@code{char})
9194 @cindex symbol, defining (@code{char})
9195 @cindex defining glyph (@code{char})
9196 @cindex glyph, defining (@code{char})
9197 @cindex escape character, while defining glyph
9198 @cindex character, escape, while defining glyph
9199 @cindex @code{tr} request, and glyph definitions
9200 @cindex @code{cp} request, and glyph definitions
9201 @cindex @code{rc} request, and glyph definitions
9202 @cindex @code{lc} request, and glyph definitions
9203 @cindex @code{\l}, and glyph definitions
9204 @cindex @code{\L}, and glyph definitions
9205 @cindex @code{\&}, and glyph definitions
9206 @cindex @code{\e}, and glyph definitions
9207 @cindex @code{hcode} request, and glyph definitions
9208 Define a new glyph@tie{}@var{g} to be @var{string} (which can be
9209 empty).@footnote{@code{char} is a misnomer since an output glyph is
9210 defined.} Every time glyph@tie{}@var{g} needs to be printed,
9211 @var{string} is processed in a temporary environment and the result is
9212 wrapped up into a single object. Compatibility mode is turned off and
9213 the escape character is set to @samp{\} while @var{string} is being
9214 processed. Any emboldening, constant spacing or track kerning is
9215 applied to this object rather than to individual characters in
9218 A glyph defined by these requests can be used just
9219 like a normal glyph provided by the output device. In particular,
9220 other characters can be translated to it with the @code{tr} or
9221 @code{trin} requests; it can be made the leader character by the
9222 @code{lc} request; repeated patterns can be drawn with the glyph
9223 using the @code{\l} and @code{\L} escape sequences; words containing
9224 the glyph can be hyphenated correctly if the @code{hcode} request
9225 is used to give the glyph's symbol a hyphenation code.
9227 There is a special anti-recursion feature: Use of @code{g} within
9228 the glyph's definition is handled like normal characters and symbols
9229 not defined with @code{char}.
9231 Note that the @code{tr} and @code{trin} requests take precedence if
9232 @code{char} accesses the same symbol.
9246 The @code{fchar} request defines a fallback glyph:
9247 @code{gtroff} only checks for glyphs defined with @code{fchar}
9248 if it cannot find the glyph in the current font.
9249 @code{gtroff} carries out this test before checking special fonts.
9251 @code{fschar} defines a fallback glyph for font@tie{}@var{f}: @code{gtroff}
9252 checks for glyphs defined with @code{fschar} after the list of fonts
9253 declared as font-specific special fonts with the @code{fspecial} request,
9254 but before the list of fonts declared as global special fonts with the
9255 @code{special} request.
9257 Finally, the @code{schar} request defines a global fallback glyph:
9258 @code{gtroff} checks for glyphs defined with @code{schar} after the list
9259 of fonts declared as global special fonts with the @code{special} request,
9260 but before the already mounted special fonts.
9262 @xref{Using Symbols}, for a detailed description of the glyph
9263 searching mechanism in @code{gtroff}.
9266 @DefreqList {rchar, c1 c2 @dots{}}
9267 @DefreqListEnd {rfschar, f c1 c2 @dots{}}
9268 @cindex removing glyph definition (@code{rchar}, @code{rfschar})
9269 @cindex glyph, removing definition (@code{rchar}, @code{rfschar})
9270 @cindex fallback glyph, removing definition (@code{rchar}, @code{rfschar})
9271 Remove the definitions of glyphs @var{c1}, @var{c2},@tie{}@enddots{}
9272 This undoes the effect of a @code{char}, @code{fchar}, or
9273 @code{schar} request.
9275 It is possible to omit the whitespace between arguments.
9277 The request @code{rfschar} removes glyph definitions defined with
9278 @code{fschar} for glyph@tie{}f.
9281 @xref{Special Characters}.
9283 @c ---------------------------------------------------------------------
9285 @node Special Fonts, Artificial Fonts, Using Symbols, Fonts and Symbols
9286 @subsection Special Fonts
9287 @cindex special fonts
9288 @cindex fonts, special
9290 Special fonts are those that @code{gtroff} searches
9291 when it cannot find the requested glyph in the current font.
9292 The Symbol font is usually a special font.
9294 @code{gtroff} provides the following two requests to add more special
9295 fonts. @xref{Using Symbols}, for a detailed description of the glyph
9296 searching mechanism in @code{gtroff}.
9298 Usually, only non-TTY devices have special fonts.
9300 @DefreqList {special, [@Var{s1} @Var{s2} @dots{}]}
9301 @DefreqListEnd {fspecial, f [@Var{s1} @Var{s2} @dots{}]}
9304 Use the @code{special} request to define special fonts. Initially, this
9307 Use the @code{fspecial} request to designate special fonts only when
9308 font@tie{}@var{f} is active. Initially, this list is empty.
9310 Previous calls to @code{special} or @code{fspecial} are overwritten;
9311 without arguments, the particular list of special fonts is set to empty.
9312 Special fonts are searched in the order they appear as arguments.
9314 All fonts which appear in a call to @code{special} or @code{fspecial} are
9317 @xref{Using Symbols}, for the exact search order of glyphs.
9320 @c ---------------------------------------------------------------------
9322 @node Artificial Fonts, Ligatures and Kerning, Special Fonts, Fonts and Symbols
9323 @subsection Artificial Fonts
9324 @cindex artificial fonts
9325 @cindex fonts, artificial
9327 There are a number of requests and escapes for artificially creating
9328 fonts. These are largely vestiges of the days when output devices
9329 did not have a wide variety of fonts, and when @code{nroff} and
9330 @code{troff} were separate programs. Most of them are no longer
9331 necessary in GNU @code{troff}. Nevertheless, they are supported.
9333 @DefescList {\\H, ', height, '}
9334 @DefescItem {\\H, ', @t{+}height, '}
9335 @DefescItem {\\H, ', @t{-}height, '}
9336 @DefregListEnd {.height}
9337 @cindex changing the font height (@code{\H})
9338 @cindex font height, changing (@code{\H})
9339 @cindex height, font, changing (@code{\H})
9340 Change (increment, decrement) the height of the current font, but not
9341 the width. If @var{height} is zero, restore the original height.
9342 Default scaling indicator is @samp{z}.
9344 The read-only number register @code{.height} contains the font height as
9347 Currently, only the @option{-Tps} device supports this feature.
9349 Note that @code{\H} doesn't produce an input token in @code{gtroff}.
9350 As a consequence, it can be used in requests like @code{mc} (which
9351 expects a single character as an argument) to change the font on
9358 In compatibility mode, @code{gtroff} behaves differently: If an
9359 increment or decrement is used, it is always taken relative to the
9360 current point size and not relative to the previously selected font
9365 \H'+5'test \H'+5'test
9369 prints the word @samp{test} twice with the same font height (five
9370 points larger than the current font size).
9373 @DefescList {\\S, ', slant, '}
9374 @DefregListEnd {.slant}
9375 @cindex changing the font slant (@code{\S})
9376 @cindex font slant, changing (@code{\S})
9377 @cindex slant, font, changing (@code{\S})
9378 Slant the current font by @var{slant} degrees. Positive values slant
9379 to the right. Only integer values are possible.
9381 The read-only number register @code{.slant} contains the font slant as
9384 Currently, only the @option{-Tps} device supports this feature.
9386 Note that @code{\S} doesn't produce an input token in @code{gtroff}.
9387 As a consequence, it can be used in requests like @code{mc} (which
9388 expects a single character as an argument) to change the font on
9395 This request is incorrectly documented in the original @acronym{UNIX}
9396 troff manual; the slant is always set to an absolute value.
9399 @Defreq {ul, [@Var{lines}]}
9400 @cindex underlining (@code{ul})
9401 The @code{ul} request normally underlines subsequent lines if a TTY
9402 output device is used. Otherwise, the lines are printed in italics
9403 (only the term `underlined' is used in the following). The single
9404 argument is the number of input lines to be underlined; with no
9405 argument, the next line is underlined. If @var{lines} is zero or
9406 negative, stop the effects of @code{ul} (if it was active). Requests
9407 and empty lines do not count for computing the number of underlined
9408 input lines, even if they produce some output like @code{tl}. Lines
9409 inserted by macros (e.g.@: invoked by a trap) do count.
9411 At the beginning of @code{ul}, the current font is stored and the
9412 underline font is activated. Within the span of a @code{ul} request,
9413 it is possible to change fonts, but after the last line affected by
9414 @code{ul} the saved font is restored.
9416 This number of lines still to be underlined is associated with the
9417 current environment (@pxref{Environments}). The underline font can be
9418 changed with the @code{uf} request.
9420 @c XXX @xref should be changed to grotty
9422 @c @xref{Troff and Nroff Mode}, for a discussion how underlining is
9423 @c implemented in for TTY output devices, and which problems can arise.
9425 The @code{ul} request does not underline spaces.
9428 @Defreq {cu, [@Var{lines}]}
9429 @cindex continuous underlining (@code{cu})
9430 @cindex underlining, continuous (@code{cu})
9431 The @code{cu} request is similar to @code{ul} but underlines spaces as
9432 well (if a TTY output device is used).
9436 @cindex underline font (@code{uf})
9437 @cindex font for underlining (@code{uf})
9438 Set the underline font (globally) used by @code{ul} and @code{cu}. By
9439 default, this is the font at position@tie{}2. @var{font} can be either
9440 a non-negative font position or the name of a font.
9443 @DefreqList {bd, font [@Var{offset}]}
9444 @DefreqItem {bd, font1 font2 [@Var{offset}]}
9446 @cindex imitating bold face (@code{bd})
9447 @cindex bold face, imitating (@code{bd})
9448 Artificially create a bold font by printing each glyph twice,
9451 Two syntax forms are available.
9455 Imitate a bold font unconditionally. The first argument specifies the
9456 font to embolden, and the second is the number of basic units, minus
9457 one, by which the two glyphs are offset. If the second argument is
9458 missing, emboldening is turned off.
9460 @var{font} can be either a non-negative font position or the name of a
9463 @var{offset} is available in the @code{.b} read-only register if a
9464 special font is active; in the @code{bd} request, its default unit is
9467 @cindex @code{fspecial} request, and imitating bold
9469 @cindex embolding of special fonts
9470 @cindex special fonts, emboldening
9472 Imitate a bold form conditionally. Embolden @var{font1} by
9473 @var{offset} only if font @var{font2} is the current font. This
9474 command can be issued repeatedly to set up different emboldening
9475 values for different current fonts. If the second argument is
9476 missing, emboldening is turned off for this particular current font.
9478 This affects special fonts only (either set up with the @code{special}
9479 command in font files or with the @code{fspecial} request).
9483 @Defreq {cs, font [@Var{width} [@Var{em-size}]]}
9484 @cindex constant glyph space mode (@code{cs})
9485 @cindex mode for constant glyph space (@code{cs})
9486 @cindex glyph, constant space
9487 @cindex @code{ps} request, and constant glyph space mode
9488 Switch to and from @dfn{constant glyph space mode}. If activated, the
9489 width of every glyph is @math{@var{width}/36} ems. The em size is
9490 given absolutely by @var{em-size}; if this argument is missing, the em
9491 value is taken from the current font size (as set with the @code{ps}
9492 request) when the font is effectively in use. Without second and
9493 third argument, constant glyph space mode is deactivated.
9495 Default scaling indicator for @var{em-size} is @samp{z}; @var{width} is
9499 @c ---------------------------------------------------------------------
9501 @node Ligatures and Kerning, , Artificial Fonts, Fonts and Symbols
9502 @subsection Ligatures and Kerning
9503 @cindex ligatures and kerning
9504 @cindex kerning and ligatures
9506 Ligatures are groups of characters that are run together, i.e, producing
9507 a single glyph. For example, the letters `f' and `i' can form a
9508 ligature `fi' as in the word `file'. This produces a cleaner look
9509 (albeit subtle) to the printed output. Usually, ligatures are not
9510 available in fonts for TTY output devices.
9512 Most @sc{PostScript} fonts support the fi and fl ligatures. The C/A/T
9513 typesetter that was the target of @acronym{AT&T} @code{troff} also
9514 supported `ff', `ffi', and `ffl' ligatures. Advanced typesetters or
9515 `expert' fonts may include ligatures for `ft' and `ct', although GNU
9516 @code{troff} does not support these (yet).
9518 Only the current font is checked for ligatures and kerns; neither special
9519 fonts nor entities defined with the @code{char} request (and its siblings)
9520 are taken into account.
9522 @DefreqList {lg, [@Var{flag}]}
9523 @DefregListEnd {.lg}
9524 @cindex activating ligatures (@code{lg})
9525 @cindex ligatures, activating (@code{lg})
9526 @cindex ligatures enabled register (@code{.lg})
9527 Switch the ligature mechanism on or off; if the parameter is non-zero
9528 or missing, ligatures are enabled, otherwise disabled. Default is on.
9529 The current ligature mode can be found in the read-only number register
9530 @code{.lg} (set to 1 or@tie{}2 if ligatures are enabled, 0@tie{}otherwise).
9532 Setting the ligature mode to@tie{}2 enables the two-character ligatures
9533 (fi, fl, and ff) and disables the three-character ligatures (ffi and
9537 @dfn{Pairwise kerning} is another subtle typesetting mechanism that
9538 modifies the distance between a glyph pair to improve readability.
9539 In most cases (but not always) the distance is decreased.
9541 For example, compare the combination of the letters `V' and `A'. With
9542 kerning, `VA' is printed. Without kerning it appears as `V@w{}A'.
9544 Typewriter-like fonts and fonts for terminals where all glyphs
9545 have the same width don't use kerning.
9547 @DefreqList {kern, [@Var{flag}]}
9548 @DefregListEnd {.kern}
9549 @cindex activating kerning (@code{kern})
9550 @cindex kerning, activating (@code{kern})
9551 @cindex kerning enabled register (@code{.kern})
9552 Switch kerning on or off. If the parameter is non-zero or missing,
9553 enable pairwise kerning, otherwise disable it. The read-only number
9554 register @code{.kern} is set to@tie{}1 if pairwise kerning is enabled,
9557 @cindex zero width space character (@code{\&})
9558 @cindex character, zero width space (@code{\&})
9559 @cindex space character, zero width (@code{\&})
9560 If the font description file contains pairwise kerning information,
9561 glyphs from that font are kerned. Kerning between two glyphs
9562 can be inhibited by placing @code{\&} between them: @samp{V\&A}.
9564 @xref{Font File Format}.
9567 @cindex track kerning
9568 @cindex kerning, track
9569 @dfn{Track kerning} expands or reduces the space between glyphs.
9570 This can be handy, for example, if you need to squeeze a long word
9571 onto a single line or spread some text to fill a narrow column. It
9572 must be used with great care since it is usually considered bad
9573 typography if the reader notices the effect.
9575 @Defreq {tkf, f s1 n1 s2 n2}
9576 @cindex activating track kerning (@code{tkf})
9577 @cindex track kerning, activating (@code{tkf})
9578 Enable track kerning for font@tie{}@var{f}. If the current font
9579 is@tie{}@var{f} the width of every glyph is increased by an amount
9580 between @var{n1} and @var{n2} (@var{n1}, @var{n2} can be negative); if
9581 the current point size is less than or equal to @var{s1} the width is
9582 increased by @var{n1}; if it is greater than or equal to @var{s2} the
9583 width is increased by @var{n2}; if the point size is greater than or
9584 equal to @var{s1} and less than or equal to @var{s2} the increase in
9585 width is a linear function of the point size.
9587 The default scaling indicator is @samp{z} for @var{s1} and @var{s2},
9588 @samp{p} for @var{n1} and @var{n2}.
9590 Note that the track kerning amount is added even to the rightmost glyph
9591 in a line; for large values it is thus recommended to increase the line
9592 length by the same amount to compensate it.
9595 Sometimes, when typesetting letters of different fonts, more or less
9596 space at such boundaries are needed. There are two escapes to help
9600 @cindex italic correction (@code{\/})
9601 @cindex correction, italic (@code{\/})
9602 @cindex correction between italic and roman glyph (@code{\/}, @code{\,})
9603 @cindex roman glyph, correction after italic glyph (@code{\/})
9604 @cindex italic glyph, correction before roman glyph (@code{\/})
9605 @cindex glyph, italic correction (@code{\/})
9606 Increase the width of the preceding glyph so that the spacing
9607 between that glyph and the following glyph is correct if the
9608 following glyph is a roman glyph. For example, if an
9609 italic@tie{}@code{f} is immediately followed by a roman right
9610 parenthesis, then in many fonts the top right portion of the@tie{}@code{f}
9611 overlaps the top left of the right parenthesis. Use this escape
9612 sequence whenever an italic glyph is immediately followed by a
9613 roman glyph without any intervening space. This small amount of
9614 space is also called @dfn{italic correction}.
9617 @c can't use @Example...@endExample here
9621 @result{} {@it f}@r{)}
9623 @result{} @i{f}@r{)}
9629 @Defesc {\\\,, , , }
9630 @cindex left italic correction (@code{\,})
9631 @cindex correction, left italic (@code{\,})
9632 @cindex glyph, left italic correction (@code{\,})
9633 @cindex roman glyph, correction before italic glyph (@code{\,})
9634 @cindex italic glyph, correction after roman glyph (@code{\,})
9635 Modify the spacing of the following glyph so that the spacing
9636 between that glyph and the preceding glyph is correct if the
9637 preceding glyph is a roman glyph. Use this escape sequence
9638 whenever a roman glyph is immediately followed by an italic
9639 glyph without any intervening space. In analogy to above, this
9640 space could be called @dfn{left italic correction}, but this term
9644 @c can't use @Example...@endExample here
9648 @result{} @r{q}@i{f}
9650 @result{} @r{q}@math{@ptexcomma}@i{f}
9657 Insert a zero-width character, which is invisible. Its intended use
9658 is to stop interaction of a character with its surrounding.
9662 It prevents the insertion of extra space after an end-of-sentence
9668 @result{} Test. Test.
9671 @result{} Test. Test.
9675 It prevents interpretation of a control character at the beginning of
9680 @result{} warning: `Test' not defined
9686 It prevents kerning between two glyphs.
9689 @c can't use @Example...@endExample here
9695 @result{} @r{V@w{}A}
9701 It is needed to map an arbitrary character to nothing in the @code{tr}
9702 request (@pxref{Character Translations}).
9707 This escape is similar to @code{\&} except that it behaves like a
9708 character declared with the @code{cflags} request to be transparent
9709 for the purposes of an end-of-sentence character.
9711 Its main usage is in macro definitions to protect against arguments
9712 starting with a control character.
9724 @result{}This is a test.' This is a test.
9728 @result{}This is a test.' This is a test.
9733 @c =====================================================================
9735 @node Sizes, Strings, Fonts and Symbols, gtroff Reference
9741 @cindex size of type
9742 @cindex vertical spacing
9743 @cindex spacing, vertical
9744 @code{gtroff} uses two dimensions with each line of text, type size
9745 and vertical spacing. The @dfn{type size} is approximately the height
9746 of the tallest glyph.@footnote{This is usually the parenthesis.
9747 Note that in most cases the real dimensions of the glyphs in a font
9748 are @emph{not} related to its type size! For example, the standard
9749 @sc{PostScript} font families `Times Roman', `Helvetica', and
9750 `Courier' can't be used together at 10@dmn{pt}; to get acceptable
9751 output, the size of `Helvetica' has to be reduced by one point, and
9752 the size of `Courier' must be increased by one point.} @dfn{Vertical
9753 spacing} is the amount of space @code{gtroff} allows for a line of
9754 text; normally, this is about 20%@tie{}larger than the current type
9755 size. Ratios smaller than this can result in hard-to-read text;
9756 larger than this, it spreads the text out more vertically (useful for
9757 term papers). By default, @code{gtroff} uses 10@tie{}point type on
9758 12@tie{}point spacing.
9761 The difference between type size and vertical spacing is known, by
9762 typesetters, as @dfn{leading} (this is pronounced `ledding').
9765 * Changing Type Sizes::
9766 * Fractional Type Sizes::
9769 @c ---------------------------------------------------------------------
9771 @node Changing Type Sizes, Fractional Type Sizes, Sizes, Sizes
9772 @subsection Changing Type Sizes
9774 @DefreqList {ps, [@Var{size}]}
9775 @DefreqItem {ps, @t{+}@Var{size}}
9776 @DefreqItem {ps, @t{-}@Var{size}}
9777 @DefescItem {\\s, , size, }
9779 @cindex changing type sizes (@code{ps}, @code{\s})
9780 @cindex type sizes, changing (@code{ps}, @code{\s})
9781 @cindex point sizes, changing (@code{ps}, @code{\s})
9782 Use the @code{ps} request or the @code{\s} escape to change (increase,
9783 decrease) the type size (in points). Specify @var{size} as either an
9784 absolute point size, or as a relative change from the current size.
9785 The size@tie{}0, or no argument, goes back to the previous size.
9787 Default scaling indicator of @code{size} is @samp{z}. If @code{size}
9788 is zero or negative, it is set to 1@dmn{u}.
9790 @cindex type size registers (@code{.s}, @code{.ps})
9791 @cindex point size registers (@code{.s}, @code{.ps})
9792 The read-only number register @code{.s} returns the point size in
9793 points as a decimal fraction. This is a string. To get the point
9794 size in scaled points, use the @code{.ps} register instead.
9796 @code{.s} is associated with the current environment
9797 (@pxref{Environments}).
9804 wink, wink, \s+2nudge, nudge,\s+8 say no more!
9808 The @code{\s} escape may be called in a variety of ways. Much like
9809 other escapes there must be a way to determine where the argument ends
9810 and the text begins. Any of the following forms are valid:
9814 Set the point size to @var{n}@tie{}points. @var{n}@tie{}must be either
9815 0 or in the range 4 to@tie{}39.
9819 Increase or decrease the point size by @var{n}@tie{}points.
9820 @var{n}@tie{}must be exactly one digit.
9823 Set the point size to @var{nn}@tie{}points. @var{nn} must be exactly
9830 Increase or decrease the point size by @var{nn}@tie{}points. @var{nn}
9831 must be exactly two digits.
9834 Note that @code{\s} doesn't produce an input token in @code{gtroff}.
9835 As a consequence, it can be used in requests like @code{mc} (which
9836 expects a single character as an argument) to change the font on
9843 @xref{Fractional Type Sizes}, for yet another syntactical form of
9844 using the @code{\s} escape.
9847 @Defreq {sizes, s1 s2 @dots{} sn [0]}
9848 Some devices may only have certain permissible sizes, in which case
9849 @code{gtroff} rounds to the nearest permissible size.
9850 The @file{DESC} file specifies which sizes are permissible for the device.
9852 Use the @code{sizes} request to change the permissible sizes
9853 for the current output device.
9854 Arguments are in scaled points;
9855 the @code{sizescale} line in the
9856 @file{DESC} file for the output device
9857 provides the scaling factor.
9858 For example, if the scaling factor is 1000,
9859 then the value 12000 is 12@tie{}points.
9861 Each argument can be a single point size (such as @samp{12000}),
9862 or a range of sizes (such as @samp{4000-72000}).
9863 You can optionally end the list with a zero.
9866 @DefreqList {vs, [@Var{space}]}
9867 @DefreqItem {vs, @t{+}@Var{space}}
9868 @DefreqItem {vs, @t{-}@Var{space}}
9870 @cindex changing vertical line spacing (@code{vs})
9871 @cindex vertical line spacing, changing (@code{vs})
9872 @cindex vertical line spacing register (@code{.v})
9873 Change (increase, decrease) the vertical spacing by @var{space}. The
9874 default scaling indicator is @samp{p}.
9876 If @code{vs} is called without an argument, the vertical spacing is
9877 reset to the previous value before the last call to @code{vs}.
9879 @cindex @code{.V} register, and @code{vs}
9880 @code{gtroff} creates a warning of type @samp{range} if @var{space} is
9881 negative; the vertical spacing is then set to smallest positive value,
9882 the vertical resolution (as given in the @code{.V} register).
9884 Note that @w{@samp{.vs 0}} isn't saved in a diversion since it doesn't
9885 result in a vertical motion. You explicitly have to repeat this command
9886 before inserting the diversion.
9888 The read-only number register @code{.v} contains the current vertical
9889 spacing; it is associated with the current environment
9890 (@pxref{Environments}).
9893 @cindex vertical line spacing, effective value
9894 The effective vertical line spacing consists of four components. Breaking
9895 a line causes the following actions (in the given order).
9899 @cindex extra pre-vertical line space (@code{\x})
9900 @cindex line space, extra pre-vertical (@code{\x})
9901 Move the current point vertically by the @dfn{extra pre-vertical line
9902 space}. This is the minimum value of all @code{\x} escapes with a
9903 negative argument in the current output line.
9906 Move the current point vertically by the vertical line spacing as set with
9907 the @code{vs} request.
9910 Output the current line.
9913 @cindex extra post-vertical line space (@code{\x})
9914 @cindex line space, extra post-vertical (@code{\x})
9915 Move the current point vertically by the @dfn{extra post-vertical line
9916 space}. This is the maximum value of all @code{\x} escapes with a
9917 positive argument in the line which has just been output.
9920 @cindex post-vertical line spacing
9921 @cindex line spacing, post-vertical (@code{pvs})
9922 Move the current point vertically by the @dfn{post-vertical line spacing}
9923 as set with the @code{pvs} request.
9926 @cindex double-spacing (@code{vs}, @code{pvs})
9927 It is usually better to use @code{vs} or @code{pvs} instead of @code{ls}
9928 to produce double-spaced documents: @code{vs} and @code{pvs} have a finer
9929 granularity for the inserted vertical space compared to @code{ls};
9930 furthermore, certain preprocessors assume single-spacing.
9932 @xref{Manipulating Spacing}, for more details on the @code{\x} escape
9933 and the @code{ls} request.
9935 @DefreqList {pvs, [@Var{space}]}
9936 @DefreqItem {pvs, @t{+}@Var{space}}
9937 @DefreqItem {pvs, @t{-}@Var{space}}
9938 @DefregListEnd {.pvs}
9939 @cindex @code{ls} request, alternative to (@code{pvs})
9940 @cindex post-vertical line spacing, changing (@code{pvs})
9941 @cindex post-vertical line spacing register (@code{.pvs})
9942 Change (increase, decrease) the post-vertical spacing by
9943 @var{space}. The default scaling indicator is @samp{p}.
9945 If @code{pvs} is called without an argument, the post-vertical spacing is
9946 reset to the previous value before the last call to @code{pvs}.
9948 @code{gtroff} creates a warning of type @samp{range} if @var{space} is
9949 zero or negative; the vertical spacing is then set to zero.
9951 The read-only number register @code{.pvs} contains the current
9952 post-vertical spacing; it is associated with the current environment
9953 (@pxref{Environments}).
9956 @c ---------------------------------------------------------------------
9958 @node Fractional Type Sizes, , Changing Type Sizes, Sizes
9959 @subsection Fractional Type Sizes
9960 @cindex fractional type sizes
9961 @cindex fractional point sizes
9962 @cindex type sizes, fractional
9963 @cindex point sizes, fractional
9964 @cindex sizes, fractional
9966 @cindex @code{s} unit
9967 @cindex unit, @code{s}
9968 @cindex @code{z} unit
9969 @cindex unit, @code{z}
9970 @cindex @code{ps} request, with fractional type sizes
9971 @cindex @code{cs} request, with fractional type sizes
9972 @cindex @code{tkf} request, with fractional type sizes
9973 @cindex @code{\H}, with fractional type sizes
9974 @cindex @code{\s}, with fractional type sizes
9975 A @dfn{scaled point} is equal to @math{1/@var{sizescale}} points,
9976 where @var{sizescale} is specified in the @file{DESC} file (1@tie{}by
9977 default). There is a new scale indicator @samp{z} which has the
9978 effect of multiplying by @var{sizescale}. Requests and escape
9979 sequences in @code{gtroff} interpret arguments that represent a point
9980 size as being in units of scaled points, but they evaluate each such
9981 argument using a default scale indicator of @samp{z}. Arguments
9982 treated in this way are the argument to the @code{ps} request, the
9983 third argument to the @code{cs} request, the second and fourth
9984 arguments to the @code{tkf} request, the argument to the @code{\H}
9985 escape sequence, and those variants of the @code{\s} escape sequence
9986 that take a numeric expression as their argument (see below).
9988 For example, suppose @var{sizescale} is@tie{}1000; then a scaled point
9989 is equivalent to a millipoint; the request @w{@samp{.ps 10.25}} is
9990 equivalent to @w{@samp{.ps 10.25z}} and thus sets the point size to
9991 10250@tie{}scaled points, which is equal to 10.25@tie{}points.
9993 @code{gtroff} disallows the use of the @samp{z} scale indicator in
9994 instances where it would make no sense, such as a numeric
9995 expression whose default scale indicator was neither @samp{u} nor
9996 @samp{z}. Similarly it would make
9997 no sense to use a scaling indicator other than @samp{z} or @samp{u} in a
9998 numeric expression whose default scale indicator was @samp{z}, and so
9999 @code{gtroff} disallows this as well.
10001 There is also new scale indicator @samp{s} which multiplies by the
10002 number of units in a scaled point. So, for example, @samp{\n[.ps]s} is
10003 equal to @samp{1m}. Be sure not to confuse the @samp{s} and @samp{z}
10007 A read-only number register returning the point size in scaled points.
10009 @code{.ps} is associated with the current environment
10010 (@pxref{Environments}).
10014 @DefregListEnd {.sr}
10015 @cindex last-requested point size registers (@code{.psr}, @code{.sr})
10016 @cindex point size registers, last-requested (@code{.psr}, @code{.sr})
10017 @cindex @code{.ps} register, in comparison with @code{.psr}
10018 @cindex @code{.s} register, in comparison with @code{.sr}
10019 The last-requested point size in scaled points is contained in the
10020 @code{.psr} read-only number register. The last requested point size
10021 in points as a decimal fraction can be found in @code{.sr}. This is a
10022 string-valued read-only number register.
10024 Note that the requested point sizes are device-independent, whereas
10025 the values returned by the @code{.ps} and @code{.s} registers are not.
10026 For example, if a point size of 11@dmn{pt} is requested, and a
10027 @code{sizes} request (or a @code{sizescale} line in a @file{DESC} file)
10028 specifies 10.95@dmn{pt} instead, this value is actually used.
10030 Both registers are associated with the current environment
10031 (@pxref{Environments}).
10034 The @code{\s} escape has the following syntax for working with
10035 fractional type sizes:
10040 Set the point size to @var{n}@tie{}scaled points; @var{n}@tie{}is a numeric
10041 expression with a default scale indicator of @samp{z}.
10044 @itemx \s[-@var{n}]
10045 @itemx \s+[@var{n}]
10046 @itemx \s-[@var{n}]
10047 @itemx \s'+@var{n}'
10048 @itemx \s'-@var{n}'
10049 @itemx \s+'@var{n}'
10050 @itemx \s-'@var{n}'
10051 Increase or or decrease the point size by @var{n}@tie{}scaled points;
10052 @var{n}@tie{}is a numeric expression with a default scale indicator of
10059 @c =====================================================================
10061 @node Strings, Conditionals and Loops, Sizes, gtroff Reference
10065 @code{gtroff} has string variables, which are entirely for user
10066 convenience (i.e.@: there are no built-in strings exept @code{.T}, but
10067 even this is a read-write string variable).
10069 @DefreqList {ds, name [@Var{string}]}
10070 @DefreqItem {ds1, name [@Var{string}]}
10071 @DefescItem {\\*, , n, }
10072 @DefescItem {\\*, @Lparen{}, nm, }
10073 @DefescListEnd {\\*, @Lbrack{}, name arg1 arg2 @dots{}, @Rbrack{}}
10074 @cindex string interpolation (@code{\*})
10075 @cindex string expansion (@code{\*})
10076 @cindex interpolation of strings (@code{\*})
10077 @cindex expansion of strings (@code{\*})
10078 @cindex string arguments
10079 @cindex arguments, of strings
10080 Define and access a string variable @var{name} (one-character
10081 name@tie{}@var{n}, two-character name @var{nm}). If @var{name} already
10082 exists, @code{ds} overwrites the previous definition. Only the syntax form
10083 using brackets can take arguments which are handled identically to
10084 macro arguments; the single exception is that a closing bracket as an
10085 argument must be enclosed in double quotes. @xref{Request and Macro
10086 Arguments}, and @ref{Parameters}.
10091 .ds foo a \\$1 test
10093 This is \*[foo nice].
10094 @result{} This is a nice test.
10097 The @code{\*} escape @dfn{interpolates} (expands in-place) a
10098 previously-defined string variable. To be more precise, the stored
10099 string is pushed onto the input stack which is then parsed by
10100 @code{gtroff}. Similar to number registers, it is possible to nest
10101 strings, i.e. string variables can be called within string variables.
10103 If the string named by the @code{\*} escape does not exist, it is
10104 defined as empty, and a warning of type @samp{mac} is emitted (see
10105 @ref{Debugging}, for more details).
10107 @cindex comments, with @code{ds}
10108 @cindex @code{ds} request, and comments
10109 @strong{Caution:} Unlike other requests, the second argument to the
10110 @code{ds} request takes up the entire line including trailing spaces.
10111 This means that comments on a line with such a request can introduce
10112 unwanted space into a string.
10115 .ds UX \s-1UNIX\s0\u\s-3tm\s0\d \" UNIX trademark
10119 Instead the comment should be put on another line or have the comment
10120 escape adjacent with the end of the string.
10123 .ds UX \s-1UNIX\s0\u\s-3tm\s0\d\" UNIX trademark
10126 @cindex trailing quotes
10127 @cindex quotes, trailing
10128 @cindex leading spaces with @code{ds}
10129 @cindex spaces with @code{ds}
10130 @cindex @code{ds} request, and leading spaces
10131 To produce leading space the string can be started with a double
10132 quote. No trailing quote is needed; in fact, any trailing quote is
10133 included in your string.
10136 .ds sign " Yours in a white wine sauce,
10139 @cindex multi-line strings
10140 @cindex strings, multi-line
10141 @cindex newline character, in strings, escaping
10142 @cindex escaping newline characters, in strings
10143 Strings are not limited to a single line of text. A string can span
10144 several lines by escaping the newlines with a backslash. The
10145 resulting string is stored @emph{without} the newlines.
10148 .ds foo lots and lots \
10149 of text are on these \
10153 It is not possible to have real newlines in a string. To put a single
10154 double quote character into a string, use two consecutive double quote
10157 The @code{ds1} request turns off compatibility mode
10158 while interpreting a string. To be more precise, a @dfn{compatibility
10159 save} input token is inserted at the beginning of the string, and a
10160 @dfn{compatibility restore} input token at the end.
10164 .ds aa The value of xxx is \\n[xxx].
10165 .ds1 bb The value of xxx ix \\n[xxx].
10170 @result{} warning: number register `[' not defined
10171 @result{} The value of xxx is 0xxx].
10173 @result{} The value of xxx ix 12345.
10176 @cindex name space, common, of macros, diversions, and strings
10177 @cindex common name space of macros, diversions, and strings
10178 @cindex macros, shared name space with strings and diversions
10179 @cindex strings, shared name space with macros and diversions
10180 @cindex diversions, shared name space with macros and strings
10181 Strings, macros, and diversions (and boxes) share the same name space.
10182 Internally, even the same mechanism is used to store them. This has
10183 some interesting consequences. For example, it is possible to call a
10184 macro with string syntax and vice versa.
10191 @result{} This is a funny test.
10193 .ds yyy a funny test
10196 @result{} This is a funny test.
10199 Diversions and boxes can be also called with string syntax.
10201 Another consequence is that you can copy one-line diversions or boxes
10209 .ds yyy This is \*[xxx]\c
10211 @result{} @r{This is a }@i{test}.
10215 As the previous example shows, it is possible to store formatted
10216 output in strings. The @code{\c} escape prevents the insertion of an
10217 additional blank line in the output.
10219 Copying diversions longer than a single output line produces
10220 unexpected results.
10229 .ds yyy This is \*[xxx]\c
10231 @result{} test This is a funny.
10234 Usually, it is not predictable whether a diversion contains one or
10235 more output lines, so this mechanism should be avoided. With
10236 @acronym{UNIX} @code{troff}, this was the only solution to strip off a
10237 final newline from a diversion. Another disadvantage is that the
10238 spaces in the copied string are already formatted, making them
10239 unstretchable. This can cause ugly results.
10241 @cindex stripping final newline in diversions
10242 @cindex diversion, stripping final newline
10243 @cindex final newline, stripping in diversions
10244 @cindex newline, final, stripping in diversions
10245 @cindex horizontal space, unformatting
10246 @cindex space, horizontal, unformatting
10247 @cindex unformatting horizontal space
10248 A clean solution to this problem is available in GNU @code{troff},
10249 using the requests @code{chop} to remove the final newline of a
10250 diversion, and @code{unformat} to make the horizontal spaces
10263 @result{} This is a funny test.
10266 @xref{Gtroff Internals}, for more information.
10269 @DefreqList {as, name [@Var{string}]}
10270 @DefreqListEnd {as1, name [@Var{string}]}
10271 @cindex appending to a string (@code{as})
10272 @cindex string, appending (@code{as})
10273 The @code{as} request is similar to @code{ds} but appends @var{string}
10274 to the string stored as @var{name} instead of redefining it. If
10275 @var{name} doesn't exist yet, it is created.
10278 .as sign " with shallots, onions and garlic,
10281 The @code{as1} request is similar to @code{as}, but compatibility mode
10282 is switched off while the appended string is interpreted. To be more
10283 precise, a @dfn{compatibility save} input token is inserted at the
10284 beginning of the appended string, and a @dfn{compatibility restore}
10285 input token at the end.
10288 Rudimentary string manipulation routines are given with the next two
10291 @Defreq {substring, str n1 [@Var{n2}]}
10292 @cindex substring (@code{substring})
10293 Replace the string named @var{str} with the substring
10294 defined by the indices @var{n1} and@tie{}@var{n2}. The first character
10295 in the string has index@tie{}0. If @var{n2} is omitted, it is taken to
10296 be equal to the string's length. If the index value @var{n1} or
10297 @var{n2} is negative, it is counted from the end of the
10298 string, going backwards: The last character has index@tie{}@minus{}1, the
10299 character before the last character has index@tie{}@minus{}2, etc.
10303 .substring xxx 1 -4
10309 @Defreq {length, reg str}
10310 @cindex length of a string (@code{length})
10311 @cindex string, length of (@code{length})
10312 Compute the number of characters of @var{str} and return it in the
10313 number register @var{reg}. If @var{reg} doesn't exist, it is created.
10314 @code{str} is read in copy mode.
10317 .ds xxx abcd\h'3i'efgh
10318 .length yyy \*[xxx]
10324 @Defreq {rn, xx yy}
10325 @cindex renaming request (@code{rn})
10326 @cindex request, renaming (@code{rn})
10327 @cindex renaming macro (@code{rn})
10328 @cindex macro, renaming (@code{rn})
10329 @cindex renaming string (@code{rn})
10330 @cindex string, renaming (@code{rn})
10331 @cindex renaming diversion (@code{rn})
10332 @cindex diversion, renaming (@code{rn})
10333 Rename the request, macro, diversion, or string @var{xx} to @var{yy}.
10337 @cindex removing request (@code{rm})
10338 @cindex request, removing (@code{rm})
10339 @cindex removing macro (@code{rm})
10340 @cindex macro, removing (@code{rm})
10341 @cindex removing string (@code{rm})
10342 @cindex string, removing (@code{rm})
10343 @cindex removing diversion (@code{rm})
10344 @cindex diversion, removing (@code{rm})
10345 Remove the request, macro, diversion, or string @var{xx}. @code{gtroff}
10346 treats subsequent invocations as if the object had never been defined.
10349 @Defreq {als, new old}
10350 @cindex alias, string, creating (@code{als})
10351 @cindex alias, macro, creating (@code{als})
10352 @cindex alias, diversion, creating (@code{als})
10353 @cindex creating alias, for string (@code{als})
10354 @cindex creating alias, for macro (@code{als})
10355 @cindex creating alias, for diversion (@code{als})
10356 @cindex string, creating alias (@code{als})
10357 @cindex macro, creating alias (@code{als})
10358 @cindex diversion, creating alias (@code{als})
10359 Create an alias named @var{new} for the request, string, macro, or
10360 diversion object named @var{old}. The new name and the old name are
10361 exactly equivalent (it is similar to a hard rather than a soft
10362 link). If @var{old} is undefined, @code{gtroff} generates a warning of
10363 type @samp{mac} and ignores the request.
10367 Remove (chop) the last character from the macro, string, or diversion
10368 named @var{xx}. This is useful for removing the newline from the end
10369 of diversions that are to be interpolated as strings. This command
10370 can be used repeatedly; see @ref{Gtroff Internals}, for details on
10371 nodes inserted additionally by @code{gtroff}.
10374 @xref{Identifiers}, and @ref{Comments}.
10377 @c =====================================================================
10379 @node Conditionals and Loops, Writing Macros, Strings, gtroff Reference
10380 @section Conditionals and Loops
10381 @cindex conditionals and loops
10382 @cindex loops and conditionals
10385 * Operators in Conditionals::
10390 @c ---------------------------------------------------------------------
10392 @node Operators in Conditionals, if-else, Conditionals and Loops, Conditionals and Loops
10393 @subsection Operators in Conditionals
10395 @cindex @code{if} request, operators to use with
10396 @cindex @code{while} request, operators to use with
10397 In @code{if} and @code{while} requests, there are several more
10398 operators available:
10403 True if the current page is even or odd numbered (respectively).
10406 True if the document is being processed in nroff mode (i.e., the
10407 @code{.nroff} command has been issued).
10410 True if the document is being processed in troff mode (i.e., the
10411 @code{.troff} command has been issued).
10414 Always false. This condition is for compatibility with other
10415 @code{troff} versions only (identifying a @code{-Tversatec} device).
10417 @item '@var{xxx}'@var{yyy}'
10418 True if the string @var{xxx} is equal to the string @var{yyy}. Other
10419 characters can be used in place of the single quotes; the same set of
10420 delimiters as for the @code{\D} escape is used (@pxref{Escapes}).
10421 @code{gtroff} formats the strings before being compared:
10432 The resulting motions, glyph sizes, and fonts have to
10433 match,@footnote{The created output nodes must be identical.
10434 @xref{Gtroff Internals}.} and not the individual motion, size, and
10435 font requests. In the previous example, @samp{|} and @samp{\fR|\fP}
10436 both result in a roman @samp{|} glyph with the same point size and
10437 at the same location on the page, so the strings are equal. If
10438 @samp{.ft@tie{}I} had been added before the @samp{.ie}, the result
10439 would be ``false'' because (the first) @samp{|} produces an italic
10440 @samp{|} rather than a roman one.
10443 True if there is a number register named @var{xxx}.
10446 True if there is a string, macro, diversion, or request named @var{xxx}.
10449 True if there is a color named @var{xxx}.
10452 True if there is a glyph @var{g} available@footnote{The name of this
10453 conditional operator is a misnomer since it tests names of output
10454 glyphs.}; @var{g} is either an @acronym{ASCII} character or a special
10455 character (@code{\(@var{gg}} or @code{\[@var{ggg}]}); the condition
10456 is also true if @var{g} has been defined by the @code{char} request.
10459 True if a font named @var{font} exists. @var{font} is handled as if it was
10460 opened with the @code{ft} request (this is, font translation and styles are
10461 applied), without actually mounting it.
10463 This test doesn't load the complete font but only its header to verify
10466 @item S @var{style}
10467 True if style @var{style} has been registered. Font translation is applied.
10470 Note that these operators can't be combined with other operators like
10471 @samp{:} or @samp{&}; only a leading @samp{!} (without whitespace
10472 between the exclamation mark and the operator) can be used to negate
10484 A whitespace after @samp{!} always evaluates to zero (this bizarre
10485 behaviour is due to compatibility with @acronym{UNIX} @code{troff}).
10493 @result{} r xxx true
10496 It is possible to omit the whitespace before the argument to the
10497 @samp{r}, @samp{d}, and @samp{c} operators.
10499 @xref{Expressions}.
10501 @c ---------------------------------------------------------------------
10503 @node if-else, while, Operators in Conditionals, Conditionals and Loops
10504 @subsection if-else
10507 @code{gtroff} has if-then-else constructs like other languages, although
10508 the formatting can be painful.
10510 @Defreq {if, expr anything}
10512 Evaluate the expression @var{expr}, and executes @var{anything} (the
10513 remainder of the line) if @var{expr} evaluates to a value greater than
10514 zero (true). @var{anything} is interpreted as though it was on a line
10515 by itself (except that leading spaces are swallowed).
10516 @xref{Expressions}, for more info.
10521 .if ((\n[xxx] == 1) & (\n[yyy] == 2)) true
10526 @Defreq{nop, anything}
10527 Executes @var{anything}.
10528 This is similar to @code{.if@tie{}1}.
10531 @DefreqList {ie, expr anything}
10532 @DefreqListEnd {el, anything}
10533 Use the @code{ie} and @code{el} requests to write an if-then-else.
10534 The first request is the `if' part and the latter is the `else' part.
10537 .ie n .ls 2 \" double-spacing in nroff
10538 .el .ls 1 \" single-spacing in troff
10542 @c there is a bug in makeinfo <= 4.1a: you can't have `@{' as an argument
10545 @c and in 4.2 you still can't use @{ in macros.
10547 @c @DefescList {\@{, , , }
10548 @c @DefescListEnd {\@}, , , }
10549 @deffn Escape @t{\@{}
10550 @deffnx Escape @t{\@}}
10553 @cindex begin of conditional block (@code{\@{})
10554 @cindex end of conditional block (@code{\@}})
10555 @cindex conditional block, begin (@code{\@{})
10556 @cindex conditional block, end (@code{\@}})
10557 @cindex block, conditional, begin (@code{\@{})
10558 @cindex block, condititional, end (@code{\@}})
10559 In many cases, an if (or if-else) construct needs to execute more than
10560 one request. This can be done using the @code{\@{} and @code{\@}}
10561 escapes. The following example shows the possible ways to use these
10562 escapes (note the position of the opening and closing braces).
10577 @xref{Expressions}.
10579 @c ---------------------------------------------------------------------
10581 @node while, , if-else, Conditionals and Loops
10585 @code{gtroff} provides a looping construct using the @code{while}
10586 request, which is used much like the @code{if} (and related) requests.
10588 @Defreq {while, expr anything}
10589 Evaluate the expression @var{expr}, and repeatedly execute
10590 @var{anything} (the remainder of the line) until @var{expr} evaluates
10595 .while (\na < 9) \@{\
10599 @result{} 1, 2, 3, 4, 5, 6, 7, 8, 9, 10
10604 @cindex @code{de} request, and @code{while}
10607 The body of a @code{while} request is treated like the body of a
10608 @code{de} request: @code{gtroff} temporarily stores it in a macro
10609 which is deleted after the loop has been exited. It can considerably
10610 slow down a macro if the body of the @code{while} request (within the
10611 macro) is large. Each time the macro is executed, the @code{while}
10612 body is parsed and stored again as a temporary macro.
10617 . while (\\n[num] > 0) \@{\
10618 . \" many lines of code
10624 @cindex recursive macros
10625 @cindex macros, recursive
10627 The traditional and ofter better solution (@acronym{UNIX} @code{troff}
10628 doesn't have the @code{while} request) is to use a recursive macro
10629 instead which is parsed only once during its definition.
10633 . if (\\n[num] > 0) \@{\
10634 . \" many lines of code
10647 Note that the number of available recursion levels is set to@tie{}1000
10648 (this is a compile-time constant value of @code{gtroff}).
10651 The closing brace of a @code{while} body must end a line.
10656 . while (\n[a] < 10) \@{\
10659 @result{} unbalanced \@{ \@}
10665 @cindex @code{while} request, confusing with @code{br}
10666 @cindex @code{break} request, in a @code{while} loop
10667 @cindex @code{continue} request, in a @code{while} loop
10668 Break out of a @code{while} loop. Be sure not to confuse this with
10669 the @code{br} request (causing a line break).
10672 @Defreq {continue, }
10673 Finish the current iteration of a @code{while} loop, immediately
10674 restarting the next iteration.
10677 @xref{Expressions}.
10680 @c =====================================================================
10682 @node Writing Macros, Page Motions, Conditionals and Loops, gtroff Reference
10683 @section Writing Macros
10684 @cindex writing macros
10685 @cindex macros, writing
10687 A @dfn{macro} is a collection of text and embedded commands which can
10688 be invoked multiple times. Use macros to define common operations.
10690 @DefreqList {de, name [@Var{end}]}
10691 @DefreqItem {de1, name [@Var{end}]}
10692 @DefreqItem {dei, name [@Var{end}]}
10693 @DefreqListEnd {dei1, name [@Var{end}]}
10694 Define a new macro named @var{name}. @code{gtroff} copies subsequent
10695 lines (starting with the next one) into an internal buffer until it
10696 encounters the line @samp{..} (two dots). The optional second
10697 argument to @code{de} changes this to a macro to @samp{.@var{end}}.
10699 There can be whitespace after the first dot in the line containing the
10700 ending token (either @samp{.} or macro @samp{@var{end}}).
10702 Here a small example macro called @samp{P} which causes a break and
10703 inserts some vertical space. It could be used to separate paragraphs.
10712 The following example defines a macro within another. Remember that
10713 expansion must be protected twice; once for reading the macro and
10714 once for executing.
10717 \# a dummy macro to avoid a warning
10723 . nop \f[B]Hallo \\\\$1!\f[]
10729 @result{} @b{Hallo Joe!}
10733 Since @code{\f} has no expansion, it isn't necessary to protect its
10734 backslash. Had we defined another macro within @code{bar} which takes
10735 a parameter, eight backslashes would be necessary before @samp{$1}.
10737 The @code{de1} request turns off compatibility mode
10738 while executing the macro. On entry, the current compatibility mode
10739 is saved and restored at exit.
10745 The value of xxx is \\n[xxx].
10748 The value of xxx ix \\n[xxx].
10754 @result{} warning: number register `[' not defined
10755 @result{} The value of xxx is 0xxx].
10757 @result{} The value of xxx ix 12345.
10760 The @code{dei} request defines a macro indirectly.
10761 That is, it expands strings whose names
10762 are @var{name} or @var{end} before performing the append.
10779 The @code{dei1} request is similar to @code{dei} but with compatibility
10780 mode switched off during execution of the defined macro.
10782 If compatibility mode is on, @code{de} (and @code{dei}) behave similar to
10783 @code{de1} (and @code{dei1}): A `compatibility save' token is inserted at
10784 the beginning, and a `compatibility restore' token at the end, with
10785 compatibility mode switched on during execution. @xref{Gtroff Internals},
10786 for more information on switching compatibility mode on and off in a
10790 Using @file{trace.tmac}, you can trace calls to @code{de} and @code{de1}.
10792 Note that macro identifiers are shared with identifiers for strings and
10796 @DefreqList {am, name [@Var{end}]}
10797 @DefreqItem {am1, name [@Var{end}]}
10798 @DefreqItem {ami, name [@Var{end}]}
10799 @DefreqListEnd {ami1, name [@Var{end}]}
10800 @cindex appending to a macro (@code{am})
10801 @cindex macro, appending (@code{am})
10802 Works similarly to @code{de} except it appends onto the macro named
10803 @var{name}. So, to make the previously defined @samp{P} macro actually
10804 do indented instead of block paragraphs, add the necessary code to the
10805 existing macro like this:
10813 The @code{am1} request turns off compatibility mode
10814 while executing the appended macro piece. To be more precise, a
10815 @dfn{compatibility save} input token is inserted at the beginning of
10816 the appended code, and a @dfn{compatibility restore} input token at
10819 The @code{ami} request appends indirectly,
10820 meaning that @code{gtroff} expands strings whose names
10821 are @var{name} or @var{end} before performing the append.
10823 The @code{ami1} request is similar to @code{ami} but compatibility mode
10824 is switched off during execution of the defined macro.
10827 Using @file{trace.tmac}, you can trace calls to @code{am} and @code{am1}.
10830 @xref{Strings}, for the @code{als} request to rename a macro.
10832 The @code{de}, @code{am}, @code{di}, @code{da}, @code{ds}, and
10833 @code{as} requests (together with its variants) only create a new object
10834 if the name of the macro, diversion or string diversion is currently
10835 undefined or if it is defined to be a request; normally they modify the
10836 value of an existing object.
10838 @Defreq {return, [@Var{anything}]}
10839 Exit a macro, immediately returning to the caller.
10841 If called with an argument, exit twice, namely the current macro and the
10842 macro one level higher. This is used to define a wrapper macro for
10843 @code{return} in @file{trace.tmac}.
10851 @c ---------------------------------------------------------------------
10853 @node Copy-in Mode, Parameters, Writing Macros, Writing Macros
10854 @subsection Copy-in Mode
10855 @cindex copy-in mode
10856 @cindex mode, copy-in
10858 @cindex @code{\n}, when reading text for a macro
10859 @cindex @code{\$}, when reading text for a macro
10860 @cindex @code{\*}, when reading text for a macro
10861 @cindex @code{\\}, when reading text for a macro
10862 @cindex \@key{RET}, when reading text for a macro
10863 When @code{gtroff} reads in the text for a macro, string, or diversion,
10864 it copies the text (including request lines, but excluding escapes) into
10865 an internal buffer. Escapes are converted into an internal form,
10866 except for @code{\n}, @code{\$}, @code{\*}, @code{\\} and
10867 @code{\@key{RET}} which are evaluated and inserted into the text where
10868 the escape was located. This is known as @dfn{copy-in} mode or
10871 What this means is that you can specify when these escapes are to be
10872 evaluated (either at copy-in time or at the time of use) by insulating
10873 the escapes with an extra backslash. Compare this to the @code{\def}
10874 and @code{\edef} commands in @TeX{}.
10876 The following example prints the numbers 20 and@tie{}10:
10888 @c ---------------------------------------------------------------------
10890 @node Parameters, , Copy-in Mode, Writing Macros
10891 @subsection Parameters
10894 The arguments to a macro or string can be examined using a variety of
10898 @cindex number of arguments register (@code{.$})
10899 The number of arguments passed to a macro or string. This is a read-only
10902 Note that the @code{shift} request can change its value.
10905 Any individual argument can be retrieved with one of the following
10908 @DefescList {\\$, , n, }
10909 @DefescItem {\\$, @Lparen{}, nn, }
10910 @DefescListEnd {\\$, @Lbrack{}, nnn, @Rbrack{}}
10911 @cindex copy-in mode, and macro arguments
10912 @cindex macro, arguments (@code{\$})
10913 @cindex arguments, macro (@code{\$})
10914 Retrieve the @var{n}@dmn{th}, @var{nn}@dmn{th} or @var{nnn}@dmn{th}
10915 argument. As usual, the first form only accepts a single number
10916 (larger than zero), the second a two-digit number (larger or equal
10917 to@tie{}10), and the third any positive integer value (larger
10918 than zero). Macros and strings can have an unlimited number of arguments.
10919 Note that due to copy-in mode, use two backslashes on these in actual use
10920 to prevent interpolation until the macro is actually invoked.
10923 @Defreq {shift, [@Var{n}]}
10924 Shift the arguments 1@tie{}position, or as
10925 many positions as specified by its argument. After executing this
10926 request, argument@tie{}@var{i} becomes argument @math{@var{i}-@var{n}};
10927 arguments 1 to@tie{}@var{n} are no longer available. Shifting by
10928 negative amounts is currently undefined.
10930 The register @code{.$} is adjusted accordingly.
10933 @DefescList {\\$*, , , }
10934 @DefescListEnd {\\$@@, , , }
10935 In some cases it is convenient to use all of the arguments at once (for
10936 example, to pass the arguments along to another macro). The @code{\$*}
10937 escape concatenates all the arguments separated by spaces. A
10938 similar escape is @code{\$@@}, which concatenates all the
10939 arguments with each surrounded by double quotes, and separated by
10940 spaces. If not in compatibility mode, the input level of double quotes
10941 is preserved (see @ref{Request and Macro Arguments}).
10944 @Defesc {\\$0, , , }
10945 @cindex macro name register (@code{\$0})
10946 @cindex @code{als} request, and @code{\$0}
10947 The name used to invoke the current macro.
10948 The @code{als} request can make a macro have more than one name.
10953 . if \\n[error] \@{\
10954 . tm \\$0: Houston, we have a problem.
10959 .als foo generic-macro
10960 .als bar generic-macro
10964 @xref{Request and Macro Arguments}.
10967 @c =====================================================================
10969 @node Page Motions, Drawing Requests, Writing Macros, gtroff Reference
10970 @section Page Motions
10971 @cindex page motions
10972 @cindex motions, page
10974 @xref{Manipulating Spacing}, for a discussion of the main request for
10975 vertical motion, @code{sp}.
10977 @DefreqList {mk, [@Var{reg}]}
10978 @DefreqListEnd {rt, [@Var{dist}]}
10979 @cindex marking vertical page location (@code{mk})
10980 @cindex page location, vertical, marking (@code{mk})
10981 @cindex location, vertical, page, marking (@code{mk})
10982 @cindex vertical page location, marking (@code{mk})
10983 @cindex returning to marked vertical page location (@code{rt})
10984 @cindex page location, vertical, returning to marked (@code{rt})
10985 @cindex location, vertical, page, returning to marked (@code{rt})
10986 @cindex vertical page location, returning to marked (@code{rt})
10987 The request @code{mk} can be used to mark a location on a page, for
10988 movement to later. This request takes a register name as an argument
10989 in which to store the current page location. With no argument it
10990 stores the location in an internal register. The results of this can
10991 be used later by the @code{rt} or the @code{sp} request (or the
10994 The @code{rt} request returns @emph{upwards} to the location marked
10995 with the last @code{mk} request. If used with an argument, return to
10996 a position which distance from the top of the page is @var{dist} (no
10997 previous call to @code{mk} is necessary in this case). Default scaling
10998 indicator is @samp{v}.
11000 Here a primitive solution for a two-column macro.
11003 .nr column-length 1.5i
11005 .nr bottom-margin 1m
11012 . ll \\n[column-length]u
11013 . wh -\\n[bottom-margin]u 2c-trap
11020 . ie \\n[right-side] \@{\
11022 . po -(\\n[column-length]u + \\n[column-gap]u)
11024 . wh -\\n[bottom-margin]u
11027 . \" switch to right side
11029 . po +(\\n[column-length]u + \\n[column-gap]u)
11038 This is a small test which shows how the
11039 rt request works in combination with mk.
11042 Starting here, text is typeset in two columns.
11043 Note that this implementation isn't robust
11044 and thus not suited for a real two-column
11051 This is a small test which shows how the
11052 rt request works in combination with mk.
11054 Starting here, isn't robust
11055 text is typeset and thus not
11056 in two columns. suited for a
11057 Note that this real two-column
11058 implementation macro.
11062 The following escapes give fine control of movements about the page.
11064 @Defesc {\\v, ', e, '}
11065 @cindex vertical motion (@code{\v})
11066 @cindex motion, vertical (@code{\v})
11067 Move vertically, usually from the current location on the page (if no
11068 absolute position operator @samp{|} is used). The
11069 argument@tie{}@var{e} specifies the distance to move; positive is
11070 downwards and negative upwards. The default scaling indicator for this
11071 escape is @samp{v}. Beware, however, that @code{gtroff} continues text
11072 processing at the point where the motion ends, so you should always
11073 balance motions to avoid interference with text processing.
11075 @code{\v} doesn't trigger a trap. This can be quite useful; for example,
11076 consider a page bottom trap macro which prints a marker in the margin to
11077 indicate continuation of a footnote or something similar.
11080 There are some special-case escapes for vertical motion.
11082 @Defesc {\\r, , , }
11083 Move upwards@tie{}1@dmn{v}.
11086 @Defesc {\\u, , , }
11087 Move upwards@tie{}.5@dmn{v}.
11090 @Defesc {\\d, , , }
11091 Move down@tie{}.5@dmn{v}.
11094 @Defesc {\\h, ', e, '}
11095 @cindex inserting horizontal space (@code{\h})
11096 @cindex horizontal space (@code{\h})
11097 @cindex space, horizontal (@code{\h})
11098 @cindex horizontal motion (@code{\h})
11099 @cindex motion, horizontal (@code{\h})
11100 Move horizontally, usually from the current location (if no absolute
11101 position operator @samp{|} is used). The expression@tie{}@var{e}
11102 indicates how far to move: positive is rightwards and negative
11103 leftwards. The default scaling indicator for this escape is @samp{m}.
11105 This horizontal space is not discarded at the end of a line. To insert
11106 discardable space of a certain length use the @code{ss} request.
11109 There are a number of special-case escapes for horizontal motion.
11111 @Defesc {\\@key{SP}, , , }
11112 @cindex space, unbreakable
11113 @cindex unbreakable space
11114 An unbreakable and unpaddable (i.e.@: not expanded during filling)
11115 space. (Note: This is a backslash followed by a space.)
11118 @Defesc {\\~, , , }
11119 An unbreakable space that stretches like a normal inter-word space
11120 when a line is adjusted.
11123 @Defesc {\\|, , , }
11124 A 1/6@dmn{th} em space. Ignored for TTY output devices (rounded to
11128 @Defesc {\\^, , , }
11129 A 1/12@dmn{th} em space. Ignored for TTY output devices (rounded to
11133 @Defesc {\\0, , , }
11134 @cindex space, width of a digit (@code{\0})
11135 @cindex digit width space (@code{\0})
11136 A space the size of a digit.
11139 The following string sets the @TeX{} logo:
11142 .ds TeX T\h'-.1667m'\v'.224m'E\v'-.224m'\h'-.125m'X
11145 @DefescList {\\w, ', text, '}
11152 @DefregListEnd {skw}
11153 @cindex width escape (@code{\w})
11154 Return the width of the specified @var{text} in basic units.
11155 This allows horizontal movement based on the width of some
11156 arbitrary text (e.g.@: given as an argument to a macro).
11159 The length of the string `abc' is \w'abc'u.
11160 @result{} The length of the string `abc' is 72u.
11163 Font changes may occur in @var{text} which don't affect current
11166 After use, @code{\w} sets several registers:
11171 The highest and lowest point of the baseline, respectively, in @var{text}.
11175 Like the @code{st} and @code{sb} registers, but takes account of the
11176 heights and depths of glyphs. With other words, this gives the
11177 highest and lowest point of @var{text}. Values below the baseline are
11181 Defines the kinds of glyphs occurring in @var{text}:
11185 only short glyphs, no descenders or tall glyphs.
11188 at least one descender.
11191 at least one tall glyph.
11194 at least one each of a descender and a tall glyph.
11198 The amount of horizontal space (possibly negative) that should be added
11199 to the last glyph before a subscript.
11202 How far to right of the center of the last glyph in the @code{\w}
11203 argument, the center of an accent from a roman font should be placed
11208 @DefescList {\\k, , p, }
11209 @DefescItem {\\k, @Lparen{}, ps, }
11210 @DefescListEnd {\\k, @Lbrack{}, position, @Rbrack{}}
11211 @cindex saving horizontal input line position (@code{\k})
11212 @cindex horizontal input line position, saving (@code{\k})
11213 @cindex input line position, horizontal, saving (@code{\k})
11214 @cindex position, horizontal input line, saving (@code{\k})
11215 @cindex line, input, horizontal position, saving (@code{\k})
11216 Store the current horizontal position in the @emph{input} line in
11217 number register with name @var{position} (one-character name@tie{}@var{p},
11218 two-character name @var{ps}). Use this, for example, to return to the
11219 beginning of a string for highlighting or other decoration.
11223 @cindex horizontal input line position register (@code{hp})
11224 @cindex input line, horizontal position, register (@code{hp})
11225 @cindex position, horizontal, in input line, register (@code{hp})
11226 @cindex line, input, horizontal position, register (@code{hp})
11227 The current horizontal position at the input line.
11231 @cindex horizontal output line position register (@code{.k})
11232 @cindex output line, horizontal position, register (@code{.k})
11233 @cindex position, horizontal, in output line, register (@code{.k})
11234 @cindex line, output, horizontal position, register (@code{.k})
11235 A read-only number register containing the current horizontal output
11236 position (relative to the current indentation).
11239 @Defesc {\\o, ', abc, '}
11240 @cindex overstriking glyphs (@code{\o})
11241 @cindex glyphs, overstriking (@code{\o})
11242 Overstrike glyphs @var{a}, @var{b}, @var{c}, @dots{}; the glyphs
11243 are centered, and the resulting spacing is the largest width of the
11247 @Defesc {\\z, , g, , }
11248 @cindex zero-width printing (@code{\z}, @code{\Z})
11249 @cindex printing, zero-width (@code{\z}, @code{\Z})
11250 Print glyph @var{g} with zero width, i.e., without spacing. Use
11251 this to overstrike glyphs left-aligned.
11254 @Defesc {\\Z, ', anything, '}
11255 @cindex zero-width printing (@code{\z}, @code{\Z})
11256 @cindex printing, zero-width (@code{\z}, @code{\Z})
11257 Print @var{anything}, then restore the horizontal and vertical position.
11258 The argument may not contain tabs or leaders.
11260 The following is an example of a strike-through macro:
11265 \Z@@\v'-.25m'\l'\\n[ww]u'@@\\$1
11270 an actual emergency!
11275 @c =====================================================================
11277 @node Drawing Requests, Traps, Page Motions, gtroff Reference
11278 @section Drawing Requests
11279 @cindex drawing requests
11280 @cindex requests for drawing
11282 @code{gtroff} provides a number of ways to draw lines and other figures
11283 on the page. Used in combination with the page motion commands (see
11284 @ref{Page Motions}, for more info), a wide variety of figures can be
11285 drawn. However, for complex drawings these operations can be quite
11286 cumbersome, and it may be wise to use graphic preprocessors like
11287 @code{gpic} or @code{ggrn}. @xref{gpic}, and @ref{ggrn}, for more
11290 All drawing is done via escapes.
11292 @DefescList {\\l, ', l, '}
11293 @DefescListEnd {\\l, ', lg, '}
11294 @cindex drawing horizontal lines (@code{\l})
11295 @cindex horizontal line, drawing (@code{\l})
11296 @cindex line, horizontal, drawing (@code{\l})
11297 Draw a line horizontally. @var{l} is the length of the line to be
11298 drawn. If it is positive, start the line at the current location and
11299 draw to the right; its end point is the new current location. Negative
11300 values are handled differently: The line starts at the current location
11301 and draws to the left, but the current location doesn't move.
11303 @var{l} can also be specified absolutely (i.e.@: with a leading
11304 @samp{|}) which draws back to the beginning of the input line.
11305 Default scaling indicator is @samp{m}.
11307 @cindex underscore glyph (@code{\[ru]})
11308 @cindex glyph, underscore (@code{\[ru]})
11309 @cindex line drawing glyph
11310 @cindex glyph, for line drawing
11311 The optional second parameter@tie{}@var{g} is a glyph to draw the line
11312 with. If this second argument is not specified, @code{gtroff} uses
11313 the underscore glyph, @code{\[ru]}.
11315 @cindex zero width space character (@code{\&})
11316 @cindex character, zero width space (@code{\&})
11317 @cindex space character, zero width (@code{\&})
11318 To separate the two arguments (to prevent @code{gtroff} from
11319 interpreting a drawing glyph as a scaling indicator if the glyph is
11320 represented by a single character) use @code{\&}.
11322 Here a small useful example:
11326 \[br]\\$*\[br]\l'|0\[rn]'\l'|0\[ul]'
11331 Note that this works by outputting a box rule (a vertical line), then
11332 the text given as an argument and then another box rule. Finally, the
11333 line drawing escapes both draw from the current location to the
11334 beginning of the @emph{input} line -- this works because the line
11335 length is negative, not moving the current point.
11338 @DefescList {\\L, ', l, '}
11339 @DefescListEnd {\\L, ', lg, '}
11340 @cindex drawing vertical lines (@code{\L})
11341 @cindex vertical line drawing (@code{\L})
11342 @cindex line, vertical, drawing (@code{\L})
11343 @cindex line drawing glyph
11344 @cindex glyph for line drawing
11345 @cindex box rule glyph (@code{\[br]})
11346 @cindex glyph, box rule (@code{\[br]})
11347 Draw vertical lines. Its parameters are
11348 similar to the @code{\l} escape, except that the default scaling
11349 indicator is @samp{v}. The movement is downwards for positive values,
11350 and upwards for negative values. The default glyph is the box rule
11351 glyph, @code{\[br]}. As with the vertical motion escapes, text
11352 processing blindly continues where the line ends.
11355 This is a \L'3v'test.
11359 Here the result, produced with @code{grotty}.
11369 @Defesc {\\D, ', command arg @dots{}, '}
11370 The @code{\D} escape provides a variety of drawing functions.
11371 Note that on character devices, only vertical and horizontal lines are
11372 supported within @code{grotty}; other devices may only support a subset
11373 of the available drawing functions.
11375 The default scaling indicator for all subcommands of @code{\D} is
11376 @samp{m} for horizontal distances and @samp{v} for vertical ones.
11377 Exceptions are @w{@code{\D'f @dots{}'}} and @w{@code{\D't @dots{}'}}
11378 which use @code{u} as the default, and @w{@code{\D'F@var{x} @dots{}'}}
11379 which arguments are treated similar to the @code{defcolor} request.
11382 @item \D'l @var{dx} @var{dy}'
11383 @cindex line, drawing (@w{@code{\D'l @dots{}'}})
11384 @cindex drawing a line (@w{@code{\D'l @dots{}'}})
11385 Draw a line from the current location to the relative point specified by
11386 (@var{dx},@var{dy}), where positive values mean down and right,
11387 respectively. The end point of the line is the new current location.
11389 The following example is a macro for creating a box around a text string;
11390 for simplicity, the box margin is taken as a fixed value, 0.2@dmn{m}.
11396 \h'-.2m'\v'(.2m - \\n[rsb]u)'\
11397 \D'l 0 -(\\n[rst]u - \\n[rsb]u + .4m)'\
11398 \D'l (\\n[@@wd]u + .4m) 0'\
11399 \D'l 0 (\\n[rst]u - \\n[rsb]u + .4m)'\
11400 \D'l -(\\n[@@wd]u + .4m) 0'\
11401 \h'.2m'\v'-(.2m - \\n[rsb]u)'\
11408 First, the width of the string is stored in register @code{@@wd}. Then,
11409 four lines are drawn to form a box, properly offset by the box margin.
11410 The registers @code{rst} and @code{rsb} are set by the @code{\w} escape,
11411 containing the largest height and depth of the whole string.
11413 @item \D'c @var{d}'
11414 @cindex circle, drawing (@w{@code{\D'c @dots{}'}})
11415 @cindex drawing a circle (@w{@code{\D'c @dots{}'}})
11416 Draw a circle with a diameter of@tie{}@var{d} with the leftmost point at the
11417 current position. After drawing, the current location is positioned at the
11418 rightmost point of the circle.
11420 @item \D'C @var{d}'
11421 @cindex circle, solid, drawing (@w{@code{\D'C @dots{}'}})
11422 @cindex drawing a solid circle (@w{@code{\D'C @dots{}'}})
11423 @cindex solid circle, drawing (@w{@code{\D'C @dots{}'}})
11424 Draw a solid circle with the same parameters and behaviour as an outlined
11425 circle. No outline is drawn.
11427 @item \D'e @var{x} @var{y}'
11428 @cindex drawing an ellipse (@w{@code{\D'e @dots{}'}})
11429 @cindex ellipse, drawing (@w{@code{\D'e @dots{}'}})
11430 Draw an ellipse with a horizontal diameter of @var{x} and a vertical
11431 diameter of @var{y} with the leftmost point at the current position.
11432 After drawing, the current location is positioned at the rightmost point of
11435 @item \D'E @var{x} @var{y}'
11436 @cindex ellipse, solid, drawing (@w{@code{\D'E @dots{}'}})
11437 @cindex drawing a solid ellipse (@w{@code{\D'E @dots{}'}})
11438 @cindex solid ellipse, drawing (@w{@code{\D'E @dots{}'}})
11439 Draw a solid ellipse with the same parameters and behaviour as an
11440 outlined ellipse. No outline is drawn.
11442 @item \D'a @var{dx1} @var{dy1} @var{dx2} @var{dy2}'
11443 @cindex arc, drawing (@w{@code{\D'a @dots{}'}})
11444 @cindex drawing an arc (@w{@code{\D'a @dots{}'}})
11445 Draw an arc clockwise from the current location through the two
11446 specified relative locations (@var{dx1},@var{dy1}) and
11447 (@var{dx2},@var{dy2}). The coordinates of the first point are relative
11448 to the current position, and the coordinates of the second point are
11449 relative to the first point. After drawing, the current position is moved
11450 to the final point of the arc.
11452 @item \D'~ @var{dx1} @var{dy1} @var{dx2} @var{dy2} @dots{}'
11453 @cindex drawing a spline (@w{@code{\D'~ @dots{}'}})
11454 @cindex spline, drawing (@w{@code{\D'~ @dots{}'}})
11455 Draw a spline from the current location to the relative point
11456 (@var{dx1},@var{dy1}) and then to (@var{dx2},@var{dy2}), and so on.
11457 The current position is moved to the terminal point of the drawn curve.
11459 @item \D'f @var{n}'
11460 @cindex gray shading (@w{@code{\D'f @dots{}'}})
11461 @cindex shading filled objects (@w{@code{\D'f @dots{}'}})
11462 Set the shade of gray to be used for filling solid objects to@tie{}@var{n};
11463 @var{n}@tie{}must be an integer between 0 and@tie{}1000, where 0
11464 corresponds solid white and 1000 to solid black, and values in between
11465 correspond to intermediate shades of gray. This applies only to solid
11466 circles, solid ellipses, and solid polygons. By default, a level of
11469 Despite of being silly, the current point is moved horizontally to the
11470 right by@tie{}@var{n}.
11472 @cindex @w{@code{\D'f @dots{}'}} and horizontal resolution
11473 Don't use this command! It has the serious drawback that it will be
11474 always rounded to the next integer multiple of the horizontal resolution
11475 (the value of the @code{hor} keyword in the @file{DESC} file). Use
11476 @code{\M} (@pxref{Colors}) or @w{@code{\D'Fg @dots{}'}} instead.
11478 @item \D'p @var{dx1} @var{dy1} @var{dx2} @var{dy2} @dots{}'
11479 @cindex drawing a polygon (@w{@code{\D'p @dots{}'}})
11480 @cindex polygon, drawing (@w{@code{\D'p @dots{}'}})
11481 Draw a polygon from the current location to the relative position
11482 (@var{dx1},@var{dy1}) and then to (@var{dx2},@var{dy2}) and so on.
11483 When the specified data points are exhausted, a line is drawn back
11484 to the starting point. The current position is changed by adding the
11485 sum of all arguments with odd index to the actual horizontal position and
11486 the even ones to the vertical position.
11488 @item \D'P @var{dx1} @var{dy1} @var{dx2} @var{dy2} @dots{}'
11489 @cindex polygon, solid, drawing (@w{@code{\D'P @dots{}'}})
11490 @cindex drawing a solid polygon (@w{@code{\D'P @dots{}'}})
11491 @cindex solid polygon, drawing (@w{@code{\D'P @dots{}'}})
11492 Draw a solid polygon with the same parameters and behaviour as an
11493 outlined polygon. No outline is drawn.
11495 Here a better variant of the box macro to fill the box with some color.
11496 Note that the box must be drawn before the text since colors in
11497 @code{gtroff} are not transparent; the filled polygon would hide the
11504 \h'-.2m'\v'(.2m - \\n[rsb]u)'\
11506 \D'P 0 -(\\n[rst]u - \\n[rsb]u + .4m) \
11507 (\\n[@@wd]u + .4m) 0 \
11508 0 (\\n[rst]u - \\n[rsb]u + .4m) \
11509 -(\\n[@@wd]u + .4m) 0'\
11510 \h'.2m'\v'-(.2m - \\n[rsb]u)'\
11517 @item \D't @var{n}'
11518 @cindex line thickness (@w{@code{\D't @dots{}'}})
11519 @cindex thickness of lines (@w{@code{\D't @dots{}'}})
11520 Set the current line thickness to @var{n}@tie{}machine units. A value of
11521 zero selects the smallest available line thickness. A negative value
11522 makes the line thickness proportional to the current point size (this is
11523 the default behaviour of @acronym{AT&T} @code{troff}).
11525 Despite of being silly, the current point is moved horizontally to the
11526 right by@tie{}@var{n}.
11528 @item \D'F@var{scheme} @var{color_components}'
11529 @cindex unnamed fill colors (@code{\D'F@dots{}'})
11530 @cindex fill colors, unnamed (@code{\D'F@dots{}'})
11531 @cindex colors, fill, unnamed (@code{\D'F@dots{}'})
11532 Change current fill color. @var{scheme} is a single letter denoting the
11533 color scheme: @samp{r} (rgb), @samp{c} (cmy), @samp{k} (cmyk), @samp{g}
11534 (gray), or @samp{d} (default color). The color components use exactly
11535 the same syntax as in the @code{defcolor} request (@pxref{Colors}); the
11536 command @code{\D'Fd'} doesn't take an argument.
11538 @emph{No} position changing!
11544 \D'Fg .3' \" same gray as \D'f 700'
11545 \D'Fr #0000ff' \" blue
11549 @xref{Graphics Commands}.
11551 @Defesc {\\b, ', string, '}
11552 @cindex pile, glyph (@code{\b})
11553 @cindex glyph pile (@code{\b})
11554 @cindex stacking glyphs (@code{\b})
11555 @dfn{Pile} a sequence of glyphs vertically, and center it vertically
11556 on the current line. Use it to build large brackets and braces.
11558 Here an example how to create a large opening brace:
11561 \b'\[lt]\[bv]\[lk]\[bv]\[lb]'
11564 @cindex @code{\b}, limitations
11565 @cindex limitations of @code{\b} escape
11566 The first glyph is on the top, the last glyph in @var{string} is
11567 at the bottom. Note that @code{gtroff} separates the glyphs
11568 vertically by 1@dmn{m}, and the whole object is centered 0.5@dmn{m}
11569 above the current baseline; the largest glyph width is used as the
11570 width for the whole object. This rather unflexible positioning
11571 algorithm doesn't work with @option{-Tdvi} since the bracket pieces vary
11572 in height for this device. Instead, use the @code{eqn} preprocessor.
11574 @xref{Manipulating Spacing}, how to adjust the vertical spacing with
11575 the @code{\x} escape.
11579 @c =====================================================================
11581 @node Traps, Diversions, Drawing Requests, gtroff Reference
11585 @dfn{Traps} are locations, which, when reached, call a specified
11586 macro. These traps can occur at a given location on the page, at a
11587 given location in the current diversion, at a blank line,
11588 after a certain number of input lines, or at the end of input.
11590 @cindex planting a trap
11591 @cindex trap, planting
11592 Setting a trap is also called @dfn{planting}.
11593 @cindex trap, springing
11594 @cindex springing a trap
11595 It is also said that a trap is @dfn{sprung} if the associated macro
11599 * Page Location Traps::
11600 * Diversion Traps::
11601 * Input Line Traps::
11602 * Blank Line Traps::
11603 * End-of-input Traps::
11606 @c ---------------------------------------------------------------------
11608 @node Page Location Traps, Diversion Traps, Traps, Traps
11609 @subsection Page Location Traps
11610 @cindex page location traps
11611 @cindex traps, page location
11613 @dfn{Page location traps} perform an action when @code{gtroff}
11614 reaches or passes a certain vertical location on the page. Page
11615 location traps have a variety of purposes, including:
11619 setting headers and footers
11622 setting body text in multiple columns
11628 @DefreqList {vpt, flag}
11629 @DefregListEnd {.vpt}
11630 @cindex enabling vertical position traps (@code{vpt})
11631 @cindex vertical position traps, enabling (@code{vpt})
11632 @cindex vertical position trap enable register (@code{.vpt})
11633 Enable vertical position traps if @var{flag} is non-zero, or disables
11634 them otherwise. Vertical position traps are traps set by the @code{wh}
11635 or @code{dt} requests. Traps set by the @code{it} request are not
11636 vertical position traps. The parameter that controls whether vertical
11637 position traps are enabled is global. Initially vertical position traps
11638 are enabled. The current setting of this is available in the
11639 @code{.vpt} read-only number register.
11641 Note that a page can't be ejected if @code{vpt} is set to zero.
11644 @Defreq {wh, dist [@Var{macro}]}
11645 Set a page location trap. Non-negative values for @var{dist} set
11646 the trap relative to the top of the page; negative values set
11647 the trap relative to the bottom of the page. Default scaling
11648 indicator is @samp{v}.
11650 @var{macro} is the name of the macro to execute when the
11651 trap is sprung. If @var{macro} is missing, remove the first trap
11652 (if any) at @var{dist}.
11654 @cindex page headers
11655 @cindex page footers
11658 The following is a simple example of how many macro packages
11659 set headers and footers.
11662 .de hd \" Page header
11668 .de fo \" Page footer
11674 .wh 0 hd \" trap at top of the page
11675 .wh -1i fo \" trap one inch from bottom
11678 A trap at or below the bottom of the page is ignored; it can be made
11679 active by either moving it up or increasing the page length so that the
11680 trap is on the page.
11682 It is possible to have more than one trap at the same location; to do so,
11683 the traps must be defined at different locations, then moved together with
11684 the @code{ch} request; otherwise the second trap would replace the first
11685 one. Earlier defined traps hide later defined traps if moved to the same
11686 position (the many empty lines caused by the @code{bp} request are omitted
11687 in the following example):
11720 @cindex distance to next trap register (@code{.t})
11721 @cindex trap, distance, register (@code{.t})
11722 A read-only number register holding the distance to the next trap.
11724 If there are no traps between the current position and the bottom of the
11725 page, it contains the distance to the page bottom. In a diversion, the
11726 distance to the page bottom is infinite (the returned value is the biggest
11727 integer which can be represented in @code{groff}) if there are no diversion
11731 @Defreq {ch, macro [@Var{dist}]}
11732 @cindex changing trap location (@code{ch})
11733 @cindex trap, changing location (@code{ch})
11734 Change the location of a trap.
11735 The first argument is the name of the macro to be invoked at
11736 the trap, and the second argument is the new location for the trap
11737 (note that the parameters are specified in opposite order as in the
11738 @code{wh} request). This is useful for building up footnotes in a
11739 diversion to allow more space at the bottom of the page for them.
11741 Default scaling indicator for @var{dist} is @samp{v}. If @var{dist}
11742 is missing, the trap is removed.
11748 ... (simplified) footnote example ...
11754 The read-only number register @code{.ne} contains the amount of space
11755 that was needed in the last @code{ne} request that caused a trap to be
11756 sprung. Useful in conjunction with the @code{.trunc} register.
11757 @xref{Page Control}, for more information.
11759 Since the @code{.ne} register is only set by traps it doesn't make
11760 much sense to use it outside of trap macros.
11764 @cindex @code{ne} request, and the @code{.trunc} register
11765 @cindex truncated vertical space register (@code{.trunc})
11766 A read-only register containing the amount of vertical space truncated
11767 by the most recently sprung vertical position trap, or, if the trap was
11768 sprung by an @code{ne} request, minus the amount of vertical motion
11769 produced by the @code{ne} request. In other words, at the point a trap
11770 is sprung, it represents the difference of what the vertical position
11771 would have been but for the trap, and what the vertical position
11774 Since the @code{.trunc} register is only set by traps it doesn't make
11775 much sense to use it outside of trap macros.
11779 @cindex @code{bp} request, and traps (@code{.pe})
11780 @cindex traps, sprung by @code{bp} request (@code{.pe})
11781 @cindex page ejecting register (@code{.pe})
11782 A read-only register which is set to@tie{}1 while a page is ejected with
11783 the @code{bp} request (or by the end of input).
11785 Outside of traps this register is always zero. In the following example,
11786 only the second call to@tie{}@code{x} is caused by @code{bp}.
11807 @cindex diversions, and traps
11808 @cindex traps, and diversions
11809 An important fact to consider while designing macros is that diversions and
11810 traps do not interact normally. For example, if a trap invokes a header
11811 macro (while outputting a diversion) which tries to change the font on the
11812 current page, the effect will not be visible before the diversion has
11813 completely been printed (except for input protected with @code{\!} or
11814 @code{\?}) since the data in the diversion is already formatted. In most
11815 cases, this is not the expected behaviour.
11817 @c ---------------------------------------------------------------------
11819 @node Diversion Traps, Input Line Traps, Page Location Traps, Traps
11820 @subsection Diversion Traps
11821 @cindex diversion traps
11822 @cindex traps, diversion
11824 @Defreq {dt, [@Var{dist} @Var{macro}]}
11825 @cindex @code{.t} register, and diversions
11826 @cindex setting diversion trap (@code{dt})
11827 @cindex diversion trap, setting (@code{dt})
11828 @cindex trap, diversion, setting (@code{dt})
11829 Set a trap @emph{within} a diversion.
11830 @var{dist} is the location of the trap
11831 (identical to the @code{wh} request; default scaling indicator is
11832 @samp{v}) and @var{macro} is the name of the macro to be invoked.
11833 If called without arguments, the diversion trap is removed.
11835 Note that there exists only a single diversion trap.
11837 The number register @code{.t} still works within diversions.
11838 @xref{Diversions}, for more information.
11841 @c ---------------------------------------------------------------------
11843 @node Input Line Traps, Blank Line Traps, Diversion Traps, Traps
11844 @subsection Input Line Traps
11845 @cindex input line traps
11846 @cindex traps, input line
11848 @DefreqList {it, n macro}
11849 @DefreqItem {itc, n macro}
11850 @cindex setting input line trap (@code{it})
11851 @cindex input line trap, setting (@code{it})
11852 @cindex trap, input line, setting (@code{it})
11853 Set an input line trap.
11854 @var{n}@tie{}is the number of lines of input which may be read before
11855 springing the trap, @var{macro} is the macro to be invoked.
11856 Request lines are not counted as input lines.
11858 For example, one possible use is to have a macro which prints the
11859 next @var{n}@tie{}lines in a bold font.
11872 @cindex input line traps and interrupted lines (@code{itc})
11873 @cindex interrupted lines and input line traps (@code{itc})
11874 @cindex traps, input line, and interrupted lines (@code{itc})
11875 @cindex lines, interrupted, and input line traps (@code{itc})
11876 The @code{itc} request is identical
11877 except that an interrupted text line (ending with @code{\c})
11878 is not counted as a separate line.
11880 Both requests are associated with the current environment
11881 (@pxref{Environments}); switching to another environment disables the
11882 current input trap, and going back reactivates it, restoring the number
11883 of already processed lines.
11886 @c ---------------------------------------------------------------------
11888 @node Blank Line Traps, End-of-input Traps, Input Line Traps, Traps
11889 @subsection Blank Line Traps
11890 @cindex blank line traps
11891 @cindex traps, blank line
11893 @Defreq {blm, macro}
11894 @cindex blank line macro (@code{blm})
11895 Set a blank line trap.
11896 @code{gtroff} executes @var{macro} when it encounters a blank line in
11900 @c ---------------------------------------------------------------------
11902 @node End-of-input Traps, , Blank Line Traps, Traps
11903 @subsection End-of-input Traps
11904 @cindex end-of-input traps
11905 @cindex traps, end-of-input
11907 @Defreq {em, macro}
11908 @cindex setting end-of-input trap (@code{em})
11909 @cindex end-of-input trap, setting (@code{em})
11910 @cindex trap, end-of-input, setting (@code{em})
11911 @cindex end-of-input macro (@code{em})
11912 @cindex macro, end-of-input (@code{em})
11913 Set a trap at the end of input. @var{macro} is executed after the
11914 last line of the input file has been processed.
11916 For example, if the document had to have a section at the bottom of the
11917 last page for someone to approve it, the @code{em} request could be
11923 . sp |(\\n[.t] - 6v)
11937 @c =====================================================================
11939 @node Diversions, Environments, Traps, gtroff Reference
11940 @section Diversions
11943 In @code{gtroff} it is possible to @dfn{divert} text into a named
11944 storage area. Due to the similarity to defining macros it is sometimes
11945 said to be stored in a macro. This is used for saving text for output
11946 at a later time, which is useful for keeping blocks of text on the same
11947 page, footnotes, tables of contents, and indices.
11949 @cindex top-level diversion
11950 @cindex diversion, top-level
11951 For orthogonality it is said that @code{gtroff} is in the @dfn{top-level
11952 diversion} if no diversion is active (i.e., the data is diverted to the
11955 @DefreqList {di, macro}
11956 @DefreqListEnd {da, macro}
11957 @cindex beginning diversion (@code{di})
11958 @cindex diversion, beginning (@code{di})
11959 @cindex ending diversion (@code{di})
11960 @cindex diversion, ending (@code{di})
11961 @cindex appending to a diversion (@code{da})
11962 @cindex diversion, appending (@code{da})
11963 Begin a diversion. Like the @code{de}
11964 request, it takes an argument of a macro name to divert subsequent text
11965 into. The @code{da} macro appends to an existing diversion.
11967 @code{di} or @code{da} without an argument ends the diversion.
11970 @DefreqList {box, macro}
11971 @DefreqListEnd {boxa, macro}
11972 Begin (or appends to) a diversion like the
11973 @code{di} and @code{da} requests.
11974 The difference is that @code{box} and @code{boxa}
11975 do not include a partially-filled line in the diversion.
11987 @result{} Before the box. After the box.
11989 @result{} In the box.
11996 Before the diversion.
12001 After the diversion.
12003 @result{} After the diversion.
12005 @result{} Before the diversion. In the diversion.
12008 @code{box} or @code{boxa} without an argument ends the diversion.
12012 @DefregListEnd {.d}
12013 @cindex @code{nl} register, and @code{.d}
12014 @cindex nested diversions
12015 @cindex diversion, nested
12016 @cindex diversion name register (@code{.z})
12017 @cindex vertical position in diversion register (@code{.d})
12018 @cindex position, vertical, in diversion, register (@code{.d})
12019 @cindex diversion, vertical position in, register (@code{.d})
12020 Diversions may be nested. The read-only number register @code{.z}
12021 contains the name of the current diversion (this is a string-valued
12022 register). The read-only number register @code{.d} contains the current
12023 vertical place in the diversion. If not in a diversion it is the same
12024 as register @code{nl}.
12028 @cindex high-water mark register (@code{.h})
12029 @cindex mark, high-water, register (@code{.h})
12030 @cindex position of lowest text line (@code{.h})
12031 @cindex text line, position of lowest (@code{.h})
12032 The @dfn{high-water mark} on the current page. It corresponds to the
12033 text baseline of the lowest line on the page. This is a read-only
12037 .tm .h==\n[.h], nl==\n[nl]
12038 @result{} .h==0, nl==-1
12042 .tm .h==\n[.h], nl==\n[nl]
12043 @result{} .h==40, nl==120
12046 @cindex @code{.h} register, difference to @code{nl}
12047 @cindex @code{nl} register, difference to @code{.h}
12049 As can be seen in the previous example, empty lines are not considered
12050 in the return value of the @code{.h} register.
12054 @DefregListEnd {dl}
12055 @cindex @code{dn} register, and @code{da} (@code{boxa})
12056 @cindex @code{dl} register, and @code{da} (@code{boxa})
12057 @cindex @code{da} request, and @code{dn} (@code{dl})
12058 @cindex @code{boxa} request, and @code{dn} (@code{dl})
12059 After completing a diversion, the read-write number registers @code{dn}
12060 and @code{dl} contain the vertical and horizontal size of the diversion.
12061 Note that only the just processed lines are counted: For the computation
12062 of @code{dn} and @code{dl}, the requests @code{da} and @code{boxa} are
12063 handled as if @code{di} and @code{box} had been used -- lines which have
12064 been already stored in a macro are not taken into account.
12067 .\" Center text both horizontally & vertically
12069 .\" Enclose macro definitions in .eo and .ec
12070 .\" to avoid the doubling of the backslash
12072 .\" macro .(c starts centering mode
12083 .\" macro .)c terminates centering mode
12088 . nr @@s (((\n[.t]u - \n[dn]u) / 2u) - 1v)
12100 .\" End of macro definitions, restore escape mechanism
12105 @DefescList {\\!, , , }
12106 @DefescListEnd {\\?, , anything, \\?}
12107 @cindex transparent output (@code{\!}, @code{\?})
12108 @cindex output, transparent (@code{\!}, @code{\?})
12109 Prevent requests, macros, and escapes from being
12110 interpreted when read into a diversion. Both escapes take the given text
12111 and @dfn{transparently} embed it into the diversion. This is useful for
12112 macros which shouldn't be invoked until the diverted text is actually
12115 The @code{\!} escape transparently embeds text up to
12116 and including the end of the line.
12117 The @code{\?} escape transparently embeds text until the next
12118 occurrence of the @code{\?} escape. Example:
12125 @var{anything} may not contain newlines; use @code{\!} to embed
12126 newlines in a diversion. The escape sequence @code{\?} is also
12127 recognized in copy mode and turned into a single internal code; it is
12128 this code that terminates @var{anything}. Thus the following example
12135 \?\\?\\\\?\\\\\\\\nx\\\\?\\?\?
12149 Both escapes read the data in copy mode.
12151 @cindex @code{\!}, in top-level diversion
12152 @cindex top-level diversion, and @code{\!}
12153 @cindex diversion, top-level, and @code{\!}
12154 If @code{\!} is used in the top-level diversion, its argument is
12155 directly embedded into the @code{gtroff} intermediate output. This can
12156 be used for example to control a postprocessor which processes the data
12157 before it is sent to the device driver.
12159 @cindex @code{\?}, in top-level diversion
12160 @cindex top-level diversion, and @code{\?}
12161 @cindex diversion, top-level, and @code{\?}
12162 The @code{\?} escape used in the top-level diversion produces no output
12163 at all; its argument is simply ignored.
12166 @cindex @code{\!}, and @code{output}
12167 @cindex @code{output} request, and @code{\!}
12168 @Defreq {output, string}
12169 Emit @var{string} directly to the @code{gtroff} intermediate output
12170 (subject to copy-mode interpretation); this is similar to @code{\!} used
12171 at the top level. An initial double quote in @var{string} is stripped off
12172 to allow initial blanks.
12174 This request can't be used before the first page has started -- if you get
12175 an error, simply insert @code{.br} before the @code{output} request.
12177 Without argument, @code{output} is ignored.
12179 Use with caution! It is normally only needed for mark-up used by a
12180 postprocessor which does something with the output before sending it to
12181 the output device, filtering out @var{string} again.
12184 @Defreq {asciify, div}
12185 @cindex unformatting diversions (@code{asciify})
12186 @cindex diversion, unformatting (@code{asciify})
12187 @cindex @code{trin} request, and @code{asciify}
12188 @dfn{Unformat} the diversion specified by @var{div}
12189 in such a way that @acronym{ASCII} characters, characters translated with
12190 the @code{trin} request, space characters, and some escape sequences that
12191 were formatted and diverted are treated like ordinary input
12192 characters when the diversion is reread. It can be also used for gross
12193 hacks; for example, the following sets register@tie{}@code{n} to@tie{}1.
12206 @xref{Copy-in Mode}.
12209 @Defreq {unformat, div}
12210 Like @code{asciify}, unformat the specified diversion.
12211 However, @code{unformat} only unformats spaces and tabs
12213 Unformatted tabs are treated as input tokens,
12214 and spaces are stretchable again.
12216 The vertical size of lines is not preserved; glyph information (font,
12217 font size, space width, etc.)@: is retained.
12221 @c =====================================================================
12223 @node Environments, Suppressing output, Diversions, gtroff Reference
12224 @section Environments
12225 @cindex environments
12227 It happens frequently that some text should be printed in a certain
12228 format regardless of what may be in effect at the time, for example, in
12229 a trap invoked macro to print headers and footers. To solve this
12230 @code{gtroff} processes text in @dfn{environments}. An
12231 environment contains most of the parameters that control text
12232 processing. It is possible to switch amongst these environments; by
12233 default @code{gtroff} processes text in environment@tie{}0. The
12234 following is the information kept in an environment.
12238 font parameters (size, family, style, glyph height and slant, space
12239 and sentence space size)
12242 page parameters (line length, title length, vertical spacing,
12243 line spacing, indentation, line numbering, centering, right-justifying,
12244 underlining, hyphenation data)
12247 fill and adjust mode
12250 tab stops, tab and leader characters, escape character,
12251 no-break and hyphen indicators, margin character data
12254 partially collected lines
12260 drawing and fill colours
12263 These environments may be given arbitrary names (see @ref{Identifiers},
12264 for more info). Old versions of @code{troff} only had environments
12265 named @samp{0}, @samp{1}, and @samp{2}.
12267 @DefreqList {ev, [@Var{env}]}
12268 @DefregListEnd {.ev}
12269 @cindex switching environments (@code{ev})
12270 @cindex environment, switching (@code{ev})
12271 @cindex environment number/name register (@code{.ev})
12272 Switch to another environment. The argument @var{env} is the name of
12273 the environment to switch to. With no argument, @code{gtroff} switches
12274 back to the previous environment. There is no limit on the number of
12275 named environments; they are created the first time that they are
12276 referenced. The @code{.ev} read-only register contains the name or
12277 number of the current environment. This is a string-valued register.
12279 Note that a call to @code{ev} (with argument) pushes the previously
12280 active environment onto a stack. If, say, environments @samp{foo},
12281 @samp{bar}, and @samp{zap} are called (in that order), the first
12282 @code{ev} request without parameter switches back to environment
12283 @samp{bar} (which is popped off the stack), and a second call
12284 switches back to environment @samp{foo}.
12286 Here is an example:
12299 \(dg Note the large, friendly letters.
12305 @cindex copying environment (@code{evc})
12306 @cindex environment, copying (@code{evc})
12307 Copy the environment @var{env} into the current environment.
12309 The following environment data is not copied:
12313 Partially filled lines.
12316 The status whether the previous line was interrupted.
12319 The number of lines still to center, or to right-justify, or to underline
12320 (with or without underlined spaces); they are set to zero.
12323 The status whether a temporary indent is active.
12326 Input traps and its associated data.
12329 Line numbering mode is disabled; it can be reactivated with
12333 The number of consecutive hyphenated lines (set to zero).
12340 @DefregListEnd {.csk}
12341 @cindex environment, dimensions of last glyph (@code{.w}, @code{.cht}, @code{.cdp}, @code{.csk})
12342 @cindex width, of last glyph (@code{.w})
12343 @cindex height, of last glyph (@code{.cht})
12344 @cindex depth, of last glyph (@code{.cdp})
12345 @cindex skew, of last glyph (@code{.csk})
12346 @cindex last glyph, dimensions (@code{.w}, @code{.cht}, @code{.cdp}, @code{.csk})
12347 @cindex glyph, last, dimensions (@code{.w}, @code{.cht}, @code{.cdp}, @code{.csk})
12348 The @code{\n[.w]} register contains the
12349 width of the last glyph added to the current environment.
12351 The @code{\n[.cht]} register contains the
12352 height of the last glyph added to the current environment.
12354 The @code{\n[.cdp]} register contains the
12355 depth of the last glyph added to the current environment.
12356 It is positive for glyphs extending below the baseline.
12358 The @code{\n[.csk]} register contains the
12359 @dfn{skew} (how far to the right of the glyph's center
12360 that @code{gtroff} should place an accent)
12361 of the last glyph added to the current environment.
12365 @cindex environment, previous line length (@code{.n})
12366 @cindex line length, previous (@code{.n})
12367 @cindex length of previous line (@code{.n})
12368 @cindex previous line length (@code{.n})
12369 The @code{\n[.n]} register contains the
12370 length of the previous output line in the current environment.
12374 @c =====================================================================
12376 @node Suppressing output, Colors, Environments, gtroff Reference
12377 @section Suppressing output
12379 @Defesc {\\O, , num, }
12380 @cindex suppressing output (@code{\O})
12381 @cindex output, suppressing (@code{\O})
12382 Disable or enable output depending on the value of @var{num}:
12386 Disable any glyphs from being emitted to the device driver, provided that
12387 the escape occurs at the outer level (see @code{\O[3]} and @code{\O[4]}).
12388 Motion is not suppressed so effectively @code{\O[0]} means @emph{pen up}.
12391 Enable output of glyphs, provided that the escape occurs at the outer
12399 @code{\O0} and @code{\O1} also reset the four registers @samp{opminx},
12400 @samp{opminy}, @samp{opmaxx}, and @samp{opmaxy} to @minus{}1.
12401 @xref{Register Index}. These four registers mark the top left and
12402 bottom right hand corners of a box which encompasses all written glyphs.
12404 For example the input text:
12407 Hello \O[0]world \O[1]this is a test.
12411 produces the following output:
12414 Hello this is a test.
12419 Provided that the escape occurs at the outer level, enable output of
12420 glyphs and also write out to @code{stderr} the page number and four
12421 registers encompassing the glyphs previously written since the last call
12425 Begin a nesting level. At start-up, @code{gtroff} is at outer level.
12428 End a nesting level.
12430 @item \O[5@var{P}@var{filename}]
12431 This escape is @code{grohtml} specific. Provided that this escape
12432 occurs at the outer nesting level write the @code{filename} to
12433 @code{stderr}. The position of the image, @var{P}, must be specified
12434 and must be one of @code{l}, @code{r}, @code{c}, or@tie{}@code{i} (left,
12435 right, centered, inline). @var{filename} will be associated with the
12436 production of the next inline image.
12440 @c =====================================================================
12442 @node Colors, I/O, Suppressing output, gtroff Reference
12446 @DefreqList {color, [@Var{n}]}
12447 @DefregListEnd {.color}
12448 If @var{n} is missing or non-zero, activate colors (this is the default);
12449 otherwise, turn it off.
12451 The read-only number register @code{.color} is@tie{}1 if colors are active,
12454 Internally, @code{color} sets a global flag; it does not produce a token.
12455 Similar to the @code{cp} request, you should use it at the beginning of
12456 your document to control color output.
12458 Colors can be also turned off with the @option{-c} command line option.
12461 @Defreq {defcolor, ident scheme color_components}
12462 Define color with name @var{ident}. @var{scheme} can be one of the
12463 following values: @code{rgb} (three components), @code{cmy} (three
12464 components), @code{cmyk} (four components), and @code{gray} or
12465 @code{grey} (one component).
12467 @cindex default color
12468 @cindex color, default
12469 Color components can be given either as a hexadecimal string or as
12470 positive decimal integers in the range 0--65535. A hexadecimal string
12471 contains all color components concatenated. It must start with either
12472 @code{#} or @code{##}; the former specifies hex values in the range
12473 0--255 (which are internally multiplied by@tie{}257), the latter in the
12474 range 0--65535. Examples: @code{#FFC0CB} (pink), @code{##ffff0000ffff}
12475 (magenta). The default color name @c{default} can't be redefined; its
12476 value is device-specific (usually black). It is possible that the
12477 default color for @code{\m} and @code{\M} is not identical.
12479 @cindex @code{f} unit, and colors
12480 @cindex unit, @code{f}, and colors
12481 A new scaling indicator@tie{}@code{f} has been introduced which multiplies
12482 its value by 65536; this makes it convenient to specify color components
12483 as fractions in the range 0 to@tie{}1 (1f equals 65536u). Example:
12486 .defcolor darkgreen rgb 0.1f 0.5f 0.2f
12489 Note that @code{f} is the default scaling indicator for the
12490 @code{defcolor} request, thus the above statement is equivalent to
12493 .defcolor darkgreen rgb 0.1 0.5 0.2
12497 @DefreqList {gcolor, [@Var{color}]}
12498 @DefescItem {\\m, , c, }
12499 @DefescItem {\\m, @Lparen{}, co, }
12500 @DefescItem {\\m, @Lbrack{}, color, @Rbrack{}}
12501 @DefregListEnd {.m}
12502 Set (glyph) drawing color. The following examples show how to turn the
12503 next four words red.
12509 and these words are in black.
12513 \m[red]these are in red\m[] and these words are in black.
12516 The escape @code{\m[]} returns to the previous color, as does a call to
12517 @code{gcolor} without an argument.
12519 @cindex drawing color name register (@code{.m})
12520 @cindex name, drawing color, register (@code{.m})
12521 @cindex color name, drawing, register (@code{.m})
12522 The name of the current drawing color is available in the read-only,
12523 string-valued number register @samp{.m}.
12525 The drawing color is associated with the current environment
12526 (@pxref{Environments}).
12528 Note that @code{\m} doesn't produce an input token in @code{gtroff}.
12529 As a consequence, it can be used in requests like @code{mc} (which
12530 expects a single character as an argument) to change the color on
12538 @DefreqList {fcolor, [@Var{color}]}
12539 @DefescItem {\\M, , c, }
12540 @DefescItem {\\M, @Lparen{}, co, }
12541 @DefescItem {\\M, @Lbrack{}, color, @Rbrack{}}
12542 @DefregListEnd {.M}
12543 Set fill (background) color for filled objects drawn with the
12544 @code{\D'@dots{}'} commands.
12546 A red ellipse can be created with the following code:
12549 \M[red]\h'0.5i'\D'E 2i 1i'\M[]
12552 The escape @code{\M[]} returns to the previous fill color, as does a call to
12553 @code{fcolor} without an argument.
12555 @cindex background color name register (@code{.M})
12556 @cindex name, background color, register (@code{.M})
12557 @cindex color name, background, register (@code{.M})
12558 @cindex fill color name register (@code{.M})
12559 @cindex name, fill color, register (@code{.M})
12560 @cindex color name, fill, register (@code{.M})
12561 The name of the current fill (background) color is available in the
12562 read-only, string-valued number register @samp{.M}.
12564 The fill color is associated with the current environment
12565 (@pxref{Environments}).
12567 Note that @code{\M} doesn't produce an input token in @code{gtroff}.
12571 @c =====================================================================
12573 @node I/O, Postprocessor Access, Colors, gtroff Reference
12576 @cindex input and output requests
12577 @cindex requests for input and output
12578 @cindex output and input requests
12580 @code{gtroff} has several requests for including files:
12583 @cindex including a file (@code{so})
12584 @cindex file, inclusion (@code{so})
12585 Read in the specified @var{file} and
12586 includes it in place of the @code{so} request. This is quite useful for
12587 large documents, e.g.@: keeping each chapter in a separate file.
12588 @xref{gsoelim}, for more information.
12590 Since @code{gtroff} replaces the @code{so} request with the contents
12591 of @code{file}, it makes a difference whether the data is terminated with
12592 a newline or not: Assuming that file @file{xxx} contains the word
12593 @samp{foo} without a final newline, this
12602 yields @samp{This is foobar}.
12604 The search path for @var{file} can be controlled with the @option{-I} command
12608 @Defreq {pso, command}
12609 Read the standard output from the specified @var{command}
12610 and includes it in place of the @code{pso} request.
12613 @cindex mode, safer
12614 @cindex unsafe mode
12615 @cindex mode, unsafe
12616 This request causes an error if used in safer mode (which is the default).
12617 Use @code{groff}'s or @code{troff}'s @option{-U} option to activate unsafe
12620 The comment regarding a final newline for the @code{so} request is valid
12621 for @code{pso} also.
12624 @Defreq {mso, file}
12625 Identical to the @code{so} request except that @code{gtroff} searches for
12626 the specified @var{file} in the same directories as macro files for the
12627 the @option{-m} command line option. If the file name to be included
12628 has the form @file{@var{name}.tmac} and it isn't found, @code{mso} tries
12629 to include @file{tmac.@var{name}} and vice versa.
12632 @DefreqList {trf, file}
12633 @DefreqListEnd {cf, file}
12634 @cindex transparent output (@code{cf}, @code{trf})
12635 @cindex output, transparent (@code{cf}, @code{trf})
12636 Transparently output the contents of @var{file}. Each line is output
12637 as if it were preceded by @code{\!}; however, the lines are not subject
12638 to copy mode interpretation. If the file does not end with a newline,
12639 then a newline is added (@code{trf} only). For example, to define a
12640 macro@tie{}@code{x} containing the contents of file@tie{}@file{f}, use
12648 Both @code{trf} and @code{cf}, when used in a diversion,
12649 embeds an object in the diversion which, when reread, causes the
12650 contents of @var{file} to be transparently copied through to the
12651 output. In @acronym{UNIX} @code{troff}, the contents of @var{file}
12652 is immediately copied through to the output regardless of whether there
12653 is a current diversion; this behaviour is so anomalous that it must be
12656 @cindex @code{trf} request, and invalid characters
12657 @cindex characters, invalid for @code{trf} request
12658 @cindex invalid characters for @code{trf} request
12659 While @code{cf} copies the contents of @var{file} completely unprocessed,
12660 @code{trf} disallows characters such as NUL that are not valid
12661 @code{gtroff} input characters (@pxref{Identifiers}).
12663 Both requests cause a line break.
12666 @Defreq {nx, [@Var{file}]}
12667 @cindex processing next file (@code{nx})
12668 @cindex file, processing next (@code{nx})
12669 @cindex next file, processing (@code{nx})
12670 Force @code{gtroff} to continue processing of
12671 the file specified as an argument. If no argument is given, immediately
12672 jump to the end of file.
12675 @Defreq {rd, [@Var{prompt} [@Var{arg1} @Var{arg2} @dots{}]]}
12676 @cindex reading from standard input (@code{rd})
12677 @cindex standard input, reading from (@code{rd})
12678 @cindex input, standard, reading from (@code{rd})
12679 Read from standard input, and include what is read as though it
12680 were part of the input file. Text is read until a blank line
12683 If standard input is a TTY input device (keyboard), write @var{prompt}
12684 to standard error, followed by a colon (or send BEL for a beep if no
12685 argument is given).
12687 Arguments after @var{prompt} are available for the input. For example,
12694 with the input @w{@samp{This is \$2.}} prints
12701 @cindex form letters
12702 @cindex letters, form
12703 Using the @code{nx} and @code{rd} requests,
12704 it is easy to set up form letters. The form
12705 letter template is constructed like this, putting the following lines
12706 into a file called @file{repeat.let}:
12722 @cindex @code{ex} request, used with @code{nx} and @code{rd}
12724 When this is run, a file containing the following lines should be
12725 redirected in. Note that requests included in this file are executed
12726 as though they were part of the form letter. The last block of input
12727 is the @code{ex} request which tells @code{groff} to stop processing. If
12728 this was not there, @code{groff} would not know when to stop.
12732 708 NW 19th Av., #202
12739 San Diego, CA 92103
12747 Pipe the output of @code{gtroff} to the shell command(s)
12748 specified by @var{pipe}. This request must occur before
12749 @code{gtroff} has a chance to print anything.
12752 @cindex mode, safer
12753 @cindex unsafe mode
12754 @cindex mode, unsafe
12755 @code{pi} causes an error if used in safer mode (which is the default).
12756 Use @code{groff}'s or @code{troff}'s @option{-U} option to activate unsafe
12759 Multiple calls to @code{pi} are allowed, acting as a chain. For example,
12767 is the same as @w{@samp{.pi foo | bar}}.
12769 @cindex @code{groff}, and @code{pi} request
12770 @cindex @code{pi} request, and @code{groff}
12771 Note that the intermediate output format of @code{gtroff} is piped to
12772 the specified commands. Consequently, calling @code{groff} without the
12773 @option{-Z} option normally causes a fatal error.
12776 @DefreqList {sy, cmds}
12777 @DefregListEnd {systat}
12778 Execute the shell command(s) specified by @var{cmds}. The output is not
12779 saved anyplace, so it is up to the user to do so.
12782 @cindex mode, safer
12783 @cindex unsafe mode
12784 @cindex mode, unsafe
12785 This request causes an error if used in safer mode (which is the default).
12786 Use @code{groff}'s or @code{troff}'s @option{-U} option to activate unsafe
12789 For example, the following code fragment introduces the current time into a
12792 @cindex time, current
12793 @cindex current time
12796 .sy perl -e 'printf ".nr H %d\\n.nr M %d\\n.nr S %d\\n",\
12797 (localtime(time))[2,1,0]' > /tmp/x\n[$$]
12799 .sy rm /tmp/x\n[$$]
12804 Note that this works by having the @code{perl} script (run by @code{sy})
12805 print out the @code{nr} requests which set the number registers
12806 @code{H}, @code{M}, and @code{S}, and then reads those commands in with
12807 the @code{so} request.
12809 For most practical purposes, the number registers @code{seconds},
12810 @code{minutes}, and @code{hours} which are initialized at start-up of
12811 @code{gtroff} should be sufficient. Use the @code{af} request to get a
12818 \n[hours]:\n[minutes]:\n[seconds]
12821 @cindex @code{system()} return value register (@code{systat})
12822 The @code{systat} read-write number register contains the return value
12823 of the @code{system()} function executed by the last @code{sy} request.
12826 @DefreqList {open, stream file}
12827 @DefreqListEnd {opena, stream file}
12828 @cindex opening file (@code{open})
12829 @cindex file, opening (@code{open})
12830 @cindex appending to a file (@code{opena})
12831 @cindex file, appending to (@code{opena})
12832 Open the specified @var{file} for writing and
12833 associates the specified @var{stream} with it.
12835 The @code{opena} request is like @code{open}, but if the file exists,
12836 append to it instead of truncating it.
12839 @cindex mode, safer
12840 @cindex unsafe mode
12841 @cindex mode, unsafe
12842 Both @code{open} and @code{opena} cause an error if used in safer mode
12843 (which is the default). Use @code{groff}'s or @code{troff}'s @option{-U}
12844 option to activate unsafe mode.
12847 @DefreqList {write, stream data}
12848 @DefreqListEnd {writec, stream data}
12849 @cindex copy-in mode, and @code{write} requests
12850 @cindex mode, copy-in, and @code{write} requests
12851 @cindex writing to file (@code{write})
12852 @cindex file, writing to (@code{write})
12853 Write to the file associated with the specified @var{stream}.
12854 The stream must previously have
12855 been the subject of an open request. The remainder of the line is
12856 interpreted as the @code{ds} request reads its second argument: A
12857 leading @samp{"} is stripped, and it is read in copy-in mode.
12859 The @code{writec} request is like @code{write}, but only
12860 @code{write} appends a newline to the data.
12863 @Defreq {writem, stream xx}
12864 @cindex @code{asciify} request, and @code{writem}
12865 Write the contents of the macro or string @var{xx}
12866 to the file associated with the specified @var{stream}.
12868 @var{xx} is read in copy mode, i.e., already formatted elements are
12869 ignored. Consequently, diversions must be unformatted with the
12870 @code{asciify} request before calling @code{writem}. Usually, this
12871 means a loss of information.
12874 @Defreq {close, stream}
12875 @cindex closing file (@code{close})
12876 @cindex file, closing (@code{close})
12877 Close the specified @var{stream};
12878 the stream is no longer an acceptable argument to the
12879 @code{write} request.
12881 Here a simple macro to write an index entry.
12887 . write idx \\n[%] \\$*
12896 @DefescList {\\V, , e, }
12897 @DefescItem {\\V, @Lparen{}, ev, }
12898 @DefescListEnd {\\V, @Lbrack{}, env, @Rbrack{}}
12899 Interpolate the contents of the specified environment variable
12900 @var{env} (one-character name@tie{}@var{e}, two-character name @var{ev})
12901 as returned by the function @code{getenv}. @code{\V} is interpreted
12906 @c =====================================================================
12908 @node Postprocessor Access, Miscellaneous, I/O, gtroff Reference
12909 @section Postprocessor Access
12910 @cindex postprocessor access
12911 @cindex access of postprocessor
12913 There are two escapes which give information directly to the
12914 postprocessor. This is particularly useful for embedding
12915 @sc{PostScript} into the final document.
12917 @Defesc {\\X, ', xxx, '}
12918 Embeds its argument into the @code{gtroff}
12919 output preceded with @w{@samp{x X}}.
12921 @cindex @code{\&}, in @code{\X}
12922 @cindex @code{\)}, in @code{\X}
12923 @cindex @code{\%}, in @code{\X}
12925 @cindex @code{\:}, in @code{\X}
12928 @cindex @code{\@r{<colon>}}, in @code{\X}
12930 The escapes @code{\&}, @code{\)}, @code{\%}, and @code{\:} are ignored
12931 within @code{\X}, @w{@samp{\ }} and @code{\~} are converted to single
12932 space characters. All other escapes (except @code{\\} which produces a
12933 backslash) cause an error.
12935 @kindex use_charnames_in_special
12936 @pindex DESC@r{, and @code{use_charnames_in_special}}
12937 @cindex @code{\X}, and special characters
12938 If the @samp{use_charnames_in_special} keyword is set in the @file{DESC}
12939 file, special characters no longer cause an error; the name @var{xx} is
12940 represented as @samp{\(@var{xx})} in the @w{@samp{x X}} output command.
12941 Additionally, the backslash is represented as @code{\\}.
12943 @samp{use_charnames_in_special} is currently used by @code{grohtml} only.
12946 @DefescList {\\Y, , n, }
12947 @DefescItem {\\Y, @Lparen{}, nm, }
12948 @DefescListEnd {\\Y, @Lbrack{}, name, @Rbrack{}}
12949 This is approximately equivalent to @samp{\X'\*[@var{name}]'}
12950 (one-character name@tie{}@var{n}, two-character name @var{nm}).
12951 However, the contents of the string or macro @var{name} are not
12952 interpreted; also it is permitted for @var{name} to have been defined
12953 as a macro and thus contain newlines (it is not permitted for the
12954 argument to @code{\X} to contain newlines). The inclusion of
12955 newlines requires an extension to the @acronym{UNIX} @code{troff}
12956 output format, and confuses drivers that do not know about this
12957 extension (@pxref{Device Control Commands}).
12960 @xref{Output Devices}.
12963 @c =====================================================================
12965 @node Miscellaneous, Gtroff Internals, Postprocessor Access, gtroff Reference
12966 @section Miscellaneous
12968 This section documents parts of @code{gtroff} which cannot (yet) be
12969 categorized elsewhere in this manual.
12971 @Defreq {nm, [@Var{start} [@Var{inc} [@Var{space} [@Var{indent}]]]]}
12972 @cindex printing line numbers (@code{nm})
12973 @cindex line numbers, printing (@code{nm})
12974 @cindex numbers, line, printing (@code{nm})
12975 Print line numbers.
12976 @var{start} is the line number of the @emph{next}
12977 output line. @var{inc} indicates which line numbers are printed.
12978 For example, the value@tie{}5 means to emit only line numbers which
12979 are multiples of@tie{}5; this defaults to@tie{}1. @var{space} is the
12980 space to be left between the number and the text; this defaults to
12981 one digit space. The fourth argument is the indentation of the line
12982 numbers, defaulting to zero. Both @var{space} and @var{indent} are
12983 given as multiples of digit spaces; they can be negative also.
12984 Without any arguments, line numbers are turned off.
12986 @code{gtroff} reserves three digit spaces for the line number (which is
12987 printed right-justified) plus the amount given by @var{indent}; the
12988 output lines are concatenated to the line numbers, separated by
12989 @var{space}, and @emph{without} reducing the line length. Depending
12990 on the value of the horizontal page offset (as set with the
12991 @code{po} request), line numbers which are longer than the reserved
12992 space stick out to the left, or the whole line is moved to the right.
12994 Parameters corresponding to missing arguments are not changed; any
12995 non-digit argument (to be more precise, any argument starting with a
12996 character valid as a delimiter for identifiers) is also treated as
12999 If line numbering has been disabled with a call to @code{nm} without
13000 an argument, it can be reactivated with @samp{.nm +0}, using the
13001 previously active line numbering parameters.
13003 The parameters of @code{nm} are associated with the current environment
13004 (@pxref{Environments}). The current output line number is available
13005 in the number register @code{ln}.
13010 This test shows how line numbering works with groff.
13012 This test shows how line numbering works with groff.
13016 This test shows how line numbering works with groff.
13018 This test shows how line numbering works with groff.
13022 And here the result:
13025 This test shows how
13026 line numbering works
13027 999 with groff. This
13028 1000 test shows how line
13029 1001 numbering works with
13031 This test shows how
13034 This test shows how
13035 1005 line numbering
13040 @Defreq {nn, [@Var{skip}]}
13041 Temporarily turn off line numbering. The argument is the number
13042 of lines not to be numbered; this defaults to@tie{}1.
13045 @Defreq {mc, glyph [@Var{dist}]}
13046 @cindex margin glyph (@code{mc})
13047 @cindex glyph, for margins (@code{mc})
13048 Print a @dfn{margin character} to the right of the
13049 text.@footnote{@dfn{Margin character} is a misnomer since it is an
13050 output glyph.} The first argument is the glyph to be
13051 printed. The second argument is the distance away from the right
13052 margin. If missing, the previously set value is used; default is
13053 10@dmn{pt}). For text lines that are too long (that is, longer than
13054 the text length plus @var{dist}), the margin character is directly
13055 appended to the lines.
13057 With no arguments the margin character is turned off.
13058 If this occurs before a break, no margin character is printed.
13060 For compatibility with @acronym{AT&T} @code{troff}, a call to @code{mc}
13061 to set the margin character can't be undone immediately; at least one
13062 line gets a margin character. Thus
13081 @cindex @code{tl} request, and @code{mc}
13082 For empty lines and lines produced by the @code{tl} request no margin
13083 character is emitted.
13085 The margin character is associated with the current environment
13086 (@pxref{Environments}).
13090 This is quite useful for indicating text that has changed, and, in fact,
13091 there are programs available for doing this (they are called
13092 @code{nrchbar} and @code{changebar} and can be found in any
13093 @samp{comp.sources.unix} archive).
13098 This paragraph is highlighted with a margin
13101 Note that vertical space isn't marked.
13105 But we can fake it with `\&'.
13111 This paragraph is highlighted |
13112 with a margin character. |
13114 Note that vertical space isn't |
13117 But we can fake it with `\&'. |
13121 @DefreqList {psbb, filename}
13125 @DefregListEnd {ury}
13126 @cindex PostScript, bounding box
13127 @cindex bounding box
13128 Retrieve the bounding box of the PostScript image
13129 found in @var{filename}.
13130 The file must conform to
13131 Adobe's @dfn{Document Structuring Conventions} (DSC);
13132 the command searches for a @code{%%BoundingBox} comment
13133 and extracts the bounding box values into the number registers
13134 @code{llx}, @code{lly}, @code{urx}, and @code{ury}.
13135 If an error occurs (for example, @code{psbb} cannot find
13136 the @code{%%BoundingBox} comment),
13137 it sets the four number registers to zero.
13139 The search path for @var{filename} can be controlled with the @option{-I}
13140 command line option.
13144 @c =====================================================================
13146 @node Gtroff Internals, Debugging, Miscellaneous, gtroff Reference
13147 @section @code{gtroff} Internals
13149 @cindex input token
13150 @cindex token, input
13151 @cindex output node
13152 @cindex node, output
13153 @code{gtroff} processes input in three steps. One or more input
13154 characters are converted to an @dfn{input token}.@footnote{Except the
13155 escapes @code{\f}, @code{\F}, @code{\H}, @code{\m}, @code{\M}, @code{\R},
13156 @code{\s}, and @code{\S} which are processed immediately if not in
13157 copy-in mode.} Then, one or more input tokens are converted to an
13158 @dfn{output node}. Finally, output nodes are converted to the
13159 intermediate output language understood by all output devices.
13161 Actually, before step one happens, @code{gtroff} converts certain
13162 escape sequences into reserved input characters (not accessible by
13163 the user); such reserved characters are used for other internal
13164 processing also -- this is the very reason why not all characters
13165 are valid input. @xref{Identifiers}, for more on this topic.
13167 For example, the input string @samp{fi\[:u]} is converted into a
13168 character token @samp{f}, a character token @samp{i}, and a special
13169 token @samp{:u} (representing u@tie{}umlaut). Later on, the character
13170 tokens @samp{f} and @samp{i} are merged to a single output node
13171 representing the ligature glyph @samp{fi} (provided the current font
13172 has a glyph for this ligature); the same happens with @samp{:u}. All
13173 output glyph nodes are `processed' which means that they are invariably
13174 associated with a given font, font size, advance width, etc. During
13175 the formatting process, @code{gtroff} itself adds various nodes to
13176 control the data flow.
13178 Macros, diversions, and strings collect elements in two chained lists:
13179 a list of input tokens which have been passed unprocessed, and a list
13180 of output nodes. Consider the following the diversion.
13192 It contains these elements.
13194 @multitable {@i{vertical size node}} {token list} {element number}
13195 @item node list @tab token list @tab element number
13197 @item @i{line start node} @tab --- @tab 1
13198 @item @i{glyph node @code{a}} @tab --- @tab 2
13199 @item @i{word space node} @tab --- @tab 3
13200 @item --- @tab @code{b} @tab 4
13201 @item --- @tab @code{\n} @tab 5
13202 @item @i{glyph node @code{c}} @tab --- @tab 6
13203 @item @i{vertical size node} @tab --- @tab 7
13204 @item @i{vertical size node} @tab --- @tab 8
13205 @item --- @tab @code{\n} @tab 9
13208 @cindex @code{\v}, internal representation
13210 Elements 1, 7, and@tie{}8 are inserted by @code{gtroff}; the latter two
13211 (which are always present) specify the vertical extent of the last
13212 line, possibly modified by @code{\x}. The @code{br} request finishes
13213 the current partial line, inserting a newline input token which is
13214 subsequently converted to a space when the diversion is reread. Note
13215 that the word space node has a fixed width which isn't stretchable
13216 anymore. To convert horizontal space nodes back to input tokens, use
13217 the @code{unformat} request.
13219 Macros only contain elements in the token list (and the node list is
13220 empty); diversions and strings can contain elements in both lists.
13222 Note that the @code{chop} request simply reduces the number of elements in a
13223 macro, string, or diversion by one. Exceptions are @dfn{compatibility save}
13224 and @dfn{compatibility ignore} input tokens which are ignored. The
13225 @code{substring} request also ignores those input tokens.
13227 Some requests like @code{tr} or @code{cflags} work on glyph
13228 identifiers only; this means that the associated glyph can be changed
13229 without destroying this association. This can be very helpful for
13230 substituting glyphs. In the following example, we assume that
13231 glyph @samp{foo} isn't available by default, so we provide a
13232 substitution using the @code{fchar} request and map it to input
13233 character @samp{x}.
13241 Now let us assume that we install an additional special font
13242 @samp{bar} which has glyph @samp{foo}.
13250 Since glyphs defined with @code{fchar} are searched before glyphs
13251 in special fonts, we must call @code{rchar} to remove the definition
13252 of the fallback glyph. Anyway, the translation is still active;
13253 @samp{x} now maps to the real glyph @samp{foo}.
13255 @cindex compatibility mode, and parameters
13256 @cindex mode, compatibility, and parameters
13257 @cindex arguments, and compatibility mode
13258 @cindex parameters, and compatibility mode
13259 @cindex macro arguments, and compatibility mode
13260 @cindex request arguments, and compatibility mode
13261 Macro and request arguments preserve the compatibility mode:
13264 .cp 1 \" switch to compatibility mode
13268 .cp 0 \" switch compatibility mode off
13274 Since compatibility mode is on while @code{de} is called, the macro
13275 @code{xx} activates compatibility mode while executing. Argument
13276 @code{$1} can still be handled properly because it inherits the
13277 compatibility mode status which was active at the point where @code{xx}
13280 After expansion of the parameters, the compatibility save and restore
13281 tokens are removed.
13284 @c =====================================================================
13286 @node Debugging, Implementation Differences, Gtroff Internals, gtroff Reference
13290 @code{gtroff} is not easy to debug, but there are some useful features
13291 and strategies for debugging.
13293 @Defreq {lf, line [@Var{filename}]}
13295 @cindex multi-file documents
13296 @cindex documents, multi-file
13297 @cindex setting input line number (@code{lf})
13298 @cindex input line number, setting (@code{lf})
13299 @cindex number, input line, setting (@code{lf})
13300 Change the line number and optionally the file name @code{gtroff} shall
13301 use for error and warning messages. @var{line} is the input line number
13302 of the @emph{next} line.
13304 Without argument, the request is ignored.
13306 This is a debugging aid for documents which are split into many files,
13307 then put together with @code{soelim} and other preprocessors. Usually,
13308 it isn't invoked manually.
13310 Note that other @code{troff} implementations (including the original
13311 @acronym{AT&T} version) handle @code{lf} differently. For them,
13312 @var{line} changes the line number of the @emph{current} line.
13315 @DefreqList {tm, string}
13316 @DefreqItem {tm1, string}
13317 @DefreqListEnd {tmc, string}
13318 @cindex printing to stderr (@code{tm}, @code{tm1}, @code{tmc})
13319 @cindex stderr, printing to (@code{tm}, @code{tm1}, @code{tmc})
13320 Send @var{string} to the standard error output;
13321 this is very useful for printing debugging messages among other things.
13323 @var{string} is read in copy mode.
13325 The @code{tm} request ignores leading spaces of @var{string}; @code{tm1}
13326 handles its argument similar to the @code{ds} request: a leading double
13327 quote in @var{string} is stripped to allow initial blanks.
13329 The @code{tmc} request is similar to @code{tm1} but does
13330 not append a newline (as is done in @code{tm} and @code{tm1}).
13333 @Defreq {ab, [@Var{string}]}
13334 @cindex aborting (@code{ab})
13335 Similar to the @code{tm} request, except that
13336 it causes @code{gtroff} to stop processing. With no argument it
13337 prints @samp{User Abort.} to standard error.
13341 @cindex @code{ex} request, use in debugging
13342 @cindex exiting (@code{ex})
13343 The @code{ex} request also causes @code{gtroff} to stop processing;
13344 see also @ref{I/O}.
13347 When doing something involved it is useful to leave the debugging
13348 statements in the code and have them turned on by a command line flag.
13351 .if \n(DB .tm debugging output
13355 To activate these statements say
13361 If it is known in advance that there will be many errors and no useful
13362 output, @code{gtroff} can be forced to suppress formatted output with
13363 the @option{-z} flag.
13366 @cindex dumping symbol table (@code{pm})
13367 @cindex symbol table, dumping (@code{pm})
13368 Print the entire symbol table on @code{stderr}. Names of all defined
13369 macros, strings, and diversions are print together with their size in
13370 bytes. Since @code{gtroff} sometimes adds nodes by itself, the
13371 returned size can be larger than expected.
13373 This request differs from @acronym{UNIX} @code{troff}: @code{gtroff}
13374 reports the sizes of diversions, ignores an additional argument to
13375 print only the total of the sizes, and the size isn't returned in
13376 blocks of 128 characters.
13380 @cindex dumping number registers (@code{pnr})
13381 @cindex number registers, dumping (@code{pnr})
13382 Print the names and contents of all
13383 currently defined number registers on @code{stderr}.
13387 @cindex dumping traps (@code{ptr})
13388 @cindex traps, dumping (@code{ptr})
13389 Print the names and positions of all traps
13390 (not including input line traps and diversion traps) on @code{stderr}.
13391 Empty slots in the page trap list are printed as well, because they can
13392 affect the priority of subsequently planted traps.
13396 @cindex flush output (@code{fl})
13397 @cindex output, flush (@code{fl})
13398 @cindex interactive use of @code{gtroff}
13399 @cindex @code{gtroff}, interactive use
13400 Instruct @code{gtroff} to flush its output immediately. The intent
13401 is for interactive use, but this behaviour is currently not
13402 implemented in @code{gtroff}. Contrary to @acronym{UNIX} @code{troff},
13403 TTY output is sent to a device driver also (@code{grotty}), making it
13404 non-trivial to communicate interactively.
13406 This request causes a line break.
13409 @Defreq {backtrace, }
13410 @cindex backtrace of input stack (@code{backtrace})
13411 @cindex input stack, backtrace (@code{backtrace})
13412 Print a backtrace of the input stack to the standard error stream.
13414 Consider the following in file @file{test}:
13428 On execution, @code{gtroff} prints the following:
13431 test:2: backtrace: macro `xxx'
13432 test:5: backtrace: macro `yyy'
13433 test:8: backtrace: file `test'
13436 The option @option{-b} of @code{gtroff} internally calls a variant of
13437 this request on each error and warning.
13441 @cindex input stack, setting limit
13442 Use the @code{slimit} number register
13443 to set the maximum number of objects on the input stack.
13444 If @code{slimit} is less than or equal to@tie{}0,
13445 there is no limit set.
13446 With no limit, a buggy recursive macro can exhaust virtual memory.
13448 The default value is 1000; this is a compile-time constant.
13451 @Defreq {warnscale, si}
13452 Set the scaling indicator used in warnings to @var{si}. Valid values for
13453 @var{si} are @samp{u}, @samp{i}, @samp{c}, @samp{p}, and @samp{P}. At
13454 startup, it is set to @samp{i}.
13457 @Defreq {spreadwarn, [@Var{limit}]}
13458 Make @code{gtroff} emit a warning if the additional space inserted for
13459 each space between words in an output line is larger or equal to
13460 @var{limit}. A negative value is changed to zero; no argument toggles the
13461 warning on and off without changing @var{limit}. The default scaling
13462 indicator is @samp{m}. At startup, @code{spreadwarn} is deactivated, and
13463 @var{limit} is set to 3@dmn{m}.
13472 will cause a warning if @code{gtroff} must add 0.2@dmn{m} or more for each
13473 interword space in a line.
13475 This request is active only if text is justified to both margins (using
13480 @code{gtroff} has command line options for printing out more warnings
13481 (@option{-w}) and for printing backtraces (@option{-b}) when a warning
13482 or an error occurs. The most verbose level of warnings is @option{-ww}.
13484 @DefreqList {warn, [@Var{flags}]}
13485 @DefregListEnd {.warn}
13486 @cindex level of warnings (@code{warn})
13487 @cindex warnings, level (@code{warn})
13488 Control the level of warnings checked for. The @var{flags} are the sum
13489 of the numbers associated with each warning that is to be enabled; all
13490 other warnings are disabled. The number associated with each warning is
13491 listed below. For example, @w{@code{.warn 0}} disables all warnings,
13492 and @w{@code{.warn 1}} disables all warnings except that about missing
13493 glyphs. If no argument is given, all warnings are enabled.
13495 The read-only number register @code{.warn} contains the current warning
13503 @c ---------------------------------------------------------------------
13505 @node Warnings, , Debugging, Debugging
13506 @subsection Warnings
13509 The warnings that can be given to @code{gtroff} are divided into the
13510 following categories. The name associated with each warning is used by
13511 the @option{-w} and @option{-W} options; the number is used by the
13512 @code{warn} request and by the @code{.warn} register.
13517 Non-existent glyphs.@footnote{@code{char} is a misnomer since it reports
13518 missing glyphs -- there aren't missing input characters, only invalid
13519 ones.} This is enabled by default.
13523 Invalid numeric expressions. This is enabled by default.
13524 @xref{Expressions}.
13530 In fill mode, lines which could not be broken so that their length was
13531 less than the line length. This is enabled by default.
13535 Missing or mismatched closing delimiters.
13539 @cindex @code{ie} request, and warnings
13540 @cindex @code{el} request, and warnings
13541 Use of the @code{el} request with no matching @code{ie} request.
13546 Meaningless scaling indicators.
13550 Out of range arguments.
13554 Dubious syntax in numeric expressions.
13558 @cindex @code{di} request, and warnings
13559 @cindex @code{da} request, and warnings
13560 Use of @code{di} or @code{da} without an argument when there is no
13565 @cindex @code{de}, @code{de1}, @code{dei} requests, and warnings
13566 @cindex @code{am}, @code{am1}, @code{ami} requests, and warnings
13567 @cindex @code{ds}, @code{ds1} requests, and warnings
13568 @cindex @code{as}, @code{as1} requests, and warnings
13569 @cindex @code{di} request, and warnings
13570 @cindex @code{da} request, and warnings
13571 @cindex @code{box}, @code{boxa} requests, and warnings
13572 @cindex @code{\*}, and warnings
13573 Use of undefined strings, macros and diversions. When an undefined
13574 string, macro, or diversion is used, that string is automatically
13575 defined as empty. So, in most cases, at most one warning is given
13580 @cindex @code{nr} request, and warnings
13581 @cindex @code{\R}, and warnings
13582 @cindex @code{\n}, and warnings
13583 Use of undefined number registers. When an undefined number register is
13584 used, that register is automatically defined to have a value of@tie{}0.
13585 So, in most cases, at most one warning is given for use of a particular
13590 @cindex @code{\t}, and warnings
13591 Use of a tab character where a number was expected.
13595 @cindex @code{\@}}, and warnings
13596 Use of @code{\@}} where a number was expected.
13600 Requests that are missing non-optional arguments.
13604 Invalid input characters.
13608 Unrecognized escape sequences. When an unrecognized escape sequence
13609 @code{\@var{X}} is encountered, the escape character is ignored, and
13610 @var{X} is printed.
13614 @cindex compatibility mode
13615 Missing space between a request or macro and its argument. This warning
13616 is given when an undefined name longer than two characters is
13617 encountered, and the first two characters of the name make a defined
13618 name. The request or macro is not invoked. When this warning is
13619 given, no macro is automatically defined. This is enabled by default.
13620 This warning never occurs in compatibility mode.
13624 Non-existent fonts. This is enabled by default.
13628 Invalid escapes in text ignored with the @code{ig} request. These are
13629 conditions that are errors when they do not occur in ignored text.
13633 Color related warnings.
13636 All warnings except @samp{di}, @samp{mac} and @samp{reg}. It is
13637 intended that this covers all warnings that are useful with traditional
13645 @c =====================================================================
13647 @node Implementation Differences, , Debugging, gtroff Reference
13648 @section Implementation Differences
13649 @cindex implementation differences
13650 @cindex differences in implementation
13651 @cindex incompatibilities with @acronym{AT&T} @code{troff}
13652 @cindex compatibility mode
13653 @cindex mode, compatibility
13655 GNU @code{troff} has a number of features which cause incompatibilities
13656 with documents written with old versions of @code{troff}.
13659 @cindex names, long
13660 Long names cause some incompatibilities. @acronym{UNIX} @code{troff}
13667 @cindex @code{\*}, incompatibilities with @acronym{AT&T} @code{troff}
13668 @cindex @code{\n}, incompatibilities with @acronym{AT&T} @code{troff}
13670 as defining a string @samp{ab} with contents @samp{cd}. Normally, GNU
13671 @code{troff} interprets this as a call of a macro named
13672 @code{dsabcd}. Also @acronym{UNIX} @code{troff} interprets
13673 @code{\*[} or @code{\n[} as references to a string or number register
13674 called @samp{[}. In GNU @code{troff}, however, this is normally
13675 interpreted as the start of a long name. In compatibility mode GNU
13676 @code{troff} interprets long names in the traditional way
13677 (which means that they are not recognized as names).
13679 @DefreqList {cp, [@Var{n}]}
13680 @DefreqItem {do, cmd}
13681 @DefregListEnd {.C}
13682 If @var{n} is missing or non-zero, turn on compatibility mode;
13683 otherwise, turn it off.
13685 The read-only number register @code{.C} is@tie{}1 if compatibility mode is
13686 on, 0@tie{}otherwise.
13688 Compatibility mode can be also turned on with the @option{-C} command line
13691 The @code{do} request turns off compatibility mode
13692 while executing its arguments as a @code{gtroff} command.
13699 executes the @code{fam} request when compatibility mode
13702 @code{gtroff} restores the previous compatibility setting
13703 before interpreting any files sourced by the @var{cmd}.
13706 @cindex input level in delimited arguments
13707 @cindex delimited arguments, incompatibilities with @acronym{AT&T} @code{troff}
13708 Two other features are controlled by @option{-C}. If not in
13709 compatibility mode, GNU @code{troff} preserves the input level in
13710 delimited arguments:
13718 In compatibility mode, the string @samp{72def'} is returned; without
13719 @option{-C} the resulting string is @samp{168} (assuming a TTY output
13722 @cindex @code{\f}, incompatibilities with @acronym{AT&T} @code{troff}
13723 @cindex @code{\H}, incompatibilities with @acronym{AT&T} @code{troff}
13724 @cindex @code{\s}, incompatibilities with @acronym{AT&T} @code{troff}
13725 @cindex @code{\S}, incompatibilities with @acronym{AT&T} @code{troff}
13726 Finally, the escapes @code{\f}, @code{\H}, @code{\m}, @code{\M},
13727 @code{\R}, @code{\s}, and @code{\S} are transparent for recognizing the
13728 beginning of a line only in compatibility mode (this is a rather obscure
13729 feature). For example, the code
13739 prints @samp{Hallo!} in bold face if in compatibility mode, and
13740 @samp{.xx} in bold face otherwise.
13742 @cindex @code{\A}, incompatibilities with @acronym{AT&T} @code{troff}
13743 @cindex @code{\|}, incompatibilities with @acronym{AT&T} @code{troff}
13744 @cindex @code{\^}, incompatibilities with @acronym{AT&T} @code{troff}
13745 @cindex @code{\&}, incompatibilities with @acronym{AT&T} @code{troff}
13746 @cindex @code{\@{}, incompatibilities with @acronym{AT&T} @code{troff}
13747 @cindex @code{\@}}, incompatibilities with @acronym{AT&T} @code{troff}
13748 @cindex @code{\@key{SP}}, 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{\!}, incompatibilities with @acronym{AT&T} @code{troff}
13754 @cindex @code{\%}, incompatibilities with @acronym{AT&T} @code{troff}
13755 @cindex @code{\c}, incompatibilities with @acronym{AT&T} @code{troff}
13756 GNU @code{troff} does not allow the use of the escape sequences
13757 @code{\|}, @code{\^}, @code{\&}, @code{\@{}, @code{\@}},
13758 @code{\@key{SP}}, @code{\'}, @code{\`}, @code{\-}, @code{\_}, @code{\!},
13759 @code{\%}, and @code{\c} in names of strings, macros, diversions, number
13760 registers, fonts or environments; @acronym{UNIX} @code{troff} does. The
13761 @code{\A} escape sequence (@pxref{Identifiers}) may be helpful in
13762 avoiding use of these escape sequences in names.
13764 @cindex fractional point sizes
13765 @cindex fractional type sizes
13766 @cindex point sizes, fractional
13767 @cindex type sizes, fractional
13768 @cindex sizes, fractional
13769 @cindex @code{ps} request, incompatibilities with @acronym{AT&T} @code{troff}
13770 Fractional point sizes cause one noteworthy incompatibility. In
13771 @acronym{UNIX} @code{troff} the @code{ps} request ignores scale
13772 indicators and thus
13779 sets the point size to 10@tie{}points, whereas in GNU @code{troff} it
13780 sets the point size to 10@tie{}scaled points. @xref{Fractional Type
13781 Sizes}, for more information.
13783 @cindex @code{bd} request, incompatibilities with @acronym{AT&T} @code{troff}
13784 @cindex @code{cs} request, incompatibilities with @acronym{AT&T} @code{troff}
13785 @cindex @code{tr} request, incompatibilities with @acronym{AT&T} @code{troff}
13786 @cindex @code{fp} request, incompatibilities with @acronym{AT&T} @code{troff}
13787 @cindex input characters and output glyphs, compatibility with @acronym{AT&T} @code{troff}
13788 @cindex output glyphs, and input characters,compatibility with @acronym{AT&T} @code{troff}
13789 @cindex characters, input, and output glyphs, compatibility with @acronym{AT&T} @code{troff}
13790 @cindex glyphs, output, and input characters, compatibility with @acronym{AT&T} @code{troff}
13791 In GNU @code{troff} there is a fundamental difference between
13792 (unformatted) input characters and (formatted) output glyphs.
13793 Everything that affects how a glyph is output is stored
13794 with the glyph node; once a glyph node has been constructed it is
13795 unaffected by any subsequent requests that are executed, including
13796 @code{bd}, @code{cs}, @code{tkf}, @code{tr}, or @code{fp} requests.
13797 Normally glyphs are constructed from input characters at the
13798 moment immediately before the glyph is added to the current output
13799 line. Macros, diversions and strings are all, in fact, the same type of
13800 object; they contain lists of input characters and glyph nodes in
13801 any combination. A glyph node does not behave like an input
13802 character for the purposes of macro processing; it does not inherit any
13803 of the special properties that the input character from which it was
13804 constructed might have had. For example,
13814 @cindex printing backslash (@code{\\}, @code{\e}, @code{\E}, @code{\[rs]})
13815 @cindex backslash, printing (@code{\\}, @code{\e}, @code{\E}, @code{\[rs]})
13816 @cindex @code{\e}, incompatibilities with @acronym{AT&T} @code{troff}
13817 @cindex @code{\!}, incompatibilities with @acronym{AT&T} @code{troff}
13818 @cindex @code{\?}, incompatibilities with @acronym{AT&T} @code{troff}
13819 @cindex transparent output, incompatibilities with @acronym{AT&T} @code{troff}
13820 @cindex output, transparent, incompatibilities with @acronym{AT&T} @code{troff}
13822 prints @samp{\\} in GNU @code{troff}; each pair of input backslashes
13823 is turned into one output backslash and the resulting output backslashes
13824 are not interpreted as escape characters when they are reread.
13825 @acronym{UNIX} @code{troff} would interpret them as escape characters
13826 when they were reread and would end up printing one @samp{\}. The
13827 correct way to obtain a printable backslash is to use the @code{\e}
13828 escape sequence: This always prints a single instance of the current
13829 escape character, regardless of whether or not it is used in a
13830 diversion; it also works in both GNU @code{troff} and @acronym{UNIX}
13831 @code{troff}.@footnote{To be completely independent of the current
13832 escape character, use @code{\(rs} which represents a reverse solidus
13833 (backslash) glyph.} To store, for some reason, an escape sequence in a
13834 diversion that will be interpreted when the diversion is reread, either
13835 use the traditional @code{\!} transparent output facility, or, if this
13836 is unsuitable, the new @code{\?} escape sequence.
13838 @xref{Diversions}, and @ref{Gtroff Internals}, for more information.
13842 @c =====================================================================
13843 @c =====================================================================
13845 @node Preprocessors, Output Devices, gtroff Reference, Top
13846 @chapter Preprocessors
13847 @cindex preprocessors
13849 This chapter describes all preprocessors that come with @code{groff} or
13850 which are freely available.
13863 @c =====================================================================
13865 @node geqn, gtbl, Preprocessors, Preprocessors
13866 @section @code{geqn}
13867 @cindex @code{eqn}, the program
13868 @cindex @code{geqn}, the program
13876 @c ---------------------------------------------------------------------
13878 @node Invoking geqn, , geqn, geqn
13879 @subsection Invoking @code{geqn}
13880 @cindex invoking @code{geqn}
13881 @cindex @code{geqn}, invoking
13886 @c =====================================================================
13888 @node gtbl, gpic, geqn, Preprocessors
13889 @section @code{gtbl}
13890 @cindex @code{tbl}, the program
13891 @cindex @code{gtbl}, the program
13899 @c ---------------------------------------------------------------------
13901 @node Invoking gtbl, , gtbl, gtbl
13902 @subsection Invoking @code{gtbl}
13903 @cindex invoking @code{gtbl}
13904 @cindex @code{gtbl}, invoking
13909 @c =====================================================================
13911 @node gpic, ggrn, gtbl, Preprocessors
13912 @section @code{gpic}
13913 @cindex @code{pic}, the program
13914 @cindex @code{gpic}, the program
13922 @c ---------------------------------------------------------------------
13924 @node Invoking gpic, , gpic, gpic
13925 @subsection Invoking @code{gpic}
13926 @cindex invoking @code{gpic}
13927 @cindex @code{gpic}, invoking
13932 @c =====================================================================
13934 @node ggrn, grap, gpic, Preprocessors
13935 @section @code{ggrn}
13936 @cindex @code{grn}, the program
13937 @cindex @code{ggrn}, the program
13945 @c ---------------------------------------------------------------------
13947 @node Invoking ggrn, , ggrn, ggrn
13948 @subsection Invoking @code{ggrn}
13949 @cindex invoking @code{ggrn}
13950 @cindex @code{ggrn}, invoking
13955 @c =====================================================================
13957 @node grap, grefer, ggrn, Preprocessors
13958 @section @code{grap}
13959 @cindex @code{grap}, the program
13961 A free implementation of @code{grap}, written by Ted Faber,
13962 is available as an extra package from the following address:
13965 @uref{http://www.lunabase.org/~faber/Vault/software/grap/}
13969 @c =====================================================================
13971 @node grefer, gsoelim, grap, Preprocessors
13972 @section @code{grefer}
13973 @cindex @code{refer}, the program
13974 @cindex @code{grefer}, the program
13979 * Invoking grefer::
13982 @c ---------------------------------------------------------------------
13984 @node Invoking grefer, , grefer, grefer
13985 @subsection Invoking @code{grefer}
13986 @cindex invoking @code{grefer}
13987 @cindex @code{grefer}, invoking
13992 @c =====================================================================
13994 @node gsoelim, , grefer, Preprocessors
13995 @section @code{gsoelim}
13996 @cindex @code{soelim}, the program
13997 @cindex @code{gsoelim}, the program
14002 * Invoking gsoelim::
14005 @c ---------------------------------------------------------------------
14007 @node Invoking gsoelim, , gsoelim, gsoelim
14008 @subsection Invoking @code{gsoelim}
14009 @cindex invoking @code{gsoelim}
14010 @cindex @code{gsoelim}, invoking
14016 @c =====================================================================
14017 @c =====================================================================
14019 @node Output Devices, File formats, Preprocessors, Top
14020 @chapter Output Devices
14021 @cindex output devices
14022 @cindex devices for output
14027 * Special Characters::
14038 @c =====================================================================
14040 @node Special Characters, grotty, Output Devices, Output Devices
14041 @section Special Characters
14042 @cindex special characters
14043 @cindex characters, special
14050 @c =====================================================================
14052 @node grotty, grops, Special Characters, Output Devices
14053 @section @code{grotty}
14054 @cindex @code{grotty}, the program
14059 * Invoking grotty::
14062 @c ---------------------------------------------------------------------
14064 @node Invoking grotty, , grotty, grotty
14065 @subsection Invoking @code{grotty}
14066 @cindex invoking @code{grotty}
14067 @cindex @code{grotty}, invoking
14071 @c The following is no longer true; fix and extend it.
14074 @c @cindex Teletype
14075 @c @cindex ISO 6249 SGR
14076 @c @cindex terminal control sequences
14077 @c @cindex control sequences, for terminals
14078 @c For TTY output devices, underlining is done by emitting sequences of
14079 @c @samp{_} and @samp{\b} (the backspace character) before the actual
14080 @c character. Literally, this is printing an underline character, then
14081 @c moving back one character position, and printing the actual character
14082 @c at the same position as the underline character (similar to a
14083 @c typewriter). Usually, a modern terminal can't interpret this (and the
14084 @c original Teletype machines for which this sequence was appropriate are
14085 @c no longer in use). You need a pager program like @code{less} which
14086 @c translates this into ISO 6429 SGR sequences to control terminals.
14089 @c =====================================================================
14091 @node grops, grodvi, grotty, Output Devices
14092 @section @code{grops}
14093 @cindex @code{grops}, the program
14099 * Embedding PostScript::
14102 @c ---------------------------------------------------------------------
14104 @node Invoking grops, Embedding PostScript, grops, grops
14105 @subsection Invoking @code{grops}
14106 @cindex invoking @code{grops}
14107 @cindex @code{grops}, invoking
14111 @c ---------------------------------------------------------------------
14113 @node Embedding PostScript, , Invoking grops, grops
14114 @subsection Embedding @sc{PostScript}
14115 @cindex embedding PostScript
14116 @cindex PostScript, embedding
14121 @c =====================================================================
14123 @node grodvi, grolj4, grops, Output Devices
14124 @section @code{grodvi}
14125 @cindex @code{grodvi}, the program
14130 * Invoking grodvi::
14133 @c ---------------------------------------------------------------------
14135 @node Invoking grodvi, , grodvi, grodvi
14136 @subsection Invoking @code{grodvi}
14137 @cindex invoking @code{grodvi}
14138 @cindex @code{grodvi}, invoking
14143 @c =====================================================================
14145 @node grolj4, grolbp, grodvi, Output Devices
14146 @section @code{grolj4}
14147 @cindex @code{grolj4}, the program
14152 * Invoking grolj4::
14155 @c ---------------------------------------------------------------------
14157 @node Invoking grolj4, , grolj4, grolj4
14158 @subsection Invoking @code{grolj4}
14159 @cindex invoking @code{grolj4}
14160 @cindex @code{grolj4}, invoking
14165 @c =====================================================================
14167 @node grolbp, grohtml, grolj4, Output Devices
14168 @section @code{grolbp}
14169 @cindex @code{grolbp}, the program
14174 * Invoking grolbp::
14177 @c ---------------------------------------------------------------------
14179 @node Invoking grolbp, , grolbp, grolbp
14180 @subsection Invoking @code{grolbp}
14181 @cindex invoking @code{grolbp}
14182 @cindex @code{grolbp}, invoking
14187 @c =====================================================================
14189 @node grohtml, gxditview, grolbp, Output Devices
14190 @section @code{grohtml}
14191 @cindex @code{grohtml}, the program
14196 * Invoking grohtml::
14197 * grohtml specific registers and strings::
14200 @c ---------------------------------------------------------------------
14202 @node Invoking grohtml, grohtml specific registers and strings, grohtml, grohtml
14203 @subsection Invoking @code{grohtml}
14204 @cindex invoking @code{grohtml}
14205 @cindex @code{grohtml}, invoking
14209 @c ---------------------------------------------------------------------
14211 @node grohtml specific registers and strings, , Invoking grohtml, grohtml
14212 @subsection @code{grohtml} specific registers and strings
14213 @cindex registers specific to @code{grohtml}
14214 @cindex strings specific to @code{grohtml}
14215 @cindex @code{grohtml}, registers and strings
14217 @DefmpregList {ps4html, grohtml}
14218 @DefstrListEnd {www-image-template, grohtml}
14219 The registers @code{ps4html} and @code{www-image-template} are defined
14220 by the @code{pre-grohtml} preprocessor. @code{pre-grohtml} reads in
14221 the @code{troff} input, marks up the inline equations and passes the
14225 troff -Tps -rps4html=1 -dwww-image-template=@var{template}
14235 The PostScript device is used to create all the image files, and the
14236 register @code{ps4html} enables the macro sets to ignore floating
14237 keeps, footers, and headings.
14239 The register @code{www-image-template} is set to the user specified
14240 template name or the default name.
14244 @c =====================================================================
14246 @node gxditview, , grohtml, Output Devices
14247 @section @code{gxditview}
14248 @cindex @code{gxditview}, the program
14253 * Invoking gxditview::
14256 @c ---------------------------------------------------------------------
14258 @node Invoking gxditview, , gxditview, gxditview
14259 @subsection Invoking @code{gxditview}
14260 @cindex invoking @code{gxditview}
14261 @cindex @code{gxditview}, invoking
14268 @c =====================================================================
14269 @c =====================================================================
14271 @node File formats, Installation, Output Devices, Top
14272 @chapter File formats
14273 @cindex file formats
14274 @cindex formats, file
14276 All files read and written by @code{gtroff} are text files. The
14277 following two sections describe their format.
14285 @c =====================================================================
14287 @node gtroff Output, Font Files, File formats, File formats
14288 @section @code{gtroff} Output
14289 @cindex @code{gtroff}, output
14290 @cindex output, @code{gtroff}
14292 This section describes the intermediate output format of GNU
14293 @code{troff}. This output is produced by a run of @code{gtroff}
14294 before it is fed into a device postprocessor program.
14296 As @code{groff} is a wrapper program around @code{gtroff} that
14297 automatically calls a postprocessor, this output does not show up
14298 normally. This is why it is called @dfn{intermediate}.
14299 @code{groff} provides the option @option{-Z} to inhibit postprocessing,
14300 such that the produced intermediate output is sent to standard output
14301 just like calling @code{gtroff} manually.
14303 @cindex troff output
14304 @cindex output, troff
14305 @cindex intermediate output
14306 @cindex output, intermediate
14307 Here, the term @dfn{troff output} describes what is output by
14308 @code{gtroff}, while @dfn{intermediate output} refers to the language
14309 that is accepted by the parser that prepares this output for the
14310 postprocessors. This parser is smarter on whitespace and implements
14311 obsolete elements for compatibility, otherwise both formats are the
14312 same.@footnote{The parser and postprocessor for intermediate output
14313 can be found in the file@*
14314 @file{@var{groff-source-dir}/src/libs/libdriver/input.cpp}.}
14316 The main purpose of the intermediate output concept is to facilitate
14317 the development of postprocessors by providing a common programming
14318 interface for all devices. It has a language of its own that is
14319 completely different from the @code{gtroff} language. While the
14320 @code{gtroff} language is a high-level programming language for text
14321 processing, the intermediate output language is a kind of low-level
14322 assembler language by specifying all positions on the page for writing
14325 The intermediate output produced by @code{gtroff} is fairly readable,
14326 while output from @acronym{AT&T} @code{troff} is rather hard to
14327 understand because of strange habits that are still supported, but not
14328 used any longer by @code{gtroff}.
14331 * Language Concepts::
14332 * Command Reference::
14333 * Intermediate Output Examples::
14334 * Output Language Compatibility::
14337 @c ---------------------------------------------------------------------
14339 @node Language Concepts, Command Reference, gtroff Output, gtroff Output
14340 @subsection Language Concepts
14342 During the run of @code{gtroff}, the input data is cracked down to the
14343 information on what has to be printed at what position on the intended
14344 device. So the language of the intermediate output format can be quite
14345 small. Its only elements are commands with and without arguments.
14346 In this section, the term @dfn{command} always refers to the intermediate
14347 output language, and never to the @code{gtroff} language used for document
14348 formatting. There are commands for positioning and text writing, for drawing, and
14349 for device controlling.
14357 @node Separation, Argument Units, Language Concepts, Language Concepts
14358 @subsubsection Separation
14360 @acronym{AT&T} @code{troff} output has strange requirements on whitespace.
14361 The @code{gtroff} output parser, however, is smart about whitespace by
14362 making it maximally optional. The whitespace characters, i.e., the
14363 tab, space, and newline characters, always have a syntactical meaning.
14364 They are never printable because spacing within the output is always
14365 done by positioning commands.
14367 Any sequence of space or tab characters is treated as a single
14368 @dfn{syntactical space}. It separates commands and arguments, but is
14369 only required when there would occur a clashing between the command code
14370 and the arguments without the space. Most often, this happens when
14371 variable-length command names, arguments, argument lists, or command
14372 clusters meet. Commands and arguments with a known, fixed length need
14373 not be separated by syntactical space.
14375 A line break is a syntactical element, too. Every command argument can be
14376 followed by whitespace, a comment, or a newline character. Thus a
14377 @dfn{syntactical line break} is defined to consist of optional
14378 syntactical space that is optionally followed by a comment, and a
14381 The normal commands, those for positioning and text, consist of a
14382 single letter taking a fixed number of arguments. For historical reasons,
14383 the parser allows to stack such commands on the same line, but
14384 fortunately, in @code{gtroff}'s intermediate output, every command with
14385 at least one argument is followed by a line break, thus providing
14386 excellent readability.
14388 The other commands -- those for drawing and device controlling --
14389 have a more complicated structure; some recognize long command names,
14390 and some take a variable number of arguments. So all @samp{D} and
14391 @samp{x} commands were designed to request a syntactical line break
14392 after their last argument. Only one command, @w{@samp{x X}},
14393 has an argument that can stretch over several lines; all other
14394 commands must have all of their arguments on the same line as the
14395 command, i.e., the arguments may not be splitted by a line break.
14397 Empty lines (these are lines containing only space and/or a comment), can
14398 occur everywhere. They are just ignored.
14400 @node Argument Units, Document Parts, Separation, Language Concepts
14401 @subsubsection Argument Units
14403 Some commands take integer arguments that are assumed to represent
14404 values in a measurement unit, but the letter for the corresponding
14405 scale indicator is not written with the output command arguments.
14406 Most commands assume the scale indicator @samp{u}, the basic unit of
14407 the device, some use @samp{z}, the scaled point unit of the device,
14408 while others, such as the color commands, expect plain integers.
14410 Note that single characters can have the eighth bit set, as can the
14411 names of fonts and special characters. The names of characters and
14412 fonts can be of arbitrary length. A character that is to be printed
14413 will always be in the current font.
14415 A string argument is always terminated by the next whitespace
14416 character (space, tab, or newline); an embedded @samp{#} character is
14417 regarded as part of the argument, not as the beginning of a comment
14418 command. An integer argument is already terminated by the next
14419 non-digit character, which then is regarded as the first character of
14420 the next argument or command.
14422 @node Document Parts, , Argument Units, Language Concepts
14423 @subsubsection Document Parts
14425 A correct intermediate output document consists of two parts, the
14426 @dfn{prologue} and the @dfn{body}.
14428 The task of the prologue is to set the general device parameters
14429 using three exactly specified commands. @code{gtroff}'s prologue
14430 is guaranteed to consist of the following three lines (in that order):
14434 x res @var{n} @var{h} @var{v}
14439 with the arguments set as outlined in @ref{Device Control Commands}.
14440 Note that the parser for the intermediate output format is able to
14441 swallow additional whitespace and comments as well even in the
14444 The body is the main section for processing the document data.
14445 Syntactically, it is a sequence of any commands different from the
14446 ones used in the prologue. Processing is terminated as soon as the
14447 first @w{@samp{x stop}} command is encountered; the last line of any
14448 @code{gtroff} intermediate output always contains such a command.
14450 Semantically, the body is page oriented. A new page is started by a
14451 @samp{p} command. Positioning, writing, and drawing commands are
14452 always done within the current page, so they cannot occur before the
14453 first @samp{p} command. Absolute positioning (by the @samp{H} and
14454 @samp{V} commands) is done relative to the current page; all other
14455 positioning is done relative to the current location within this page.
14457 @c ---------------------------------------------------------------------
14459 @node Command Reference, Intermediate Output Examples, Language Concepts, gtroff Output
14460 @subsection Command Reference
14462 This section describes all intermediate output commands, both from
14463 @acronym{AT&T} @code{troff} as well as the @code{gtroff} extensions.
14466 * Comment Command::
14467 * Simple Commands::
14468 * Graphics Commands::
14469 * Device Control Commands::
14470 * Obsolete Command::
14473 @node Comment Command, Simple Commands, Command Reference, Command Reference
14474 @subsubsection Comment Command
14477 @item #@var{anything}@angles{end of line}
14478 A comment. Ignore any characters from the @samp{#} character up to
14479 the next newline character.
14481 This command is the only possibility for commenting in the intermediate
14482 output. Each comment can be preceded by arbitrary syntactical space;
14483 every command can be terminated by a comment.
14486 @node Simple Commands, Graphics Commands, Comment Command, Command Reference
14487 @subsubsection Simple Commands
14489 The commands in this subsection have a command code consisting of a
14490 single character, taking a fixed number of arguments. Most of them
14491 are commands for positioning and text writing. These commands are
14492 smart about whitespace. Optionally, syntactical space can be inserted
14493 before, after, and between the command letter and its arguments.
14494 All of these commands are stackable, i.e., they can be preceded by
14495 other simple commands or followed by arbitrary other commands on the
14496 same line. A separating syntactical space is only necessary when two
14497 integer arguments would clash or if the preceding argument ends with a
14502 .if (\n[@USE_ENV_STACK] == 1) \{\
14504 Open a new environment by copying the actual device configuration data
14505 to the environment stack.
14507 The current environment is setup by the device specification and
14508 manipulated by the setting commands.
14512 Close the actual environment (opened by a preceding
14514 and restore the previous environment from the environment
14515 stack as the actual device configuration data.
14517 \} \" endif @USE_ENV_STACK
14520 @item C @var{xxx}@angles{whitespace}
14521 Print a special character named @var{xxx}. The trailing
14522 syntactical space or line break is necessary to allow glyph names
14523 of arbitrary length. The glyph is printed at the current print
14524 position; the glyph's size is read from the font file. The print
14525 position is not changed.
14528 Print glyph@tie{}@var{g} at the current print position;@footnote{@samp{c}
14529 is actually a misnomer since it outputs a glyph.} the glyph's size is
14530 read from the font file. The print position is not changed.
14533 Set font to font number@tie{}@var{n} (a non-negative integer).
14536 Move right to the absolute vertical position@tie{}@var{n} (a
14537 non-negative integer in basic units @samp{u} relative to left edge
14541 Move @var{n} (a non-negative integer) basic units @samp{u} horizontally
14542 to the right. The original @acronym{UNIX} troff manual allows negative
14543 values for @var{n} also, but @code{gtroff} doesn't use this.
14545 @item m @var{color-scheme} @r{[}@var{component} @dots{}@r{]}
14546 Set the color for text (glyphs), line drawing, and the outline of
14547 graphic objects using different color schemes; the analoguous command
14548 for the filling color of graphic objects is @samp{DF}. The color
14549 components are specified as integer arguments between 0 and 65536.
14550 The number of color components and their meaning vary for the
14551 different color schemes. These commands are generated by
14552 @code{gtroff}'s escape sequence @code{\m}. No position changing.
14553 These commands are a @code{gtroff} extension.
14556 @item mc @var{cyan} @var{magenta} @var{yellow}
14557 Set color using the CMY color scheme, having the 3@tie{}color components
14558 @var{cyan}, @var{magenta}, and @var{yellow}.
14561 Set color to the default color value (black in most cases).
14562 No component arguments.
14564 @item mg @var{gray}
14565 Set color to the shade of gray given by the argument, an integer
14566 between 0 (black) and 65536 (white).
14568 @item mk @var{cyan} @var{magenta} @var{yellow} @var{black}
14569 Set color using the CMYK color scheme, having the 4@tie{}color components
14570 @var{cyan}, @var{magenta}, @var{yellow}, and @var{black}.
14572 @item mr @var{red} @var{green} @var{blue}
14573 Set color using the RGB color scheme, having the 3@tie{}color components
14574 @var{red}, @var{green}, and @var{blue}.
14578 Print glyph with index@tie{}@var{n} (a non-negative integer) of the
14579 current font. This command is a @code{gtroff} extension.
14581 @item n @var{b} @var{a}
14582 Inform the device about a line break, but no positioning is done by
14583 this command. In @acronym{AT&T} @code{troff}, the integer arguments
14584 @var{b} and@tie{}@var{a} informed about the space before and after the
14585 current line to make the intermediate output more human readable
14586 without performing any action. In @code{groff}, they are just ignored, but
14587 they must be provided for compatibility reasons.
14590 Begin a new page in the outprint. The page number is set
14591 to@tie{}@var{n}. This page is completely independent of pages formerly
14592 processed even if those have the same page number. The vertical
14593 position on the outprint is automatically set to@tie{}0. All
14594 positioning, writing, and drawing is always done relative to a page,
14595 so a @samp{p} command must be issued before any of these commands.
14598 Set point size to @var{n}@tie{}scaled points (this is unit @samp{z}).
14599 @acronym{AT&T} @code{troff} used the unit points (@samp{p}) instead.
14600 @xref{Output Language Compatibility}.
14602 @item t @var{xxx}@angles{whitespace}
14603 @itemx t @var{xxx} @var{dummy-arg}@angles{whitespace}
14604 Print a word, i.e., a sequence of characters @var{xxx} representing
14605 output glyphs which names are single characters, terminated by
14606 a space character or a line break; an optional second integer argument
14607 is ignored (this allows the formatter to generate an even number of
14608 arguments). The first glyph should be printed at the current
14609 position, the current horizontal position should then be increased by
14610 the width of the first glyph, and so on for each glyph.
14611 The widths of the glyphs are read from the font file, scaled for the
14612 current point size, and rounded to a multiple of the horizontal
14613 resolution. Special characters cannot be printed using this command
14614 (use the @samp{C} command for special characters). This command is a
14615 @code{gtroff} extension; it is only used for devices whose @file{DESC}
14616 file contains the @code{tcommand} keyword (@pxref{DESC File Format}).
14618 @item u @var{n} @var{xxx}@angles{whitespace}
14619 Print word with track kerning. This is the same as the @samp{t}
14620 command except that after printing each glyph, the current
14621 horizontal position is increased by the sum of the width of that
14622 glyph and@tie{}@var{n} (an integer in basic units @samp{u}).
14623 This command is a @code{gtroff} extension; it is only used for devices
14624 whose @file{DESC} file contains the @code{tcommand} keyword
14625 (@pxref{DESC File Format}).
14628 Move down to the absolute vertical position@tie{}@var{n} (a
14629 non-negative integer in basic units @samp{u}) relative to upper edge
14633 Move @var{n}@tie{}basic units @samp{u} down (@var{n} is a non-negative
14634 integer). The original @acronym{UNIX} troff manual allows negative
14635 values for @var{n} also, but @code{gtroff} doesn't use this.
14638 Informs about a paddable white space to increase readability.
14639 The spacing itself must be performed explicitly by a move command.
14642 @node Graphics Commands, Device Control Commands, Simple Commands, Command Reference
14643 @subsubsection Graphics Commands
14645 Each graphics or drawing command in the intermediate output starts
14646 with the letter @samp{D}, followed by one or two characters that
14647 specify a subcommand; this is followed by a fixed or variable number
14648 of integer arguments that are separated by a single space character.
14649 A @samp{D} command may not be followed by another command on the same line
14650 (apart from a comment), so each @samp{D} command is terminated by a
14651 syntactical line break.
14653 @code{gtroff} output follows the classical spacing rules (no space
14654 between command and subcommand, all arguments are preceded by a
14655 single space character), but the parser allows optional space between
14656 the command letters and makes the space before the first argument
14657 optional. As usual, each space can be any sequence of tab and space
14660 Some graphics commands can take a variable number of arguments.
14661 In this case, they are integers representing a size measured in basic
14662 units @samp{u}. The arguments called @var{h1}, @var{h2}, @dots{},
14663 @var{hn} stand for horizontal distances where positive means right,
14664 negative left. The arguments called @var{v1}, @var{v2}, @dots{},
14665 @var{vn} stand for vertical distances where positive means down,
14666 negative up. All these distances are offsets relative to the current
14669 Each graphics command directly corresponds to a similar @code{gtroff}
14670 @code{\D} escape sequence. @xref{Drawing Requests}.
14672 Unknown @samp{D} commands are assumed to be device-specific.
14673 Its arguments are parsed as strings; the whole information is then
14674 sent to the postprocessor.
14676 In the following command reference, the syntax element
14677 @angles{line break} means a syntactical line break as defined above.
14680 @item D~ @var{h1} @var{v1} @var{h2} @var{v2} @dots{} @var{hn} @var{vn}@angles{line break}
14681 Draw B-spline from current position to offset (@var{h1},@var{v1}),
14682 then to offset (@var{h2},@var{v2}), if given, etc.@: up to
14683 (@var{hn},@var{vn}). This command takes a variable number of argument
14684 pairs; the current position is moved to the terminal point of the drawn
14687 @item Da @var{h1} @var{v1} @var{h2} @var{v2}@angles{line break}
14688 Draw arc from current position to
14689 (@var{h1},@var{v1})@math{+}(@var{h2},@var{v2}) with center at
14690 (@var{h1},@var{v1}); then move the current position to the final point
14693 @item DC @var{d}@angles{line break}
14694 @itemx DC @var{d} @var{dummy-arg}@angles{line break}
14695 Draw a solid circle using the current fill color with
14696 diameter@tie{}@var{d} (integer in basic units @samp{u}) with leftmost
14697 point at the current position; then move the current position to the
14698 rightmost point of the circle. An optional second integer argument is
14699 ignored (this allows the formatter to generate an even number of
14700 arguments). This command is a @code{gtroff} extension.
14702 @item Dc @var{d}@angles{line break}
14703 Draw circle line with diameter@tie{}@var{d} (integer in basic units
14704 @samp{u}) with leftmost point at the current position; then move the
14705 current position to the rightmost point of the circle.
14707 @item DE @var{h} @var{v}@angles{line break}
14708 Draw a solid ellipse in the current fill color with a horizontal
14709 diameter of@tie{}@var{h} and a vertical diameter of@tie{}@var{v} (both
14710 integers in basic units @samp{u}) with the leftmost point at the
14711 current position; then move to the rightmost point of the ellipse.
14712 This command is a @code{gtroff} extension.
14714 @item De @var{h} @var{v}@angles{line break}
14715 Draw an outlined ellipse with a horizontal diameter of@tie{}@var{h}
14716 and a vertical diameter of@tie{}@var{v} (both integers in basic units
14717 @samp{u}) with the leftmost point at current position; then move to
14718 the rightmost point of the ellipse.
14720 @item DF @var{color-scheme} @r{[}@var{component} @dots{}@r{]}@angles{line break}
14721 Set fill color for solid drawing objects using different color
14722 schemes; the analoguous command for setting the color of text, line
14723 graphics, and the outline of graphic objects is @samp{m}.
14724 The color components are specified as integer arguments between 0 and
14725 65536. The number of color components and their meaning vary for the
14726 different color schemes. These commands are generated by @code{gtroff}'s
14727 escape sequences @w{@code{\D'F @dots{}'}} and @code{\M} (with no other
14728 corresponding graphics commands). No position changing. This command
14729 is a @code{gtroff} extension.
14732 @item DFc @var{cyan} @var{magenta} @var{yellow}@angles{line break}
14733 Set fill color for solid drawing objects using the CMY color scheme,
14734 having the 3@tie{}color components @var{cyan}, @var{magenta}, and
14737 @item DFd@angles{line break}
14738 Set fill color for solid drawing objects to the default fill color value
14739 (black in most cases). No component arguments.
14741 @item DFg @var{gray}@angles{line break}
14742 Set fill color for solid drawing objects to the shade of gray given by
14743 the argument, an integer between 0 (black) and 65536 (white).
14745 @item DFk @var{cyan} @var{magenta} @var{yellow} @var{black}@angles{line break}
14746 Set fill color for solid drawing objects using the CMYK color scheme,
14747 having the 4@tie{}color components @var{cyan}, @var{magenta}, @var{yellow},
14750 @item DFr @var{red} @var{green} @var{blue}@angles{line break}
14751 Set fill color for solid drawing objects using the RGB color scheme,
14752 having the 3@tie{}color components @var{red}, @var{green}, and @var{blue}.
14755 @item Df @var{n}@angles{line break}
14756 The argument@tie{}@var{n} must be an integer in the range @math{-32767}
14760 @item @math{0 @LE{} @var{n} @LE{} 1000}
14761 Set the color for filling solid drawing objects to a shade of gray,
14762 where 0 corresponds to solid white, 1000 (the default) to solid black,
14763 and values in between to intermediate shades of gray; this is
14764 obsoleted by command @samp{DFg}.
14766 @item @math{@var{n} < 0} or @math{@var{n} > 1000}
14767 Set the filling color to the color that is currently being used for
14768 the text and the outline, see command @samp{m}. For example, the
14777 sets all colors to blue.
14781 No position changing. This command is a @code{gtroff} extension.
14783 @item Dl @var{h} @var{v}@angles{line break}
14784 Draw line from current position to offset (@var{h},@var{v}) (integers
14785 in basic units @samp{u}); then set current position to the end of the
14788 @item Dp @var{h1} @var{v1} @var{h2} @var{v2} @dots{} @var{hn} @var{vn}@angles{line break}
14789 Draw a polygon line from current position to offset (@var{h1},@var{v1}),
14790 from there to offset (@var{h2},@var{v2}), etc.@: up to offset
14791 (@var{hn},@var{vn}), and from there back to the starting position.
14792 For historical reasons, the position is changed by adding the sum of
14793 all arguments with odd index to the actual horizontal position and the
14794 even ones to the vertical position. Although this doesn't make sense
14795 it is kept for compatibility.
14797 As the polygon is closed, the end of drawing is the starting point, so
14798 the position doesn't change.
14800 This command is a @code{gtroff} extension.
14802 @item Dp @var{h1} @var{v1} @var{h2} @var{v2} @dots{} @var{hn} @var{vn}@angles{line break}
14803 Draw a solid polygon in the current fill color rather than an outlined
14804 polygon, using the same arguments and positioning as the corresponding
14807 No position changing.
14809 This command is a @code{gtroff} extension.
14811 @item Dt @var{n}@angles{line break}
14812 Set the current line thickness to@tie{}@var{n} (an integer in basic
14813 units @samp{u}) if @math{@var{n}>0}; if @math{@var{n}=0} select the
14814 smallest available line thickness; if @math{@var{n}<0} set the line
14815 thickness proportional to the point size (this is the default before
14816 the first @samp{Dt} command was specified). For historical reasons,
14817 the horizontal position is changed by adding the argument to the actual
14818 horizontal position, while the vertical position is not changed.
14819 Although this doesn't make sense it is kept for compatibility.
14821 No position changing.
14823 This command is a @code{gtroff} extension.
14826 @node Device Control Commands, Obsolete Command, Graphics Commands, Command Reference
14827 @subsubsection Device Control Commands
14829 Each device control command starts with the letter @samp{x},
14830 followed by a space character (optional or arbitrary space or tab in
14831 @code{gtroff}) and a subcommand letter or word; each argument (if any)
14832 must be preceded by a syntactical space. All @samp{x} commands are
14833 terminated by a syntactical line break; no device control command can
14834 be followed by another command on the same line (except a comment).
14836 The subcommand is basically a single letter, but to increase
14837 readability, it can be written as a word, i.e., an arbitrary sequence
14838 of characters terminated by the next tab, space, or newline character.
14839 All characters of the subcommand word but the first are simply ignored.
14840 For example, @code{gtroff} outputs the initialization command
14841 @w{@samp{x i}} as @w{@samp{x init}} and the resolution command
14842 @w{@samp{x r}} as @w{@samp{x res}}.
14844 In the following, the syntax element @angles{line break} means a
14845 syntactical line break (@pxref{Separation}).
14848 @item xF @var{name}@angles{line break}
14849 The @samp{F} stands for @var{Filename}.
14851 Use @var{name} as the intended name for the current file in error
14852 reports. This is useful for remembering the original file name when
14853 @code{gtroff} uses an internal piping mechanism. The input file is
14854 not changed by this command. This command is a @code{gtroff} extension.
14856 @item xf @var{n} @var{s}@angles{line break}
14857 The @samp{f} stands for @var{font}.
14859 Mount font position@tie{}@var{n} (a non-negative integer) with font
14860 named@tie{}@var{s} (a text word). @xref{Font Positions}.
14862 @item xH @var{n}@angles{line break}
14863 The @samp{H} stands for @var{Height}.
14865 Set glyph height to@tie{}@var{n} (a positive integer in scaled
14866 points @samp{z}). @acronym{AT&T} @code{troff} uses the unit points
14867 (@samp{p}) instead. @xref{Output Language Compatibility}.
14869 @item xi@angles{line break}
14870 The @samp{i} stands for @var{init}.
14872 Initialize device. This is the third command of the prologue.
14874 @item xp@angles{line break}
14875 The @samp{p} stands for @var{pause}.
14877 Parsed but ignored. The original @acronym{UNIX} troff manual writes
14880 pause device, can be restarted
14883 @item xr @var{n} @var{h} @var{v}@angles{line break}
14884 The @samp{r} stands for @var{resolution}.
14886 Resolution is@tie{}@var{n}, while @var{h} is the minimal horizontal
14887 motion, and @var{v} the minimal vertical motion possible with this
14888 device; all arguments are positive integers in basic units @samp{u}
14889 per inch. This is the second command of the prologue.
14891 @item xS @var{n}@angles{line break}
14892 The @samp{S} stands for @var{Slant}.
14894 Set slant to@tie{}@var{n} (an integer in basic units @samp{u}).
14896 @item xs@angles{line break}
14897 The @samp{s} stands for @var{stop}.
14899 Terminates the processing of the current file; issued as the last
14900 command of any intermediate troff output.
14902 @item xt@angles{line break}
14903 The @samp{t} stands for @var{trailer}.
14905 Generate trailer information, if any. In @var{gtroff}, this is
14906 actually just ignored.
14908 @item xT @var{xxx}@angles{line break}
14909 The @samp{T} stands for @var{Typesetter}.
14911 Set name of device to word @var{xxx}, a sequence of characters ended
14912 by the next white space character. The possible device names coincide
14913 with those from the @code{groff} @option{-T} option. This is the first
14914 command of the prologue.
14916 @item xu @var{n}@angles{line break}
14917 The @samp{u} stands for @var{underline}.
14919 Configure underlining of spaces. If @var{n} is@tie{}1, start
14920 underlining of spaces; if @var{n} is@tie{}0, stop underlining of spaces.
14921 This is needed for the @code{cu} request in nroff mode and is ignored
14922 otherwise. This command is a @code{gtroff} extension.
14924 @item xX @var{anything}@angles{line break}
14925 The @samp{x} stands for @var{X-escape}.
14927 Send string @var{anything} uninterpreted to the device. If the line
14928 following this command starts with a @samp{+} character this line is
14929 interpreted as a continuation line in the following sense. The
14930 @samp{+} is ignored, but a newline character is sent instead to the
14931 device, the rest of the line is sent uninterpreted. The same applies
14932 to all following lines until the first character of a line is not a
14933 @samp{+} character. This command is generated by the @code{gtroff}
14934 escape sequence @code{\X}. The line-continuing feature is a
14935 @code{gtroff} extension.
14938 @node Obsolete Command, , Device Control Commands, Command Reference
14939 @subsubsection Obsolete Command
14940 In @acronym{AT&T} @code{troff} output, the writing of a single
14941 glyph is mostly done by a very strange command that combines a
14942 horizontal move and a single character giving the glyph name. It
14943 doesn't have a command code, but is represented by a 3-character
14944 argument consisting of exactly 2@tie{}digits and a character.
14947 @item @var{dd}@var{g}
14948 Move right @var{dd} (exactly two decimal digits) basic units @samp{u},
14949 then print glyph@tie{}@var{g} (represented as a single character).
14951 In @code{gtroff}, arbitrary syntactical space around and within this
14952 command is allowed to be added. Only when a preceding command on the
14953 same line ends with an argument of variable length a separating space
14954 is obligatory. In @acronym{AT&T} @code{troff}, large clusters of these
14955 and other commands are used, mostly without spaces; this made such output
14959 For modern high-resolution devices, this command does not make sense
14960 because the width of the glyphs can become much larger than two
14961 decimal digits. In @code{gtroff}, this is only used for the devices
14962 @code{X75}, @code{X75-12}, @code{X100}, and @code{X100-12}. For other
14963 devices, the commands @samp{t} and @samp{u} provide a better
14966 @c ---------------------------------------------------------------------
14968 @node Intermediate Output Examples, Output Language Compatibility, Command Reference, gtroff Output
14969 @subsection Intermediate Output Examples
14971 This section presents the intermediate output generated from the same
14972 input for three different devices. The input is the sentence
14973 @samp{hell world} fed into @code{gtroff} on the command line.
14976 @item High-resolution device @code{ps}
14978 This is the standard output of @code{gtroff} if no @option{-T} option
14983 shell> echo "hell world" | groff -Z -T ps
15009 This output can be fed into @code{grops} to get its representation as
15012 @item Low-resolution device @code{latin1}
15014 This is similar to the high-resolution device except that the
15015 positioning is done at a minor scale. Some comments (lines starting
15016 with @samp{#}) were added for clarification; they were not generated
15021 shell> echo "hell world" | groff -Z -T latin1
15034 # initial positioning on the page
15037 # write text `hell'
15039 # inform about space, and issue a horizontal jump
15041 # write text `world'
15043 # announce line break, but do nothing because ...
15046 # ... the end of the document has been reached
15054 This output can be fed into @code{grotty} to get a formatted text
15057 @item @acronym{AT&T} @code{troff} output
15058 Since a computer monitor has a very low resolution compared to modern
15059 printers the intermediate output for the X@tie{}Window devices can use
15060 the jump-and-write command with its 2-digit displacements.
15064 shell> echo "hell world" | groff -Z -T X100
15076 # write text with jump-and-write commands
15077 ch07e07l03lw06w11o07r05l03dh7
15087 This output can be fed into @code{xditview} or @code{gxditview}
15088 for displaying in@tie{}X.
15090 Due to the obsolete jump-and-write command, the text clusters in the
15091 @acronym{AT&T} @code{troff} output are almost unreadable.
15094 @c ---------------------------------------------------------------------
15096 @node Output Language Compatibility, , Intermediate Output Examples, gtroff Output
15097 @subsection Output Language Compatibility
15099 The intermediate output language of @acronym{AT&T} @code{troff}
15100 was first documented in the @acronym{UNIX} troff manual, with later
15101 additions documented in @cite{A Typesetter-indenpendent TROFF},
15102 written by Brian Kernighan.
15104 The @code{gtroff} intermediate output format is compatible with this
15105 specification except for the following features.
15109 The classical quasi device independence is not yet implemented.
15112 The old hardware was very different from what we use today. So the
15113 @code{groff} devices are also fundamentally different from the ones in
15114 @acronym{AT&T} @code{troff}. For example, the @acronym{AT&T}
15115 PostScript device is called @code{post} and has a resolution of only
15116 720 units per inch, suitable for printers 20 years ago, while
15117 @code{groff}'s @code{ps} device has a resolution of
15118 72000 units per inch. Maybe, by implementing some rescaling
15119 mechanism similar to the classical quasi device independence,
15120 @code{groff} could emulate @acronym{AT&T}'s @code{post} device.
15123 The B-spline command @samp{D~} is correctly handled by the
15124 intermediate output parser, but the drawing routines aren't
15125 implemented in some of the postprocessor programs.
15128 The argument of the commands @samp{s} and @w{@samp{x H}} has the
15129 implicit unit scaled point @samp{z} in @code{gtroff}, while
15130 @acronym{AT&T} @code{troff} has point (@samp{p}). This isn't an
15131 incompatibility but a compatible extension, for both units coincide
15132 for all devices without a @code{sizescale} parameter in the @file{DESC}
15133 file, including all postprocessors from @acronym{AT&T} and
15134 @code{groff}'s text devices. The few @code{groff} devices with
15135 a @code{sizescale} parameter either do not exist for @acronym{AT&T}
15136 @code{troff}, have a different name, or seem to have a different
15137 resolution. So conflicts are very unlikely.
15140 The position changing after the commands @samp{Dp}, @samp{DP}, and
15141 @samp{Dt} is illogical, but as old versions of @code{gtroff} used this
15142 feature it is kept for compatibility reasons.
15145 Temporarily, there existed some confusion on the positioning after the
15146 @samp{D} commands that are groff extensions. This has been clarified
15147 by establishing the classical rule for all @code{groff} drawing commands:
15151 The position after a graphic object has been drawn is at its end;
15152 for circles and ellipses, the `end' is at the right side.
15155 From this, the positionings specified for the drawing commands above
15156 follow quite naturally.
15163 @c =====================================================================
15165 @node Font Files, , gtroff Output, File formats
15166 @section Font Files
15168 @cindex files, font
15170 The @code{gtroff} font format is roughly a superset of the
15171 @code{ditroff} font format (as used in later versions of @acronym{AT&T}
15172 @code{troff} and its descendants). Unlike the @code{ditroff} font
15173 format, there is no associated binary format; all files are text
15174 files.@footnote{Plan@tie{}9 @code{troff} has also abandoned the binary
15175 format.} The font files for device @var{name} are stored in a directory
15176 @file{dev@var{name}}. There are two types of file: a device description
15177 file called @file{DESC} and for each font@tie{}@var{f} a font file
15178 called@tie{}@file{@var{f}}.
15181 * DESC File Format::
15182 * Font File Format::
15185 @c ---------------------------------------------------------------------
15187 @node DESC File Format, Font File Format, Font Files, Font Files
15188 @subsection @file{DESC} File Format
15189 @cindex @file{DESC} file, format
15190 @cindex font description file, format
15191 @cindex format of font description file
15192 @pindex DESC@r{ file format}
15194 The @file{DESC} file can contain the following types of line. Except
15195 for the @code{charset} keyword which must comes last (if at all), the
15196 order of the lines is not important.
15201 @cindex device resolution
15202 @cindex resolution, device
15203 There are @var{n}@tie{}machine units per inch.
15207 @cindex horizontal resolution
15208 @cindex resolution, horizontal
15209 The horizontal resolution is @var{n}@tie{}machine units. All horizontal
15210 quantities are rounded to be multiples of this value.
15214 @cindex vertical resolution
15215 @cindex resolution, vertical
15216 The vertical resolution is @var{n}@tie{}machine units. All vertical
15217 quantities are rounded to be multiples of this value.
15219 @item sizescale @var{n}
15221 The scale factor for point sizes. By default this has a value of@tie{}1.
15222 One scaled point is equal to one point/@var{n}. The arguments to the
15223 @code{unitwidth} and @code{sizes} commands are given in scaled points.
15224 @xref{Fractional Type Sizes}, for more information.
15226 @item unitwidth @var{n}
15228 Quantities in the font files are given in machine units for fonts whose
15229 point size is @var{n}@tie{}scaled points.
15231 @item prepro @var{program}
15233 Call @var{program} as a preprocessor. Currently, this keyword is used
15234 by @code{groff} with option @option{-Thtml} only.
15236 @item postpro @var{program}
15238 Call @var{program} as a postprocessor. For example, the line
15245 in the file @file{devdvi/DESC} makes @code{groff} call @code{grodvi}
15246 if option @option{-Tdvi} is given (and @option{-Z} isn't used).
15250 This means that the postprocessor can handle the @samp{t} and @samp{u}
15251 intermediate output commands.
15253 @item sizes @var{s1} @var{s2} @dots{} @var{sn} 0
15255 This means that the device has fonts at @var{s1}, @var{s2}, @dots{}
15256 @var{sn} scaled points. The list of sizes must be terminated by@tie{}0
15257 (this is digit zero). Each @var{si} can also be a range of sizes
15258 @var{m}-@var{n}. The list can extend over more than one line.
15260 @item styles @var{S1} @var{S2} @dots{} @var{Sm}
15262 The first @var{m}@tie{}font positions are associated with styles
15263 @var{S1} @dots{} @var{Sm}.
15265 @item fonts @var{n} @var{F1} @var{F2} @var{F3} @dots{} @var{Fn}
15267 Fonts @var{F1} @dots{} @var{Fn} are mounted in the font positions
15268 @var{m}+1, @dots{}, @var{m}+@var{n} where @var{m} is the number of
15269 styles. This command may extend over more than one line. A font name
15270 of@tie{}0 means no font is mounted on the corresponding font position.
15272 @item family @var{fam}
15274 The default font family is @var{fam}.
15276 @item use_charnames_in_special
15277 @kindex use_charnames_in_special
15278 This command indicates that @code{gtroff} should encode special
15279 characters inside special commands. Currently, this is only used
15280 by the @acronym{HTML} output device. @xref{Postprocessor Access}.
15282 @item papersize @var{string} @dots{}
15284 Select a paper size. Valid values for @var{string} are the ISO paper
15285 types @code{A0}-@code{A7}, @code{B0}-@code{B7}, @code{C0}-@code{C7},
15286 @code{D0}-@code{D7}, @code{DL}, and the US paper types @code{letter},
15287 @code{legal}, @code{tabloid}, @code{ledger}, @code{statement},
15288 @code{executive}, @code{com10}, and @code{monarch}. Case is not significant
15289 for @var{string} if it holds predefined paper types. Alternatively,
15290 @var{string} can be a file name (e.g.@: @file{/etc/papersize}); if the file
15291 can be opened, @code{groff} reads the first line and tests for the above
15292 paper sizes. Finally, @var{string} can be a custom paper size in the format
15293 @code{@var{length},@var{width}} (no spaces before and after the comma).
15294 Both @var{length} and @var{width} must have a unit appended; valid values
15295 are @samp{i} for inches, @samp{C} for centimeters, @samp{p} for points, and
15296 @samp{P} for picas. Example: @code{12c,235p}. An argument which starts
15297 with a digit is always treated as a custom paper format. @code{papersize}
15298 sets both the vertical and horizontal dimension of the output medium.
15300 More than one argument can be specified; @code{groff} scans from left to
15301 right and uses the first valid paper specification.
15303 @item pass_filenames
15304 @kindex pass_filenames
15305 Tell @code{gtroff} to emit the name of the source file currently
15306 being processed. This is achieved by the intermediate output command
15307 @samp{F}. Currently, this is only used by the @acronym{HTML} output
15310 @item print @var{program}
15312 Use @var{program} as a spooler program for printing. If omitted,
15313 the @option{-l} and @option{-L} options of @code{groff} are ignored.
15317 This line and everything following in the file are ignored. It is
15318 allowed for the sake of backwards compatibility.
15321 The @code{res}, @code{unitwidth}, @code{fonts}, and @code{sizes} lines
15322 are mandatory. Other commands are ignored by @code{gtroff} but may be
15323 used by postprocessors to store arbitrary information about the device
15324 in the @file{DESC} file.
15328 @kindex biggestfont
15329 Here a list of obsolete keywords which are recognized by @code{groff}
15330 but completely ignored: @code{spare1}, @code{spare2},
15331 @code{biggestfont}.
15333 @c ---------------------------------------------------------------------
15335 @node Font File Format, , DESC File Format, Font Files
15336 @subsection Font File Format
15337 @cindex font file, format
15338 @cindex font description file, format
15339 @cindex format of font files
15340 @cindex format of font description files
15342 A @dfn{font file}, also (and probably better) called a @dfn{font
15343 description file}, has two sections. The first section is a sequence
15344 of lines each containing a sequence of blank delimited words; the first
15345 word in the line is a key, and subsequent words give a value for that
15351 The name of the font is@tie{}@var{f}.
15353 @item spacewidth @var{n}
15355 The normal width of a space is@tie{}@var{n}.
15357 @item slant @var{n}
15359 The glyphs of the font have a slant of @var{n}@tie{}degrees.
15360 (Positive means forward.)
15362 @item ligatures @var{lig1} @var{lig2} @dots{} @var{lign} [0]
15364 Glyphs @var{lig1}, @var{lig2}, @dots{}, @var{lign} are ligatures;
15365 possible ligatures are @samp{ff}, @samp{fi}, @samp{fl}, @samp{ffi} and
15366 @samp{ffl}. For backwards compatibility, the list of ligatures may be
15367 terminated with a@tie{}0. The list of ligatures may not extend over more
15371 @cindex special fonts
15373 The font is @dfn{special}; this means that when a glyph is requested
15374 that is not present in the current font, it is searched for in any
15375 special fonts that are mounted.
15378 Other commands are ignored by @code{gtroff} but may be used by
15379 postprocessors to store arbitrary information about the font in the font
15382 @cindex comments in font files
15383 @cindex font files, comments
15385 The first section can contain comments which start with the @samp{#}
15386 character and extend to the end of a line.
15388 The second section contains one or two subsections. It must contain a
15389 @code{charset} subsection and it may also contain a @code{kernpairs}
15390 subsection. These subsections can appear in any order. Each
15391 subsection starts with a word on a line by itself.
15394 The word @code{charset} starts the character set
15395 subsection.@footnote{This keyword is misnamed since it starts a list
15396 of ordered glyphs, not characters.} The @code{charset} line is
15397 followed by a sequence of lines. Each line gives information for one
15398 glyph. A line comprises a number of fields separated by blanks or
15399 tabs. The format is
15402 @var{name} @var{metrics} @var{type} @var{code}
15403 [@var{entity-name}] [@code{--} @var{comment}]
15406 @cindex 8-bit input
15407 @cindex input, 8-bit
15408 @cindex accessing unnamed glyphs with @code{\N}
15409 @cindex unnamed glyphs, accessing with @code{\N}
15410 @cindex characters, unnamed, accessing with @code{\N}
15411 @cindex glyphs, unnamed, accessing with @code{\N}
15414 @var{name} identifies the glyph name@footnote{The distinction between
15415 input, characters, and output, glyphs, is not clearly separated in the
15416 terminology of @code{groff}; for example, the @code{char} request
15417 should be called @code{glyph} since it defines an output entity.}:
15418 If @var{name} is a single character@tie{}@var{c} then it corresponds
15419 to the @code{gtroff} input character@tie{}@var{c}; if it is of the form
15420 @samp{\@var{c}} where @var{c} is a single character, then it
15421 corresponds to the special character @code{\[@var{c}]}; otherwise it
15422 corresponds to the special character @samp{\[@var{name}]}. If it
15423 is exactly two characters @var{xx} it can be entered as
15424 @samp{\(@var{xx}}. Note that single-letter special characters can't
15425 be accessed as @samp{\@var{c}}; the only exception is @samp{\-} which
15426 is identical to @code{\[-]}.
15428 @code{gtroff} supports 8-bit input characters; however some utilities
15429 have difficulties with eight-bit characters. For this reason, there is
15430 a convention that the entity name @samp{char@var{n}} is equivalent to
15431 the single input character whose code is@tie{}@var{n}. For example,
15432 @samp{char163} would be equivalent to the character with code@tie{}163
15433 which is the pounds sterling sign in the ISO@tie{}@w{Latin-1} character set.
15434 You shouldn't use @samp{char@var{n}} entities in font description files
15435 since they are related to input, not output. Otherwise, you get
15436 hard-coded connections between input and output encoding which
15437 prevents use of different (input) character sets.
15439 The name @samp{---} is special and indicates that the glyph is
15440 unnamed; such glyphs can only be used by means of the @code{\N}
15441 escape sequence in @code{gtroff}.
15443 The @var{type} field gives the glyph type:
15447 the glyph has a descender, for example, @samp{p};
15450 the glyph has an ascender, for example, @samp{b};
15453 the glyph has both an ascender and a descender, for example, @samp{(}.
15456 The @var{code} field gives the code which the postprocessor uses to
15457 print the glyph. The glyph can also be input to @code{gtroff}
15458 using this code by means of the @code{\N} escape sequence. @var{code}
15459 can be any integer. If it starts with @samp{0} it is interpreted as
15460 octal; if it starts with @samp{0x} or @samp{0X} it is interpreted as
15461 hexadecimal. Note, however, that the @code{\N} escape sequence only
15462 accepts a decimal integer.
15464 The @var{entity-name} field gives an @acronym{ASCII} string
15465 identifying the glyph which the postprocessor uses to print the
15466 @code{gtroff} glyph @var{name}. This field is optional and has been
15467 introduced so that the @acronym{HTML} device driver can encode its
15468 character set. For example, the glyph @samp{\[Po]} is
15469 represented as @samp{£} in @acronym{HTML} 4.0.
15471 Anything on the line after the @var{entity-name} field resp.@: after
15472 @samp{--} will be ignored.
15474 The @var{metrics} field has the form:
15478 @var{width}[@code{,}@var{height}[@code{,}@var{depth}[@code{,}@var{italic-correction}
15479 [@code{,}@var{left-italic-correction}[@code{,}@var{subscript-correction}]]]]]
15484 There must not be any spaces between these subfields (it has been split
15485 here into two lines for better legibility only). Missing subfields are
15486 assumed to be@tie{}0. The subfields are all decimal integers. Since
15487 there is no associated binary format, these values are not required to
15488 fit into a variable of type @samp{char} as they are in @code{ditroff}.
15489 The @var{width} subfield gives the width of the glyph. The @var{height}
15490 subfield gives the height of the glyph (upwards is positive); if a
15491 glyph does not extend above the baseline, it should be given a zero
15492 height, rather than a negative height. The @var{depth} subfield gives
15493 the depth of the glyph, that is, the distance from the baseline to the
15494 lowest point below the baseline to which the glyph extends (downwards is
15495 positive); if a glyph does not extend below the baseline, it should be
15496 given a zero depth, rather than a negative depth. The
15497 @var{italic-correction} subfield gives the amount of space that should
15498 be added after the glyph when it is immediately to be followed by a
15499 glyph from a roman font. The @var{left-italic-correction} subfield
15500 gives the amount of space that should be added before the glyph when it
15501 is immediately to be preceded by a glyph from a roman font. The
15502 @var{subscript-correction} gives the amount of space that should be
15503 added after a glyph before adding a subscript. This should be less
15504 than the italic correction.
15506 A line in the @code{charset} section can also have the format
15513 This indicates that @var{name} is just another name for the glyph
15514 mentioned in the preceding line.
15517 The word @code{kernpairs} starts the kernpairs section. This contains a
15518 sequence of lines of the form:
15521 @var{c1} @var{c2} @var{n}
15525 This means that when glyph @var{c1} appears next to glyph @var{c2}
15526 the space between them should be increased by@tie{}@var{n}. Most
15527 entries in the kernpairs section have a negative value for@tie{}@var{n}.
15531 @c =====================================================================
15532 @c =====================================================================
15534 @node Installation, Copying This Manual, File formats, Top
15535 @chapter Installation
15536 @cindex installation
15542 @c =====================================================================
15543 @c =====================================================================
15545 @node Copying This Manual, Request Index, Installation, Top
15546 @appendix Copying This Manual
15549 * GNU Free Documentation License:: License for copying this manual.
15556 @c =====================================================================
15557 @c =====================================================================
15559 @node Request Index, Escape Index, Copying This Manual, Top
15560 @appendix Request Index
15562 Requests appear without the leading control character (normally either
15563 @samp{.} or @samp{'}).
15569 @c =====================================================================
15570 @c =====================================================================
15572 @node Escape Index, Operator Index, Request Index, Top
15573 @appendix Escape Index
15575 Any escape sequence @code{\@var{X}} with @var{X} not in the list below
15576 emits a warning, printing glyph @var{X}.
15582 @c =====================================================================
15583 @c =====================================================================
15585 @node Operator Index, Register Index, Escape Index, Top
15586 @appendix Operator Index
15592 @c =====================================================================
15593 @c =====================================================================
15595 @node Register Index, Macro Index, Operator Index, Top
15596 @appendix Register Index
15598 The macro package or program a specific register belongs to is appended in
15601 A register name@tie{}@code{x} consisting of exactly one character can be
15602 accessed as @samp{\nx}. A register name @code{xx} consisting of exactly
15603 two characters can be accessed as @samp{\n(xx}. Register names @code{xxx}
15604 of any length can be accessed as @samp{\n[xxx]}.
15610 @c =====================================================================
15611 @c =====================================================================
15613 @node Macro Index, String Index, Register Index, Top
15614 @appendix Macro Index
15616 The macro package a specific macro belongs to is appended in brackets.
15617 They appear without the leading control character (normally @samp{.}).
15623 @c =====================================================================
15624 @c =====================================================================
15626 @node String Index, Glyph Name Index, Macro Index, Top
15627 @appendix String Index
15629 The macro package or program a specific string belongs to is appended in
15632 A string name@tie{}@code{x} consisting of exactly one character can be
15633 accessed as @samp{\*x}. A string name @code{xx} consisting of exactly
15634 two characters can be accessed as @samp{\*(xx}. String names @code{xxx}
15635 of any length can be accessed as @samp{\*[xxx]}.
15642 @c =====================================================================
15643 @c =====================================================================
15645 @node Glyph Name Index, Font File Keyword Index, String Index, Top
15646 @appendix Glyph Name Index
15648 A glyph name @code{xx} consisting of exactly two characters can be
15649 accessed as @samp{\(xx}. Glyph names @code{xxx} of any length can be
15650 accessed as @samp{\[xxx]}.
15656 @c =====================================================================
15657 @c =====================================================================
15659 @node Font File Keyword Index, Program and File Index, Glyph Name Index, Top
15660 @appendix Font File Keyword Index
15666 @c =====================================================================
15667 @c =====================================================================
15669 @node Program and File Index, Concept Index, Font File Keyword Index, Top
15670 @appendix Program and File Index
15676 @c =====================================================================
15677 @c =====================================================================
15679 @node Concept Index, , Program and File Index, Top
15680 @appendix Concept Index