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.)
24 This manual documents GNU @code{troff} version 1.19.
26 Copyright @copyright{} 1994-2000, 2001, 2002, 2003, 2004
27 Free Software Foundation, Inc.
30 Permission is granted to copy, distribute and/or modify this document
31 under the terms of the GNU Free Documentation License, Version 1.1 or
32 any later version published by the Free Software Foundation; with no
33 Invariant Sections, with the Front-Cover texts being `A GNU Manual,''
34 and with the Back-Cover Texts as in (a) below. A copy of the
35 license is included in the section entitled `GNU Free Documentation
38 (a) The FSF's Back-Cover Text is: `You have freedom to copy and modify
39 this GNU Manual, like GNU software. Copies published by the Free
40 Software Foundation raise funds for GNU development.''
45 @c We use the following indices:
51 @c kindex: commands in font files
52 @c pindex: programs and files
53 @c tindex: environment variables
58 @c tindex and cindex are merged.
68 @c To avoid uppercasing in @deffn while converting to info, we define
69 @c our special @Var{}.
71 @c Due to a (not officially documented) `feature' in makeinfo 4.0,
72 @c macros are not expanded in @deffn (but the macro definition is
73 @c properly removed), so we have to define @Var{} directly in TeX also.
83 @c To assure correct HTML translation, some ugly hacks are necessary.
84 @c While processing a @def... request, the HTML translator looks at the
85 @c next line to decide whether it should start indentation or not. If
86 @c it is something starting with @def... (e.g. @deffnx), it doesn't.
87 @c So we must assure during macro expansion that a @def... is seen.
89 @c The following macros have to be used:
108 @c The definition block must end with
112 @c The above is valid for texinfo 4.0f and above.
115 @c a dummy macro to assure the `@def...'
121 @c definition of requests
123 @macro Defreq{name, arg}
124 @deffn Request @t{.\name\} \arg\
128 @macro DefreqList{name, arg}
129 @deffn Request @t{.\name\} \arg\
134 @macro DefreqItem{name, arg}
135 @deffnx Request @t{.\name\} \arg\
140 @macro DefreqListEnd{name, arg}
141 @deffnx Request @t{.\name\} \arg\
150 @c definition of escapes
152 @macro Defesc{name, delimI, arg, delimII}
153 @deffn Escape @t{\name\\delimI\}@Var{\arg\}@t{\delimII\}
157 @macro DefescList{name, delimI, arg, delimII}
158 @deffn Escape @t{\name\\delimI\}@Var{\arg\}@t{\delimII\}
163 @macro DefescItem{name, delimI, arg, delimII}
164 @deffnx Escape @t{\name\\delimI\}@Var{\arg\}@t{\delimII\}
169 @macro DefescListEnd{name, delimI, arg, delimII}
170 @deffnx Escape @t{\name\\delimI\}@Var{\arg\}@t{\delimII\}
179 @c definition of registers
182 @deffn Register @t{\\n[\name\]}
186 @macro DefregList{name}
187 @deffn Register @t{\\n[\name\]}
192 @macro DefregItem{name}
193 @deffnx Register @t{\\n[\name\]}
198 @macro DefregListEnd{name}
199 @deffnx Register @t{\\n[\name\]}
208 @c definition of registers specific to macro packages, preprocessors, etc.
210 @macro Defmpreg{name, package}
211 @deffn Register @t{\\n[\name\]}
212 @vindex \name\ @r{[}\package\@r{]}
215 @macro DefmpregList{name, package}
216 @deffn Register @t{\\n[\name\]}
218 @vindex \name\ @r{[}\package\@r{]}
221 @macro DefmpregItem{name, package}
222 @deffnx Register @t{\\n[\name\]}
224 @vindex \name\ @r{[}\package\@r{]}
227 @macro DefmpregListEnd{name, package}
228 @deffnx Register @t{\\n[\name\]}
229 @vindex \name\ @r{[}\package\@r{]}
237 @c definition of macros
239 @macro Defmac{name, arg, package}
240 @defmac @t{.\name\} \arg\
241 @maindex \name\ @r{[}\package\@r{]}
244 @macro DefmacList{name, arg, package}
245 @defmac @t{.\name\} \arg\
247 @maindex \name\ @r{[}\package\@r{]}
250 @macro DefmacItem{name, arg, package}
251 @defmacx @t{.\name\} \arg\
253 @maindex \name\ @r{[}\package\@r{]}
256 @macro DefmacListEnd{name, arg, package}
257 @defmacx @t{.\name\} \arg\
258 @maindex \name\ @r{[}\package\@r{]}
266 @c definition of strings
268 @macro Defstr{name, package}
269 @deffn String @t{\\*[\name\]}
270 @stindex \name\ @r{[}\package\@r{]}
273 @macro DefstrList{name, package}
274 @deffn String @t{\\*[\name\]}
276 @stindex \name\ @r{[}\package\@r{]}
279 @macro DefstrItem{name, package}
280 @deffnx String @t{\\*[\name\]}
282 @stindex \name\ @r{[}\package\@r{]}
285 @macro DefstrListEnd{name, package}
286 @deffnx String @t{\\*[\name\]}
287 @stindex \name\ @r{[}\package\@r{]}
311 \gdef\angles#1{\angleleft{}\r{#1}\angleright{}}
330 @c We need special parentheses and brackets:
332 @c . Real parentheses in @deffn produce an error while compiling with
334 @c . Real brackets use the wrong font in @deffn, overriding @t{}.
336 @c Since macros aren't expanded in @deffn during -E, the following
337 @c definitions are for non-TeX only.
339 @c This is true for texinfo 4.0.
356 \gdef\gobblefirst#1#2{#2}
357 \gdef\putwordAppendix{\gobblefirst}
361 @c Note: We say `Roman numerals' but `roman font'.
364 @dircategory Typesetting
366 * Groff: (groff). The GNU troff document formatting system.
372 @subtitle The GNU implementation of @code{troff}
373 @subtitle Edition 1.19.1
374 @subtitle Spring 2004
375 @author by Trent A.@tie{}Fisher
376 @author and Werner Lemberg (@email{bug-groff@@gnu.org})
379 @vskip 0pt plus 1filll
387 @node Top, Introduction, (dir), (dir)
394 @node Top, Introduction, (dir), (dir)
403 * Tutorial for Macro Users::
410 * Copying This Manual::
418 * Font File Keyword Index::
419 * Program and File Index::
425 @c =====================================================================
426 @c =====================================================================
428 @node Introduction, Invoking groff, Top, Top
429 @chapter Introduction
432 GNU @code{troff} (or @code{groff}) is a system for typesetting
433 documents. @code{troff} is very flexible and has been in existence (and
434 use) for about 3@tie{}decades. It is quite widespread and firmly
435 entrenched in the @acronym{UNIX} community.
440 * groff Capabilities::
441 * Macro Package Intro::
442 * Preprocessor Intro::
443 * Output device intro::
448 @c =====================================================================
450 @node What Is groff?, History, Introduction, Introduction
451 @section What Is @code{groff}?
452 @cindex what is @code{groff}?
453 @cindex @code{groff} -- what is it?
455 @code{groff} belongs to an older generation of document preparation
456 systems, which operate more like compilers than the more recent
457 interactive @acronym{WYSIWYG}@footnote{What You See Is What You Get}
458 systems. @code{groff} and its contemporary counterpart, @TeX{}, both
459 work using a @dfn{batch} paradigm: The input (or @dfn{source}) files are
460 normal text files with embedded formatting commands. These files can
461 then be processed by @code{groff} to produce a typeset document on a
464 Likewise, @code{groff} should not be confused with a @dfn{word
465 processor}, since that term connotes an integrated system that includes
466 an editor and a text formatter. Also, many word processors follow the
467 @acronym{WYSIWYG} paradigm discussed earlier.
469 Although @acronym{WYSIWYG} systems may be easier to use, they have a
470 number of disadvantages compared to @code{troff}:
474 They must be used on a graphics display to work on a document.
477 Most of the @acronym{WYSIWYG} systems are either non-free or are not
481 @code{troff} is firmly entrenched in all @acronym{UNIX} systems.
484 It is difficult to have a wide range of capabilities available within
485 the confines of a GUI/window system.
488 It is more difficult to make global changes to a document.
492 ``GUIs normally make it simple to accomplish simple actions and
493 impossible to accomplish complex actions.'' --Doug Gwyn (22/Jun/91 in
494 @code{comp.unix.wizards})
498 @c =====================================================================
500 @node History, groff Capabilities, What Is groff?, Introduction
504 @cindex @code{runoff}, the program
505 @cindex @code{rf}, the program
506 @code{troff} can trace its origins back to a formatting program called
507 @code{runoff}, written by J.@tie{}E.@tie{}Saltzer, which ran on MIT's CTSS
508 operating system in the mid-sixties. This name came from the common
509 phrase of the time ``I'll run off a document.'' Bob Morris ported it to
510 the 635 architecture and called the program @code{roff} (an abbreviation
511 of @code{runoff}). It was rewritten as @code{rf} for the @w{PDP-7}
512 (before having @acronym{UNIX}), and at the same time (1969), Doug
513 McIllroy rewrote an extended and simplified version of @code{roff} in
514 the @acronym{BCPL} programming language.
516 @cindex @code{roff}, the program
517 The first version of @acronym{UNIX} was developed on a @w{PDP-7} which
518 was sitting around Bell Labs. In 1971 the developers wanted to get a
519 @w{PDP-11} for further work on the operating system. In order to
520 justify the cost for this system, they proposed that they would
521 implement a document formatting system for the @acronym{AT&T} patents
522 division. This first formatting program was a reimplementation of
523 McIllroy's @code{roff}, written by J.@tie{}F.@tie{}Ossanna.
525 @cindex @code{nroff}, the program
526 When they needed a more flexible language, a new version of @code{roff}
527 called @code{nroff} (``Newer @code{roff}'') was written. It had a much
528 more complicated syntax, but provided the basis for all future versions.
529 When they got a Graphic Systems CAT Phototypesetter, Ossanna wrote a
530 version of @code{nroff} that would drive it. It was dubbed
531 @code{troff}, for ``typesetter @code{roff}'', although many people have
532 speculated that it actually means ``Times @code{roff}'' because of the
533 use of the Times font family in @code{troff} by default. As such, the
534 name @code{troff} is pronounced `@w{t-roff}' rather than `trough'.
536 With @code{troff} came @code{nroff} (they were actually the same program
537 except for some @samp{#ifdef}s), which was for producing output for line
538 printers and character terminals. It understood everything @code{troff}
539 did, and ignored the commands which were not applicable (e.g.@: font
542 Since there are several things which cannot be done easily in
543 @code{troff}, work on several preprocessors began. These programs would
544 transform certain parts of a document into @code{troff}, which made a
545 very natural use of pipes in @acronym{UNIX}.
547 The @code{eqn} preprocessor allowed mathematical formul@ae{} to be
548 specified in a much simpler and more intuitive manner. @code{tbl} is a
549 preprocessor for formatting tables. The @code{refer} preprocessor (and
550 the similar program, @code{bib}) processes citations in a document
551 according to a bibliographic database.
553 Unfortunately, Ossanna's @code{troff} was written in @w{PDP-11} assembly
554 language and produced output specifically for the CAT phototypesetter.
555 He rewrote it in C, although it was now 7000@tie{}lines of uncommented
556 code and still dependent on the CAT. As the CAT became less common, and
557 was no longer supported by the manufacturer, the need to make it support
558 other devices became a priority. However, before this could be done,
559 Ossanna was killed in a car accident.
562 @cindex @code{ditroff}, the program
563 So, Brian Kernighan took on the task of rewriting @code{troff}. The
564 newly rewritten version produced device independent code which was
565 very easy for postprocessors to read and translate to the appropriate
566 printer codes. Also, this new version of @code{troff} (called
567 @code{ditroff} for ``device independent @code{troff}'') had several
568 extensions, which included drawing functions.
570 Due to the additional abilities of the new version of @code{troff},
571 several new preprocessors appeared. The @code{pic} preprocessor
572 provides a wide range of drawing functions. Likewise the @code{ideal}
573 preprocessor did the same, although via a much different paradigm. The
574 @code{grap} preprocessor took specifications for graphs, but, unlike
575 other preprocessors, produced @code{pic} code.
577 James Clark began work on a GNU implementation of @code{ditroff} in
578 early@tie{}1989. The first version, @code{groff}@tie{}0.3.1, was released
579 June@tie{}1990. @code{groff} included:
583 A replacement for @code{ditroff} with many extensions.
586 The @code{soelim}, @code{pic}, @code{tbl}, and @code{eqn} preprocessors.
589 Postprocessors for character devices, @sc{PostScript}, @TeX{} DVI, and
590 X@tie{}Windows. GNU @code{troff} also eliminated the need for a
591 separate @code{nroff} program with a postprocessor which would produce
592 @acronym{ASCII} output.
595 A version of the @file{me} macros and an implementation of the
599 Also, a front-end was included which could construct the, sometimes
600 painfully long, pipelines required for all the post- and preprocessors.
602 Development of GNU @code{troff} progressed rapidly, and saw the
603 additions of a replacement for @code{refer}, an implementation of the
604 @file{ms} and @file{mm} macros, and a program to deduce how to format a
605 document (@code{grog}).
607 It was declared a stable (i.e.@: non-beta) package with the release of
608 version@tie{}1.04 around November@tie{}1991.
610 Beginning in@tie{}1999, @code{groff} has new maintainers (the package was
611 an orphan for a few years). As a result, new features and programs like
612 @code{grn}, a preprocessor for gremlin images, and an output device to
613 produce @acronym{HTML} output have been added.
616 @c =====================================================================
618 @node groff Capabilities, Macro Package Intro, History, Introduction
619 @section @code{groff} Capabilities
620 @cindex @code{groff} capabilities
621 @cindex capabilities of @code{groff}
623 So what exactly is @code{groff} capable of doing? @code{groff} provides
624 a wide range of low-level text formatting operations. Using these, it
625 is possible to perform a wide range of formatting tasks, such as
626 footnotes, table of contents, multiple columns, etc. Here's a list of
627 the most important operations supported by @code{groff}:
631 text filling, adjusting, and centering
640 font and glyph size control
643 vertical spacing (e.g.@: double-spacing)
646 line length and indenting
649 macros, strings, diversions, and traps
655 tabs, leaders, and fields
658 input and output conventions and character translation
661 overstrike, bracket, line drawing, and zero-width functions
664 local horizontal and vertical motions and the width function
670 output line numbering
673 conditional acceptance of input
676 environment switching
679 insertions from the standard input
682 input/output file switching
685 output and error messages
689 @c =====================================================================
691 @node Macro Package Intro, Preprocessor Intro, groff Capabilities, Introduction
692 @section Macro Packages
693 @cindex macro packages
695 Since @code{groff} provides such low-level facilities, it can be quite
696 difficult to use by itself. However, @code{groff} provides a
697 @dfn{macro} facility to specify how certain routine operations
698 (e.g.@tie{}starting paragraphs, printing headers and footers, etc.)@:
699 should be done. These macros can be collected together into a @dfn{macro
700 package}. There are a number of macro packages available; the most
701 common (and the ones described in this manual) are @file{man},
702 @file{mdoc}, @file{me}, @file{ms}, and @file{mm}.
705 @c =====================================================================
707 @node Preprocessor Intro, Output device intro, Macro Package Intro, Introduction
708 @section Preprocessors
709 @cindex preprocessors
711 Although @code{groff} provides most functions needed to format a
712 document, some operations would be unwieldy (e.g.@: to draw pictures).
713 Therefore, programs called @dfn{preprocessors} were written which
714 understand their own language and produce the necessary @code{groff}
715 operations. These preprocessors are able to differentiate their own
716 input from the rest of the document via markers.
718 To use a preprocessor, @acronym{UNIX} pipes are used to feed the output
719 from the preprocessor into @code{groff}. Any number of preprocessors
720 may be used on a given document; in this case, the preprocessors are
721 linked together into one pipeline. However, with @code{groff}, the user
722 does not need to construct the pipe, but only tell @code{groff} what
723 preprocessors to use.
725 @code{groff} currently has preprocessors for producing tables
726 (@code{tbl}), typesetting equations (@code{eqn}), drawing pictures
727 (@code{pic} and @code{grn}), and for processing bibliographies
728 (@code{refer}). An associated program which is useful when dealing with
729 preprocessors is @code{soelim}.
731 A free implementation of @code{grap}, a preprocessor for drawing graphs,
732 can be obtained as an extra package; @code{groff} can use @code{grap}
735 There are other preprocessors in existence, but, unfortunately, no free
736 implementations are available. Among them are preprocessors for drawing
737 mathematical pictures (@code{ideal}) and chemical structures
741 @c =====================================================================
743 @node Output device intro, Credits, Preprocessor Intro, Introduction
744 @section Output Devices
745 @cindex postprocessors
746 @cindex output devices
747 @cindex devices for output
749 @code{groff} actually produces device independent code which may be
750 fed into a postprocessor to produce output for a particular device.
751 Currently, @code{groff} has postprocessors for @sc{PostScript}
752 devices, character terminals, X@tie{}Windows (for previewing), @TeX{}
753 DVI format, HP LaserJet@tie{}4 and Canon LBP printers (which use
754 @acronym{CAPSL}), and @acronym{HTML}.
757 @c =====================================================================
759 @node Credits, , Output device intro, Introduction
763 Large portions of this manual were taken from existing documents, most
764 notably, the manual pages for the @code{groff} package by James Clark,
765 and Eric Allman's papers on the @file{me} macro package.
767 The section on the @file{man} macro package is partly based on
768 Susan@tie{}G.@: Kleinmann's @file{groff_man} manual page written for the
769 Debian GNU/Linux system.
771 Larry Kollar contributed the section in the @file{ms} macro package.
775 @c =====================================================================
776 @c =====================================================================
778 @node Invoking groff, Tutorial for Macro Users, Introduction, Top
779 @chapter Invoking @code{groff}
780 @cindex invoking @code{groff}
781 @cindex @code{groff} invocation
783 This section focuses on how to invoke the @code{groff} front end. This
784 front end takes care of the details of constructing the pipeline among
785 the preprocessors, @code{gtroff} and the postprocessor.
787 It has become a tradition that GNU programs get the prefix @samp{g} to
788 distinguish it from its original counterparts provided by the host (see
789 @ref{Environment}, for more details). Thus, for example, @code{geqn} is
790 GNU @code{eqn}. On operating systems like GNU/Linux or the Hurd, which
791 don't contain proprietary versions of @code{troff}, and on
792 MS-DOS/MS-Windows, where @code{troff} and associated programs are not
793 available at all, this prefix is omitted since GNU @code{troff} is the
794 only used incarnation of @code{troff}. Exception: @samp{groff} is never
795 replaced by @samp{roff}.
797 In this document, we consequently say @samp{gtroff} when talking about
798 the GNU @code{troff} program. All other implementations of @code{troff}
799 are called @acronym{AT&T} @code{troff} which is the common origin of
800 all @code{troff} derivates (with more or less compatible changes).
801 Similarly, we say @samp{gpic}, @samp{geqn}, etc.
806 * Macro Directories::
809 * Invocation Examples::
813 @c =====================================================================
815 @node Groff Options, Environment, Invoking groff, Invoking groff
828 @code{groff} normally runs the @code{gtroff} program and a postprocessor
829 appropriate for the selected device. The default device is @samp{ps}
830 (but it can be changed when @code{groff} is configured and built). It
831 can optionally preprocess with any of @code{gpic}, @code{geqn},
832 @code{gtbl}, @code{ggrn}, @code{grap}, @code{grefer}, or @code{gsoelim}.
834 This section only documents options to the @code{groff} front end. Many
835 of the arguments to @code{groff} are passed on to @code{gtroff},
836 therefore those are also included. Arguments to pre- or postprocessors
837 can be found in @ref{Invoking gpic}, @ref{Invoking geqn}, @ref{Invoking
838 gtbl}, @ref{Invoking ggrn}, @ref{Invoking grefer}, @ref{Invoking
839 gsoelim}, @ref{Invoking grotty}, @ref{Invoking grops}, @ref{Invoking
840 grohtml}, @ref{Invoking grodvi}, @ref{Invoking grolj4}, @ref{Invoking
841 grolbp}, and @ref{Invoking gxditview}.
843 The command line format for @code{groff} is:
846 groff [ -abceghilpstvzCEGNRSUVXZ ] [ -F@var{dir} ] [ -m@var{name} ]
847 [ -T@var{def} ] [ -f@var{fam} ] [ -w@var{name} ] [ -W@var{name} ]
848 [ -M@var{dir} ] [ -d@var{cs} ] [ -r@var{cn} ] [ -n@var{num} ]
849 [ -o@var{list} ] [ -P@var{arg} ] [ -L@var{arg} ] [ -I@var{dir} ]
850 [ @var{files}@dots{} ]
853 The command line format for @code{gtroff} is as follows.
856 gtroff [ -abcivzCERU ] [ -w@var{name} ] [ -W@var{name} ] [ -d@var{cs} ]
857 [ -f@var{fam} ] [ -m@var{name} ] [ -n@var{num} ]
858 [ -o@var{list} ] [ -r@var{cn} ] [ -T@var{name} ]
859 [ -F@var{dir} ] [ -M@var{dir} ] [ @var{files}@dots{} ]
863 Obviously, many of the options to @code{groff} are actually passed on to
866 Options without an argument can be grouped behind a single@tie{}@option{-}.
867 A filename of@tie{}@file{-} denotes the standard input. It is possible to
868 have whitespace between an option and its parameter.
870 The @code{grog} command can be used to guess the correct @code{groff}
871 command to format a file.
873 Here's the description of the command-line options:
875 @cindex command-line options
878 Print a help message.
881 Preprocess with @code{geqn}.
884 Preprocess with @code{gtbl}.
887 Preprocess with @code{ggrn}.
890 Preprocess with @code{grap}.
893 Preprocess with @code{gpic}.
896 Preprocess with @code{gsoelim}.
899 Suppress color output.
902 Preprocess with @code{grefer}. No mechanism is provided for passing
903 arguments to @code{grefer} because most @code{grefer} options have
904 equivalent commands which can be included in the file. @xref{grefer},
909 Note that @code{gtroff} also accepts a @option{-R} option, which is not
910 accessible via @code{groff}. This option prevents the loading of the
911 @file{troffrc} and @file{troffrc-end} files.
914 Make programs run by @code{groff} print out their version number.
917 Print the pipeline on @code{stdout} instead of executing it. If specified
918 more than once, print the pipeline on @code{stderr} and execute it.
921 Suppress output from @code{gtroff}. Only error messages are printed.
924 Do not postprocess the output of @code{gtroff}. Normally @code{groff}
925 automatically runs the appropriate postprocessor.
928 Pass @var{arg} to the postprocessor. Each argument should be passed
929 with a separate @option{-P} option. Note that @code{groff} does not
930 prepend @samp{-} to @var{arg} before passing it to the postprocessor.
933 Send the output to a spooler for printing. The command used for this is
934 specified by the @code{print} command in the device description file
935 (see @ref{Font Files}, for more info). If not present, @option{-l} is
939 Pass @var{arg} to the spooler. Each argument should be passed with a
940 separate @option{-L} option. Note that @code{groff} does not prepend
941 a @samp{-} to @var{arg} before passing it to the postprocessor.
942 If the @code{print} keyword in the device description file is missing,
943 @option{-L} is ignored.
946 Prepare output for device @var{dev}. The default device is @samp{ps},
947 unless changed when @code{groff} was configured and built. The
948 following are the output devices currently available:
952 For @sc{PostScript} printers and previewers.
955 For @TeX{} DVI format.
958 For a 75@dmn{dpi} X11 previewer.
961 For a 75@dmn{dpi} X11 previewer with a 12@dmn{pt} base font in the
965 For a 100@dmn{dpi} X11 previewer.
968 For a 100@dmn{dpi} X11 previewer with a 12@dmn{pt} base font in the
972 @cindex encoding, output, @acronym{ASCII}
973 @cindex @acronym{ASCII}, output encoding
974 @cindex output encoding, @acronym{ASCII}
975 For typewriter-like devices using the (7-bit) @acronym{ASCII}
979 @cindex encoding, output, @w{latin-1} (ISO @w{8859-1})
980 @cindex @w{latin-1} (ISO @w{8859-1}), output encoding
981 @cindex ISO @w{8859-1} (@w{latin-1}), output encoding
982 @cindex output encoding, @w{latin-1} (ISO @w{8859-1})
983 For typewriter-like devices that support the @w{Latin-1}
984 (ISO@tie{}@w{8859-1}) character set.
987 @cindex encoding, output, @w{utf-8}
988 @cindex @w{utf-8}, output encoding
989 @cindex output encoding, @w{utf-8}
990 For typewriter-like devices which use the Unicode (ISO@tie{}10646)
991 character set with @w{UTF-8} encoding.
994 @cindex encoding, output, @acronym{EBCDIC}
995 @cindex @acronym{EBCDIC}, output encoding
996 @cindex output encoding, @acronym{EBCDIC}
997 @cindex encoding, output, cp1047
998 @cindex cp1047, output encoding
999 @cindex output encoding, cp1047
1000 @cindex IBM cp1047 output encoding
1001 For typewriter-like devices which use the @acronym{EBCDIC} encoding IBM
1005 For HP LaserJet4-compatible (or other PCL5-compatible) printers.
1008 For Canon @acronym{CAPSL} printers (@w{LBP-4} and @w{LBP-8} series laser
1012 @pindex post-grohtml
1013 @cindex @code{grohtml}, the program
1015 To produce @acronym{HTML} output. Note that the @acronym{HTML} driver
1016 consists of two parts, a preprocessor (@code{pre-grohtml}) and a
1017 postprocessor (@code{post-grohtml}).
1020 @cindex output device name string register (@code{.T})
1021 @cindex output device usage number register (@code{.T})
1022 The predefined @code{gtroff} string register @code{.T} contains the
1023 current output device; the read-only number register @code{.T} is set
1024 to@tie{}1 if this option is used (which is always true if @code{groff} is
1025 used to call @code{gtroff}). @xref{Built-in Registers}.
1027 The postprocessor to be used for a device is specified by the
1028 @code{postpro} command in the device description file. (@xref{Font
1029 Files}, for more info.) This can be overridden with the @option{-X}
1033 Preview with @code{gxditview} instead of using the usual postprocessor.
1034 This is unlikely to produce good results except with @option{-Tps}.
1036 Note that this is not the same as using @option{-TX75} or
1037 @option{-TX100} to view a document with @code{gxditview}: The former
1038 uses the metrics of the specified device, whereas the latter uses
1039 X-specific fonts and metrics.
1042 Don't allow newlines with @code{eqn} delimiters. This is the same as
1043 the @option{-N} option in @code{geqn}.
1046 @cindex @code{open} request, and safer mode
1047 @cindex @code{opena} request, and safer mode
1048 @cindex @code{pso} request, and safer mode
1049 @cindex @code{sy} request, and safer mode
1050 @cindex @code{pi} request, and safer mode
1053 Safer mode. Pass the @option{-S} option to @code{gpic} and disable the
1054 @code{open}, @code{opena}, @code{pso}, @code{sy}, and @code{pi}
1055 requests. For security reasons, this is enabled by default.
1058 @cindex mode, unsafe
1060 Unsafe mode. This enables the @code{open}, @code{opena}, @code{pso},
1061 @code{sy}, and @code{pi} requests.
1064 @cindex @acronym{ASCII} approximation output register (@code{.A})
1065 Generate an @acronym{ASCII} approximation of the typeset output. The
1066 read-only register @code{.A} is then set to@tie{}1. @xref{Built-in
1067 Registers}. A typical example is
1070 groff -a -man -Tdvi troff.man | less
1074 which shows how lines are broken for the DVI device. Note that this
1075 option is rather useless today since graphic output devices are
1076 available virtually everywhere.
1079 Print a backtrace with each warning or error message. This backtrace
1080 should help track down the cause of the error. The line numbers given
1081 in the backtrace may not always be correct: @code{gtroff} can get
1082 confused by @code{as} or @code{am} requests while counting line numbers.
1085 Read the standard input after all the named input files have been
1089 Enable warning @var{name}. Available warnings are described in
1090 @ref{Debugging}. Multiple @option{-w} options are allowed.
1093 Inhibit warning @var{name}. Multiple @option{-W} options are allowed.
1096 Inhibit all error messages.
1099 Enable compatibility mode. @xref{Implementation Differences}, for the
1100 list of incompatibilities between @code{groff} and @acronym{AT&T}
1103 @item -d@var{c}@var{s}
1104 @itemx -d@var{name}=@var{s}
1105 Define @var{c} or @var{name} to be a string@tie{}@var{s}. @var{c}@tie{}must
1106 be a one-letter name; @var{name} can be of arbitrary length. All string
1107 assignments happen before loading any macro file (including the start-up
1111 Use @var{fam} as the default font family. @xref{Font Families}.
1114 Read in the file @file{@var{name}.tmac}. Normally @code{groff} searches
1115 for this in its macro directories. If it isn't found, it tries
1116 @file{tmac.@var{name}} (searching in the same directories).
1119 Number the first page @var{num}.
1122 @cindex print current page register (@code{.P})
1123 Output only pages in @var{list}, which is a comma-separated list of page
1124 ranges; @samp{@var{n}} means print page@tie{}@var{n}, @samp{@var{m}-@var{n}}
1125 means print every page between @var{m} and@tie{}@var{n}, @samp{-@var{n}}
1126 means print every page up to@tie{}@var{n}, @samp{@var{n}-} means print every
1127 page beginning with@tie{}@var{n}. @code{gtroff} exits after printing the
1128 last page in the list. All the ranges are inclusive on both ends.
1130 Within @code{gtroff}, this information can be extracted with the
1131 @samp{.P} register. @xref{Built-in Registers}.
1133 If your document restarts page numbering at the beginning of each
1134 chapter, then @code{gtroff} prints the specified page range for each
1137 @item -r@var{c}@var{n}
1138 @itemx -r@var{name}=@var{n}
1139 Set number register@tie{}@var{c} or @var{name} to the value@tie{}@var{n}.
1140 @var{c}@tie{}must be a one-letter name; @var{name} can be of arbitrary
1141 length. @var{n}@tie{}can be any @code{gtroff} numeric expression. All
1142 register assignments happen before loading any macro file (including
1146 Search @file{@var{dir}} for subdirectories @file{dev@var{name}}
1147 (@var{name} is the name of the device), for the @file{DESC} file, and
1148 for font files before looking in the standard directories (@pxref{Font
1149 Directories}). This option is passed to all pre- and postprocessors
1150 using the @env{GROFF_FONT_PATH} environment variable.
1153 Search directory @file{@var{dir}} for macro files before the standard
1154 directories (@pxref{Macro Directories}).
1157 This option may be used to specify a directory to search for files.
1158 It is passed to the following programs:
1162 @code{gsoelim} (see @ref{gsoelim} for more details);
1163 it also implies @code{groff}'s @option{-s} option.
1166 @code{gtroff}; it is used to search files named in the @code{psbb} and
1170 @code{grops}; it is used to search files named in the
1171 @w{@code{\X'ps: import}} and @w{@code{\X'ps: file}} escapes.
1174 The current directory is always searched first. This option may be specified
1175 more than once; the directories will be searched in the order specified. No
1176 directory search is performed for files specified using an absolute path.
1180 @c =====================================================================
1182 @node Environment, Macro Directories, Groff Options, Invoking groff
1183 @section Environment
1184 @cindex environment variables
1185 @cindex variables in environment
1187 There are also several environment variables (of the operating system,
1188 not within @code{gtroff}) which can modify the behavior of @code{groff}.
1191 @item GROFF_COMMAND_PREFIX
1192 @tindex GROFF_COMMAND_PREFIX@r{, environment variable}
1193 @cindex command prefix
1194 @cindex prefix, for commands
1195 If this is set to@tie{}@var{X}, then @code{groff} runs @code{@var{X}troff}
1196 instead of @code{gtroff}. This also applies to @code{tbl}, @code{pic},
1197 @code{eqn}, @code{grn}, @code{refer}, and @code{soelim}. It does not
1198 apply to @code{grops}, @code{grodvi}, @code{grotty}, @code{pre-grohtml},
1199 @code{post-grohtml}, @code{grolj4}, and @code{gxditview}.
1201 The default command prefix is determined during the installation process.
1202 If a non-GNU troff system is found, prefix @samp{g} is used, none
1205 @item GROFF_TMAC_PATH
1206 @tindex GROFF_TMAC_PATH@r{, environment variable}
1207 A colon-separated list of directories in which to search for macro files
1208 (before the default directories are tried). @xref{Macro Directories}.
1210 @item GROFF_TYPESETTER
1211 @tindex GROFF_TYPESETTER@r{, environment variable}
1212 The default output device.
1214 @item GROFF_FONT_PATH
1215 @tindex GROFF_FONT_PATH@r{, environment variable}
1216 A colon-separated list of directories in which to search for the
1217 @code{dev}@var{name} directory (before the default directories are
1218 tried). @xref{Font Directories}.
1220 @item GROFF_BIN_PATH
1221 @tindex GROFF_BIN_PATH@r{, environment variable}
1222 This search path, followed by @code{PATH}, is used for commands executed
1226 @tindex GROFF_TMPDIR@r{, environment variable}
1227 @tindex TMPDIR@r{, environment variable}
1228 The directory in which @code{groff} creates temporary files. If this is
1229 not set and @env{TMPDIR} is set, temporary files are created in that
1230 directory. Otherwise temporary files are created in a system-dependent
1231 default directory (on Unix and GNU/Linux systems, this is usually
1232 @file{/tmp}). @code{grops}, @code{grefer}, @code{pre-grohtml}, and
1233 @code{post-grohtml} can create temporary files in this directory.
1236 Note that MS-DOS and MS-Windows ports of @code{groff} use semi-colons,
1237 rather than colons, to separate the directories in the lists described
1241 @c =====================================================================
1243 @node Macro Directories, Font Directories, Environment, Invoking groff
1244 @section Macro Directories
1245 @cindex macro directories
1246 @cindex directories for macros
1247 @cindex searching macros
1248 @cindex macros, searching
1250 All macro file names must be named @code{@var{name}.tmac} or
1251 @code{tmac.@var{name}} to make the @option{-m@var{name}} command line
1252 option work. The @code{mso} request doesn't have this restriction; any
1253 file name can be used, and @code{gtroff} won't try to append or prepend
1254 the @samp{tmac} string.
1256 @cindex tmac, directory
1257 @cindex directory, for tmac files
1259 @cindex path, for tmac files
1260 @cindex searching macro files
1261 @cindex macro files, searching
1262 @cindex files, macro, searching
1263 Macro files are kept in the @dfn{tmac directories}, all of which
1264 constitute the @dfn{tmac path}. The elements of the search path for
1265 macro files are (in that order):
1269 The directories specified with @code{gtroff}'s or @code{groff}'s
1270 @option{-M} command line option.
1273 @tindex GROFF_TMAC_PATH@r{, environment variable}
1274 The directories given in the @env{GROFF_TMAC_PATH} environment
1281 @cindex mode, unsafe
1282 @cindex current directory
1283 @cindex directory, current
1284 The current directory (only if in unsafe mode using the @option{-U}
1285 command line switch).
1288 @cindex home directory
1289 @cindex directory, home
1293 @cindex site-specific directory
1294 @cindex directory, site-specific
1295 @cindex platform-specific directory
1296 @cindex directory, platform-specific
1297 A platform-dependent directory, a site-specific (platform-independent)
1298 directory, and the main tmac directory; the default locations are
1301 /usr/local/lib/groff/site-tmac
1302 /usr/local/share/groff/site-tmac
1303 /usr/local/share/groff/1.18.2/tmac
1307 assuming that the version of @code{groff} is 1.18.2, and the installation
1308 prefix was @file{/usr/local}. It is possible to fine-tune those
1309 directories during the installation process.
1313 @c =====================================================================
1315 @node Font Directories, Paper Size, Macro Directories, Invoking groff
1316 @section Font Directories
1317 @cindex font directories
1318 @cindex directories for fonts
1319 @cindex searching fonts
1320 @cindex fonts, searching
1322 Basically, there is no restriction how font files for @code{groff} are
1323 named and how long font names are; however, to make the font family
1324 mechanism work (@pxref{Font Families}), fonts within a family should
1325 start with the family name, followed by the shape. For example, the
1326 Times family uses @samp{T} for the family name and @samp{R}, @samp{B},
1327 @samp{I}, and @samp{BI} to indicate the shapes `roman', `bold',
1328 `italic', and `bold italic', respectively. Thus the final font names
1329 are @samp{TR}, @samp{TB}, @samp{TI}, and @samp{TBI}.
1332 @cindex path, for font files
1333 All font files are kept in the @dfn{font directories} which constitute
1334 the @dfn{font path}. The file search functions will always append the
1335 directory @code{dev}@var{name}, where @var{name} is the name of the
1336 output device. Assuming, say, DVI output, and @file{/foo/bar} as a
1337 font directory, the font files for @code{grodvi} must be in
1338 @file{/foo/bar/devdvi}.
1340 The elements of the search path for font files are (in that order):
1344 The directories specified with @code{gtroff}'s or @code{groff}'s
1345 @option{-F} command line option. All device drivers and some
1346 preprocessors also have this option.
1349 @tindex GROFF_FONT_PATH@r{, environment variable}
1350 The directories given in the @env{GROFF_FONT_PATH} environment
1354 @cindex site-specific directory
1355 @cindex directory, site-specific
1356 A site-specific directory and the main font directory; the default
1360 /usr/local/share/groff/site-font
1361 /usr/local/share/groff/1.18.2/font
1365 assuming that the version of @code{groff} is 1.18.2, and the installation
1366 prefix was @file{/usr/local}. It is possible to fine-tune those
1367 directories during the installation process.
1371 @c =====================================================================
1373 @node Paper Size, Invocation Examples, Font Directories, Invoking groff
1377 @cindex landscape page orientation
1378 @cindex orientation, landscape
1379 @cindex page orientation, landscape
1381 In groff, the page size for @code{gtroff} and for output devices are
1382 handled separately. @xref{Page Layout}, for vertical manipulation of
1383 the page size. @xref{Line Layout}, for horizontal changes.
1385 A default paper size can be set in the device's @file{DESC} file. Most
1386 output devices also have a command line option @option{-p} to override
1387 the default paper size and option @option{-l} to use landscape
1388 orientation. @xref{DESC File Format}, for a description of the
1389 @code{papersize} keyword which takes the same argument as @option{-p}.
1391 @pindex papersize.tmac
1393 A convenient shorthand to set a particular paper size for @code{gtroff}
1394 is command line option @option{-dpaper=@var{size}}. This defines string
1395 @code{paper} which is processed in file @file{papersize.tmac} (loaded in
1396 the start-up file @file{troffrc} by default). Possible values for
1397 @var{size} are the same as the predefined values for the
1398 @code{papersize} keyword (but only in lowercase) except
1399 @code{a7}-@code{d7}. An appended @samp{l} (ell) character denotes
1400 landscape orientation.
1402 For example, use the following for PS output on A4 paper in landscape
1406 groff -Tps -dpaper=a4l -P-pa4 -P-l -ms foo.ms > foo.ps
1409 Note that it is up to the particular macro package to respect default
1410 page dimensions set in this way (most do).
1413 @c =====================================================================
1415 @node Invocation Examples, , Paper Size, Invoking groff
1416 @section Invocation Examples
1417 @cindex invocation examples
1418 @cindex examples of invocation
1420 This section lists several common uses of @code{groff} and the
1421 corresponding command lines.
1428 This command processes @file{file} without a macro package or a
1429 preprocessor. The output device is the default, @samp{ps}, and the
1430 output is sent to @code{stdout}.
1433 groff -t -mandoc -Tascii file | less
1437 This is basically what a call to the @code{man} program does.
1438 @code{gtroff} processes the manual page @file{file} with the
1439 @file{mandoc} macro file (which in turn either calls the @file{man} or
1440 the @file{mdoc} macro package), using the @code{tbl} preprocessor and
1441 the @acronym{ASCII} output device. Finally, the @code{less} pager
1442 displays the result.
1449 Preview @file{file} with @code{gxditview}, using the @file{me} macro
1450 package. Since no @option{-T} option is specified, use the default
1451 device (@samp{ps}). Note that you can either say @w{@samp{-m me}} or
1452 @w{@samp{-me}}; the latter is an anachronism from the early days of
1453 @acronym{UNIX}.@footnote{The same is true for the other main macro
1454 packages that come with @code{groff}: @file{man}, @file{mdoc},
1455 @file{ms}, @file{mm}, and @file{mandoc}. This won't work in general;
1456 for example, to load @file{trace.tmac}, either @samp{-mtrace} or
1457 @w{@samp{-m trace}} must be used.}
1460 groff -man -rD1 -z file
1464 Check @file{file} with the @file{man} macro package, forcing
1465 double-sided printing -- don't produce any output.
1471 @c ---------------------------------------------------------------------
1473 @node grog, , Invocation Examples, Invocation Examples
1474 @subsection @code{grog}
1477 @code{grog} reads files, guesses which of the @code{groff} preprocessors
1478 and/or macro packages are required for formatting them, and prints the
1479 @code{groff} command including those options on the standard output. It
1480 generates one or more of the options @option{-e}, @option{-man},
1481 @option{-me}, @option{-mm}, @option{-mom}, @option{-ms}, @option{-mdoc},
1482 @option{-mdoc-old}, @option{-p}, @option{-R}, @option{-g}, @option{-G},
1483 @option{-s}, and @option{-t}.
1485 A special file name@tie{}@file{-} refers to the standard input. Specifying
1486 no files also means to read the standard input. Any specified options
1487 are included in the printed command. No space is allowed between
1488 options and their arguments. The only options recognized are
1489 @option{-C} (which is also passed on) to enable compatibility mode, and
1490 @option{-v} to print the version number and exit.
1499 guesses the appropriate command to print @file{paper.ms} and then prints
1500 it to the command line after adding the @option{-Tdvi} option. For
1501 direct execution, enclose the call to @code{grog} in backquotes at the
1502 @acronym{UNIX} shell prompt:
1505 `grog -Tdvi paper.ms` > paper.dvi
1509 As seen in the example, it is still necessary to redirect the output to
1510 something meaningful (i.e.@: either a file or a pager program like
1515 @c =====================================================================
1516 @c =====================================================================
1518 @node Tutorial for Macro Users, Macro Packages, Invoking groff, Top
1519 @chapter Tutorial for Macro Users
1520 @cindex tutorial for macro users
1521 @cindex macros, tutorial for users
1522 @cindex user's tutorial for macros
1523 @cindex user's macro tutorial
1525 Most users tend to use a macro package to format their papers. This
1526 means that the whole breadth of @code{groff} is not necessary for most
1527 people. This chapter covers the material needed to efficiently use a
1536 @c =====================================================================
1538 @node Basics, Common Features, Tutorial for Macro Users, Tutorial for Macro Users
1540 @cindex basics of macros
1541 @cindex macro basics
1543 This section covers some of the basic concepts necessary to understand
1544 how to use a macro package.@footnote{This section is derived from
1545 @cite{Writing Papers with nroff using -me} by Eric P.@tie{}Allman.}
1546 References are made throughout to more detailed information, if desired.
1548 @code{gtroff} reads an input file prepared by the user and outputs a
1549 formatted document suitable for publication or framing. The input
1550 consists of text, or words to be printed, and embedded commands
1551 (@dfn{requests} and @dfn{escapes}), which tell @code{gtroff} how to
1552 format the output. For more detail on this, see @ref{Embedded
1555 The word @dfn{argument} is used in this chapter to mean a word or number
1556 which appears on the same line as a request, and which modifies the
1557 meaning of that request. For example, the request
1564 spaces one line, but
1571 spaces four lines. The number@tie{}4 is an argument to the @code{sp}
1572 request which says to space four lines instead of one. Arguments are
1573 separated from the request and from each other by spaces (@emph{no}
1574 tabs). More details on this can be found in @ref{Request and Macro
1577 The primary function of @code{gtroff} is to collect words from input
1578 lines, fill output lines with those words, justify the right-hand margin
1579 by inserting extra spaces in the line, and output the result. For
1587 Four score and seven
1592 is read, packed onto output lines, and justified to produce:
1595 Now is the time for all good men to come to the aid of their party.
1596 Four score and seven years ago, etc.
1601 Sometimes a new output line should be started even though the current
1602 line is not yet full; for example, at the end of a paragraph. To do
1603 this it is possible to cause a @dfn{break}, which starts a new output
1604 line. Some requests cause a break automatically, as normally do blank
1605 input lines and input lines beginning with a space.
1607 Not all input lines are text to be formatted. Some input lines are
1608 requests which describe how to format the text. Requests always have a
1609 period (@samp{.}) or an apostrophe (@samp{'}) as the first character of
1612 The text formatter also does more complex things, such as automatically
1613 numbering pages, skipping over page boundaries, putting footnotes in the
1614 correct place, and so forth.
1616 Here are a few hints for preparing text for input to @code{gtroff}.
1620 First, keep the input lines short. Short input lines are easier to
1621 edit, and @code{gtroff} packs words onto longer lines anyhow.
1624 In keeping with this, it is helpful to begin a new line after every
1625 comma or phrase, since common corrections are to add or delete sentences
1629 End each sentence with two spaces -- or better, start each sentence on a
1630 new line. @code{gtroff} recognizes characters that usually end a
1631 sentence, and inserts sentence space accordingly.
1634 Do not hyphenate words at the end of lines -- @code{gtroff} is smart
1635 enough to hyphenate words as needed, but is not smart enough to take
1636 hyphens out and join a word back together. Also, words such as
1637 ``mother-in-law'' should not be broken over a line, since then a space
1638 can occur where not wanted, such as ``@w{mother- in}-law''.
1641 @cindex double-spacing (@code{ls})
1643 @code{gtroff} double-spaces output text automatically if you use the
1644 request @w{@samp{.ls 2}}. Reactivate single-spaced mode by typing
1645 @w{@samp{.ls 1}}.@footnote{If you need finer granularity of the
1646 vertical space, use the @code{pvs} request (@pxref{Changing Type
1649 A number of requests allow to change the way the output looks,
1650 sometimes called the @dfn{layout} of the output page. Most of these
1651 requests adjust the placing of @dfn{whitespace} (blank lines or
1654 @cindex new page (@code{bp})
1655 The @code{bp} request starts a new page, causing a line break.
1657 @cindex blank line (@code{sp})
1658 @cindex empty line (@code{sp})
1659 @cindex line, empty (@code{sp})
1660 The request @w{@samp{.sp @var{N}}} leaves @var{N}@tie{}lines of blank
1661 space. @var{N}@tie{}can be omitted (meaning skip a single line) or can
1662 be of the form @var{N}i (for @var{N}@tie{}inches) or @var{N}c (for
1663 @var{N}@tie{}centimeters). For example, the input:
1667 My thoughts on the subject
1672 leaves one and a half inches of space, followed by the line ``My
1673 thoughts on the subject'', followed by a single blank line (more
1674 measurement units are available, see @ref{Measurements}).
1676 @cindex centering lines (@code{ce})
1677 @cindex lines, centering (@code{ce})
1678 Text lines can be centered by using the @code{ce} request. The line
1679 after @code{ce} is centered (horizontally) on the page. To center more
1680 than one line, use @w{@samp{.ce @var{N}}} (where @var{N} is the number
1681 of lines to center), followed by the @var{N}@tie{}lines. To center many
1682 lines without counting them, type:
1691 The @w{@samp{.ce 0}} request tells @code{groff} to center zero more
1692 lines, in other words, stop centering.
1694 @cindex line break (@code{br})
1695 @cindex break (@code{br})
1696 All of these requests cause a break; that is, they always start a new
1697 line. To start a new line without performing any other action, use
1701 @c =====================================================================
1703 @node Common Features, , Basics, Tutorial for Macro Users
1704 @section Common Features
1705 @cindex common features
1706 @cindex features, common
1708 @code{gtroff} provides very low-level operations for formatting a
1709 document. There are many common routine operations which are done in
1710 all documents. These common operations are written into @dfn{macros}
1711 and collected into a @dfn{macro package}.
1713 All macro packages provide certain common capabilities which fall into
1714 the following categories.
1718 * Sections and Chapters::
1719 * Headers and Footers::
1720 * Page Layout Adjustment::
1722 * Footnotes and Annotations::
1723 * Table of Contents::
1726 * Multiple Columns::
1727 * Font and Size Changes::
1728 * Predefined Strings::
1729 * Preprocessor Support::
1730 * Configuration and Customization::
1733 @c ---------------------------------------------------------------------
1735 @node Paragraphs, Sections and Chapters, Common Features, Common Features
1736 @subsection Paragraphs
1739 One of the most common and most used capability is starting a
1740 paragraph. There are a number of different types of paragraphs, any
1741 of which can be initiated with macros supplied by the macro package.
1742 Normally, paragraphs start with a blank line and the first line
1743 indented, like the text in this manual. There are also block style
1744 paragraphs, which omit the indentation:
1747 Some men look at constitutions with sanctimonious
1748 reverence, and deem them like the ark of the covenant, too
1749 sacred to be touched.
1753 And there are also indented paragraphs which begin with a tag or label
1754 at the margin and the remaining text indented.
1757 one This is the first paragraph. Notice how the first
1758 line of the resulting paragraph lines up with the
1759 other lines in the paragraph.
1763 This paragraph had a long label. The first
1764 character of text on the first line does not line up
1765 with the text on second and subsequent lines,
1766 although they line up with each other.
1769 A variation of this is a bulleted list.
1772 . Bulleted lists start with a bullet. It is possible
1773 to use other glyphs instead of the bullet. In nroff
1774 mode using the ASCII character set for output, a dot
1775 is used instead of a real bullet.
1778 @c ---------------------------------------------------------------------
1780 @node Sections and Chapters, Headers and Footers, Paragraphs, Common Features
1781 @subsection Sections and Chapters
1783 Most macro packages supply some form of section headers. The simplest
1784 kind is simply the heading on a line by itself in bold type. Others
1785 supply automatically numbered section heading or different heading
1786 styles at different levels. Some, more sophisticated, macro packages
1787 supply macros for starting chapters and appendices.
1789 @c ---------------------------------------------------------------------
1791 @node Headers and Footers, Page Layout Adjustment, Sections and Chapters, Common Features
1792 @subsection Headers and Footers
1794 Every macro package gives some way to manipulate the @dfn{headers} and
1795 @dfn{footers} (also called @dfn{titles}) on each page. This is text
1796 put at the top and bottom of each page, respectively, which contain
1797 data like the current page number, the current chapter title, and so
1798 on. Its appearance is not affected by the running text. Some packages
1799 allow for different ones on the even and odd pages (for material printed
1802 The titles are called @dfn{three-part titles}, that is, there is a
1803 left-justified part, a centered part, and a right-justified part. An
1804 automatically generated page number may be put in any of these fields
1805 with the @samp{%} character (see @ref{Page Layout}, for more details).
1807 @c ---------------------------------------------------------------------
1809 @node Page Layout Adjustment, Displays, Headers and Footers, Common Features
1810 @subsection Page Layout
1812 Most macro packages let the user specify top and bottom margins and
1813 other details about the appearance of the printed pages.
1815 @c ---------------------------------------------------------------------
1817 @node Displays, Footnotes and Annotations, Page Layout Adjustment, Common Features
1818 @subsection Displays
1821 @dfn{Displays} are sections of text to be set off from the body of
1822 the paper. Major quotes, tables, and figures are types of displays, as
1823 are all the examples used in this document.
1825 @cindex quotes, major
1826 @cindex major quotes
1827 @dfn{Major quotes} are quotes which are several lines long, and hence
1828 are set in from the rest of the text without quote marks around them.
1831 A @dfn{list} is an indented, single-spaced, unfilled display. Lists
1832 should be used when the material to be printed should not be filled and
1833 justified like normal text, such as columns of figures or the examples
1837 A @dfn{keep} is a display of lines which are kept on a single page if
1838 possible. An example for a keep might be a diagram. Keeps differ from
1839 lists in that lists may be broken over a page boundary whereas keeps are
1842 @cindex keep, floating
1843 @cindex floating keep
1844 @dfn{Floating keeps} move relative to the text. Hence, they are good for
1845 things which are referred to by name, such as ``See figure@tie{}3''. A
1846 floating keep appears at the bottom of the current page if it fits;
1847 otherwise, it appears at the top of the next page. Meanwhile, the
1848 surrounding text `flows' around the keep, thus leaving no blank areas.
1850 @c ---------------------------------------------------------------------
1852 @node Footnotes and Annotations, Table of Contents, Displays, Common Features
1853 @subsection Footnotes and Annotations
1857 There are a number of requests to save text for later printing.
1859 @dfn{Footnotes} are printed at the bottom of the current page.
1861 @cindex delayed text
1862 @dfn{Delayed text} is very similar to a footnote except that it is
1863 printed when called for explicitly. This allows a list of references to
1864 appear (for example) at the end of each chapter, as is the convention in
1867 Most macro packages which supply this functionality also supply a means
1868 of automatically numbering either type of annotation.
1870 @c ---------------------------------------------------------------------
1872 @node Table of Contents, Indices, Footnotes and Annotations, Common Features
1873 @subsection Table of Contents
1874 @cindex table of contents
1875 @cindex contents, table of
1877 @dfn{Tables of contents} are a type of delayed text having a tag
1878 (usually the page number) attached to each entry after a row of dots.
1879 The table accumulates throughout the paper until printed, usually after
1880 the paper has ended. Many macro packages provide the ability to have
1881 several tables of contents (e.g.@: a standard table of contents, a list
1884 @c ---------------------------------------------------------------------
1886 @node Indices, Paper Formats, Table of Contents, Common Features
1888 @cindex index, in macro package
1890 While some macro packages use the term @dfn{index}, none actually
1891 provide that functionality. The facilities they call indices are
1892 actually more appropriate for tables of contents.
1895 To produce a real index in a document, external tools like the
1896 @code{makeindex} program are necessary.
1898 @c ---------------------------------------------------------------------
1900 @node Paper Formats, Multiple Columns, Indices, Common Features
1901 @subsection Paper Formats
1902 @cindex paper formats
1904 Some macro packages provide stock formats for various kinds of
1905 documents. Many of them provide a common format for the title and
1906 opening pages of a technical paper. The @file{mm} macros in particular
1907 provide formats for letters and memoranda.
1909 @c ---------------------------------------------------------------------
1911 @node Multiple Columns, Font and Size Changes, Paper Formats, Common Features
1912 @subsection Multiple Columns
1914 Some macro packages (but not @file{man}) provide the ability to have two
1915 or more columns on a page.
1917 @c ---------------------------------------------------------------------
1919 @node Font and Size Changes, Predefined Strings, Multiple Columns, Common Features
1920 @subsection Font and Size Changes
1922 The built-in font and size functions are not always intuitive, so all
1923 macro packages provide macros to make these operations simpler.
1925 @c ---------------------------------------------------------------------
1927 @node Predefined Strings, Preprocessor Support, Font and Size Changes, Common Features
1928 @subsection Predefined Strings
1930 Most macro packages provide various predefined strings for a variety of
1931 uses; examples are sub- and superscripts, printable dates, quotes and
1932 various special characters.
1934 @c ---------------------------------------------------------------------
1936 @node Preprocessor Support, Configuration and Customization, Predefined Strings, Common Features
1937 @subsection Preprocessor Support
1939 All macro packages provide support for various preprocessors and may
1940 extend their functionality.
1942 For example, all macro packages mark tables (which are processed with
1943 @code{gtbl}) by placing them between @code{TS} and @code{TE} macros.
1944 The @file{ms} macro package has an option, @samp{.TS@tie{}H}, that prints
1945 a caption at the top of a new page (when the table is too long to fit on
1948 @c ---------------------------------------------------------------------
1950 @node Configuration and Customization, , Preprocessor Support, Common Features
1951 @subsection Configuration and Customization
1953 Some macro packages provide means of customizing many of the details of
1954 how the package behaves. This ranges from setting the default type size
1955 to changing the appearance of section headers.
1959 @c =====================================================================
1960 @c =====================================================================
1962 @node Macro Packages, gtroff Reference, Tutorial for Macro Users, Top
1963 @chapter Macro Packages
1964 @cindex macro packages
1965 @cindex packages, macros
1967 This chapter documents the main macro packages that come with
1970 Different main macro packages can't be used at the same time; for example
1973 groff -m man foo.man -m ms bar.doc
1977 doesn't work. Note that option arguments are processed before non-option
1978 arguments; the above (failing) sample is thus reordered to
1981 groff -m man -m ms foo.man bar.doc
1993 @c =====================================================================
1995 @node man, mdoc, Macro Packages, Macro Packages
1997 @cindex manual pages
2001 @pindex man-old.tmac
2003 This is the most popular and probably the most important macro package
2004 of @code{groff}. It is easy to use, and a vast majority of manual pages
2011 * Miscellaneous man macros::
2012 * Predefined man strings::
2013 * Preprocessors in man pages::
2014 * Optional man extensions::
2017 @c ---------------------------------------------------------------------
2019 @node Man options, Man usage, man, man
2022 The command line format for using the @file{man} macros with
2026 groff -m man [ -rLL=@var{length} ] [ -rLT=@var{length} ] [ -rFT=@var{dist} ]
2027 [ -rcR=1 ] [ -rC1 ] [ -rD1 ] [-rHY=@var{flags} ]
2028 [ -rP@var{nnn} ] [ -rS@var{xx} ] [ -rX@var{nnn} ]
2029 [ -rIN=@var{length} ] [ -rSN=@var{length} ] [ @var{files}@dots{} ]
2033 It is possible to use @samp{-man} instead of @w{@samp{-m man}}.
2037 This option (the default if a TTY output device is used) creates a
2038 single, very long page instead of multiple pages. Use @code{-rcR=0}
2042 If more than one manual page is given on the command line, number the
2043 pages continuously, rather than starting each at@tie{}1.
2046 Double-sided printing. Footers for even and odd pages are formatted
2049 @item -rFT=@var{dist}
2050 Set the position of the footer text to @var{dist}. If positive, the
2051 distance is measured relative to the top of the page, otherwise it is
2052 relative to the bottom. The default is @minus{}0.5@dmn{i}.
2054 @item -rHY=@var{flags}
2055 Set hyphenation flags. Possible values are 1@tie{}to hyphenate without
2056 restrictions, 2@tie{} to not hyphenate the last word on a page,
2057 4@tie{}to not hyphenate the last two characters of a word, and
2058 8@tie{}to not hyphenate the first two characters of a word. These
2059 values are additive; the default is@tie{}14.
2061 @item -rIN=@var{length}
2062 Set the body text indent to @var{length}.
2063 If not specified, the indent defaults to 7@dmn{n}
2064 (7@tie{}characters) in nroff mode and 7.2@dmn{n} otherwise.
2065 For nroff, this value should always be an integer multiple of unit @samp{n}
2066 to get consistent indentation.
2068 @item -rLL=@var{length}
2069 Set line length to @var{length}. If not specified, the line length
2070 defaults to 78@tie{}en in nroff mode (this is 78@tie{}characters per
2071 line) and 6.5@tie{}inch otherwise.
2073 @item -rLT=@var{length}
2074 Set title length to @var{length}. If not specified, the title length
2075 defaults to the line length.
2078 Page numbering starts with @var{nnn} rather than with@tie{}1.
2081 Use @var{xx} (which can be 10, 11, or@tie{}12@dmn{pt}) as the base
2082 document font size instead of the default value of@tie{}10@dmn{pt}.
2084 @item -rSN=@var{length}
2085 Set the indent for sub-subheadings to @var{length}.
2086 If not specified, the indent defaults to 3@dmn{n}.
2089 After page @var{nnn}, number pages as @var{nnn}a, @var{nnn}b,
2090 @var{nnn}c, etc. For example, the option @option{-rX2} produces the
2091 following page numbers: 1, 2, 2a, 2b, 2c, etc.
2094 @c ---------------------------------------------------------------------
2096 @node Man usage, Man font macros, Man options, man
2098 @cindex @code{man} macros
2099 @cindex macros for manual pages [@code{man}]
2102 This section describes the available macros for manual pages. For
2103 further customization, put additional macros and requests into the file
2104 @file{man.local} which is loaded immediately after the @file{man}
2107 @Defmac {TH, title section [@Var{extra1} [@Var{extra2} [@Var{extra3}]]], man}
2108 Set the title of the man page to @var{title} and the section to
2109 @var{section}, which must have a value between 1 and@tie{}8. The value
2110 of @var{section} may also have a string appended, e.g.@: @samp{.pm},
2111 to indicate a specific subsection of the man pages.
2113 Both @var{title} and @var{section} are positioned at the left and right
2114 in the header line (with @var{section} in parentheses immediately
2115 appended to @var{title}. @var{extra1} is positioned in the middle of
2116 the footer line. @var{extra2} is positioned at the left in the footer
2117 line (or at the left on even pages and at the right on odd pages if
2118 double-sided printing is active). @var{extra3} is centered in the
2121 For @acronym{HTML} output, headers and footers are completely suppressed.
2123 Additionally, this macro starts a new page; the new line number is@tie{}1
2124 again (except if the @option{-rC1} option is given on the command line)
2125 -- this feature is intended only for formatting multiple man pages; a
2126 single man page should contain exactly one @code{TH} macro at the
2127 beginning of the file.
2130 @Defmac {SH, [@Var{heading}], man}
2131 Set up an unnumbered section heading sticking out to the left. Prints
2132 out all the text following @code{SH} up to the end of the line (or the
2133 text in the next line if there is no argument to @code{SH}) in bold
2134 face (or the font specified by the string @code{HF}), one size larger than
2135 the base document size. Additionally, the left margin and the indentation
2136 for the following text is reset to its default value.
2139 @Defmac {SS, [@Var{heading}], man}
2140 Set up an unnumbered (sub)section heading. Prints out all the text
2141 following @code{SS} up to the end of the line (or the text in the next
2142 line if there is no argument to @code{SS}) in bold face (or the font
2143 specified by the string @code{HF}), at the same size as the base document
2144 size. Additionally, the left margin and the indentation for the
2145 following text is reset to its default value.
2148 @Defmac {TP, [@Var{nnn}], man}
2149 Set up an indented paragraph with label. The indentation is set to
2150 @var{nnn} if that argument is supplied (the default unit is @samp{n}
2151 if omitted), otherwise it is set to the previous indentation value
2152 specified with @code{TP}, @code{IP}, or @code{HP} (or to the default
2153 value if none of them have been used yet).
2155 The first line of text following this macro is interpreted as a string
2156 to be printed flush-left, as it is appropriate for a label. It is not
2157 interpreted as part of a paragraph, so there is no attempt to fill the
2158 first line with text from the following input lines. Nevertheless, if
2159 the label is not as wide as the indentation the paragraph starts
2160 at the same line (but indented), continuing on the following lines.
2161 If the label is wider than the indentation the descriptive part
2162 of the paragraph begins on the line following the label, entirely
2163 indented. Note that neither font shape nor font size of the label is
2164 set to a default value; on the other hand, the rest of the text has
2165 default font settings.
2168 @DefmacList {LP, , man}
2169 @DefmacItem {PP, , man}
2170 @DefmacListEnd {P, , man}
2171 These macros are mutual aliases. Any of them causes a line break at
2172 the current position, followed by a vertical space downwards by the
2173 amount specified by the @code{PD} macro. The font size and shape are
2174 reset to the default value (10@dmn{pt} roman if no @option{-rS} option
2175 is given on the command line). Finally, the current left margin and the
2176 indentation is restored.
2179 @Defmac {IP, [@Var{designator} [@Var{nnn}]], man}
2180 Set up an indented paragraph, using @var{designator} as a tag to mark
2181 its beginning. The indentation is set to @var{nnn} if that argument
2182 is supplied (default unit is @samp{n}), otherwise it is set to the
2183 previous indentation value specified with @code{TP}, @code{IP}, or
2184 @code{HP} (or the default value if none of them have been used yet).
2185 Font size and face of the paragraph (but not the designator) are reset
2186 to their default values.
2188 To start an indented paragraph with a particular indentation but without
2189 a designator, use @samp{""} (two double quotes) as the first argument of
2192 For example, to start a paragraph with bullets as the designator and
2193 4@tie{}en indentation, write
2200 @Defmac {HP, [@Var{nnn}], man}
2201 @cindex hanging indentation [@code{man}]
2202 @cindex @code{man} macros, hanging indentation
2203 Set up a paragraph with hanging left indentation. The indentation is
2204 set to @var{nnn} if that argument is supplied (default unit is
2205 @samp{n}), otherwise it is set to the previous indentation value
2206 specified with @code{TP}, @code{IP}, or @code{HP} (or the default
2207 value if non of them have been used yet). Font size and face are reset
2208 to their default values.
2211 @Defmac {RS, [@Var{nnn}], man}
2212 @cindex left margin, how to move [@code{man}]
2213 @cindex @code{man} macros, moving left margin
2214 Move the left margin to the right by the value @var{nnn} if specified
2215 (default unit is @samp{n}); otherwise it is set to the previous
2216 indentation value specified with @code{TP}, @code{IP}, or @code{HP}
2217 (or to the default value if none of them have been used yet). The
2218 indentation value is then set to the default.
2220 Calls to the @code{RS} macro can be nested.
2223 @Defmac {RE, [@Var{nnn}], man}
2224 Move the left margin back to level @var{nnn}, restoring the previous left
2225 margin. If no argument is given, it moves one level back. The first
2226 level (i.e., no call to @code{RS} yet) has number@tie{}1, and each call
2227 to @code{RS} increases the level by@tie{}1.
2230 @cindex line breaks, with vertical space [@code{man}]
2231 @cindex @code{man} macros, line breaks with vertical space
2232 To summarize, the following macros cause a line break with the insertion
2233 of vertical space (which amount can be changed with the @code{PD}
2234 macro): @code{SH}, @code{SS}, @code{TP}, @code{LP} (@code{PP},
2235 @code{P}), @code{IP}, and @code{HP}.
2237 @cindex line breaks, without vertical space [@code{man}]
2238 @cindex @code{man} macros, line breaks without vertical space
2239 The macros @code{RS} and @code{RE} also cause a break but do not insert
2242 @cindex default indentation, resetting [@code{man}]
2243 @cindex indentaion, resetting to default [@code{man}]
2244 @cindex @code{man} macros, resetting default indentation
2245 Finally, the macros @code{SH}, @code{SS}, @code{LP} (@code{PP}, @code{P}),
2246 and @code{RS} reset the indentation to its default value.
2248 @c ---------------------------------------------------------------------
2250 @node Man font macros, Miscellaneous man macros, Man usage, man
2251 @subsection Macros to set fonts
2252 @cindex font selection [@code{man}]
2253 @cindex @code{man} macros, how to set fonts
2255 The standard font is roman; the default text size is 10@tie{}point.
2256 If command line option @option{-rS=@var{n}} is given, use
2257 @var{n}@dmn{pt} as the default text size.
2259 @Defmac {SM, [@Var{text}], man}
2260 Set the text on the same line or the text on the next line in a font
2261 that is one point size smaller than the default font.
2264 @Defmac {SB, [@Var{text}], man}
2265 @cindex bold face [@code{man}]
2266 @cindex @code{man} macros, bold face
2267 Set the text on the same line or the text on the next line in bold face
2268 font, one point size smaller than the default font.
2271 @Defmac {BI, text, man}
2272 Set its arguments alternately in bold face and italic, without a space
2273 between the arguments. Thus,
2276 .BI this "word and" that
2280 produces ``thisword andthat'' with ``this'' and ``that'' in bold face,
2281 and ``word and'' in italics.
2284 @Defmac {IB, text, man}
2285 Set its arguments alternately in italic and bold face, without a space
2286 between the arguments.
2289 @Defmac {RI, text, man}
2290 Set its arguments alternately in roman and italic, without a space between
2294 @Defmac {IR, text, man}
2295 Set its arguments alternately in italic and roman, without a space between
2299 @Defmac {BR, text, man}
2300 Set its arguments alternately in bold face and roman, without a space
2301 between the arguments.
2304 @Defmac {RB, text, man}
2305 Set its arguments alternately in roman and bold face, without a space
2306 between the arguments.
2309 @Defmac {B, [@Var{text}], man}
2310 Set @var{text} in bold face. If no text is present on the line where
2311 the macro is called, then the text of the next line appears in bold
2315 @Defmac {I, [@Var{text}], man}
2316 @cindex italic fonts [@code{man}]
2317 @cindex @code{man} macros, italic fonts
2318 Set @var{text} in italic. If no text is present on the line where the
2319 macro is called, then the text of the next line appears in italic.
2322 @c ---------------------------------------------------------------------
2324 @node Miscellaneous man macros, Predefined man strings, Man font macros, man
2325 @subsection Miscellaneous macros
2328 @cindex @code{man} macros, default indentation
2329 @cindex default indentation [@code{man}]
2330 The default indentation is 7.2@dmn{n} in troff mode and 7@dmn{n} in
2331 nroff mode except for @code{grohtml} which ignores indentation.
2334 @cindex tab stops [@code{man}]
2335 @cindex @code{man} macros, tab stops
2336 Set tabs every 0.5@tie{}inches. Since this macro is always executed
2337 during a call to the @code{TH} macro, it makes sense to call it only if
2338 the tab positions have been changed.
2341 @Defmac {PD, [@Var{nnn}], man}
2342 @cindex empty space before a paragraph [@code{man}]
2343 @cindex @code{man} macros, empty space before a paragraph
2344 Adjust the empty space before a new paragraph (or section). The
2345 optional argument gives the amount of space (default unit is
2346 @samp{v}); without parameter, the value is reset to its default value
2347 (1@tie{}line in nroff mode, 0.4@dmn{v}@tie{}otherwise).
2349 This affects the macros @code{SH}, @code{SS}, @code{TP}, @code{LP} (as
2350 well as @code{PP} and @code{P}), @code{IP}, and @code{HP}.
2353 The following two macros are included for
2356 @Defmac {AT, [@Var{system} [@Var{release}]], man}
2357 @cindex @code{man}macros, BSD compatibility
2358 Alter the footer for use with @acronym{AT&T} manpages.
2359 This command exists only for compatibility; don't use it.
2360 The first argument @var{system} can be:
2364 7th Edition (the default)
2373 An optional second argument @var{release} to @code{AT} specifies the
2374 release number (such as ``System V Release 3'').
2377 @Defmac {UC, [@Var{version}], man}
2378 @cindex @code{man}macros, BSD compatibility
2379 Alters the footer for use with @acronym{BSD} manpages.
2380 This command exists only for compatibility; don't use it.
2381 The argument can be:
2385 3rd Berkeley Distribution (the default)
2388 4th Berkeley Distribution
2391 4.2 Berkeley Distribution
2394 4.3 Berkeley Distribution
2397 4.4 Berkeley Distribution
2401 @c ---------------------------------------------------------------------
2403 @node Predefined man strings, Preprocessors in man pages, Miscellaneous man macros, man
2404 @subsection Predefined strings
2406 The following strings are defined:
2409 Switch back to the default font size.
2413 The typeface used for headings.
2414 The default is @samp{B}.
2418 The `registered' sign.
2422 The `trademark' sign.
2425 @DefstrList {lq, man}
2426 @DefstrListEnd {rq, man}
2427 @cindex @code{lq} glyph, and @code{lq} string [@code{man}]
2428 @cindex @code{rq} glyph, and @code{rq} string [@code{man}]
2429 Left and right quote. This is equal to @code{\(lq} and @code{\(rq},
2433 @c ---------------------------------------------------------------------
2435 @node Preprocessors in man pages, Optional man extensions, Predefined man strings, man
2436 @subsection Preprocessors in @file{man} pages
2438 @cindex preprocessor, calling convention
2439 @cindex calling convention of preprocessors
2440 If a preprocessor like @code{gtbl} or @code{geqn} is needed, it has
2441 become common usage to make the first line of the man page look like
2448 @pindex geqn@r{, invocation in manual pages}
2449 @pindex grefer@r{, invocation in manual pages}
2450 @pindex gtbl@r{, invocation in manual pages}
2451 @pindex man@r{, invocation of preprocessors}
2453 Note the single space character after the double quote. @var{word}
2454 consists of letters for the needed preprocessors: @samp{e} for
2455 @code{geqn}, @samp{r} for @code{grefer}, @samp{t} for @code{gtbl}.
2456 Modern implementations of the @code{man} program read this first line
2457 and automatically call the right preprocessor(s).
2459 @c ---------------------------------------------------------------------
2461 @node Optional man extensions, , Preprocessors in man pages, man
2462 @subsection Optional @file{man} extensions
2465 Use the file @file{man.local} for local extensions
2466 to the @code{man} macros or for style changes.
2468 @unnumberedsubsubsec Custom headers and footers
2469 @cindex @code{man} macros, custom headers and footers
2471 In groff versions 1.18.2 and later, you can specify custom
2472 headers and footers by redefining the following macros in
2476 Control the content of the headers.
2477 Normally, the header prints the command name
2478 and section number on either side, and the
2479 optional fifth argument to @code{TH} in the center.
2483 Control the content of the footers.
2484 Normally, the footer prints the page number
2485 and the third and fourth arguments to @code{TH}.
2487 Use the @code{FT} number register to specify the
2489 The default is @minus{}0.5@dmn{i}.
2492 @unnumberedsubsubsec Ultrix-specific man macros
2493 @cindex Ultrix-specific @code{man} macros
2494 @cindex @code{man} macros, Ultrix-specific
2497 The @code{groff} source distribution includes
2498 a file named @file{man.ultrix}, containing
2499 macros compatible with the Ultrix variant of
2501 Copy this file into @file{man.local} (or use the @code{mso} request to
2502 load it) to enable the following macros.
2504 @Defmac {CT, @Var{key}, man}
2505 Print @samp{<CTRL/@var{key}>}.
2509 Print subsequent text using the constant width (Courier) typeface.
2513 Begin a non-filled display.
2517 End a non-filled display started with @code{Ds}.
2520 @Defmac {EX, [@Var{indent}], man}
2521 Begins a non-filled display
2522 using the constant width (Courier) typeface.
2523 Use the optional @var{indent} argument to
2528 End a non-filled display started with @code{EX}.
2531 @Defmac {G, [@Var{text}], man}
2532 Sets @var{text} in Helvetica.
2533 If no text is present on the line where
2534 the macro is called, then the text of the
2535 next line appears in Helvetica.
2538 @Defmac {GL, [@Var{text}], man}
2539 Sets @var{text} in Helvetica Oblique.
2540 If no text is present on the line where
2541 the macro is called, then the text of the
2542 next line appears in Helvetica Oblique.
2545 @Defmac {HB, [@Var{text}], man}
2546 Sets @var{text} in Helvetica Bold.
2547 If no text is present on the line where
2548 the macro is called, then all text up to
2549 the next @code{HB} appears in Helvetica Bold.
2552 @Defmac {TB, [@Var{text}], man}
2553 Identical to @code{HB}.
2556 @Defmac {MS, @Var{title} @Var{sect} [@Var{punct}], man}
2557 Set a manpage reference in Ultrix format.
2558 The @var{title} is in Courier instead of italic.
2559 Optional punctuation follows the section number without
2560 an intervening space.
2563 @Defmac {NT, [@code{C}] [@Var{title}], man}
2565 Print the optional @Var{title}, or the word ``Note'',
2566 centered on the page.
2567 Text following the macro makes up the body of the note,
2568 and is indented on both sides.
2569 If the first argument is @code{C}, the body of the
2570 note is printed centered (the second argument replaces
2571 the word ``Note'' if specified).
2575 End a note begun with @code{NT}.
2578 @Defmac {PN, @Var{path} [@Var{punct}], man}
2579 Set the path name in constant width (Courier),
2580 followed by optional punctuation.
2583 @Defmac {Pn, [@Var{punct}] @Var{path} [@Var{punct}], man}
2584 When called with two arguments, identical to @code{PN}.
2585 When called with three arguments,
2586 set the second argument in constant width (Courier),
2587 bracketed by the first and third arguments in the current font.
2591 Switch to roman font and turn off any underlining in effect.
2595 Print the string @samp{<RETURN>}.
2598 @Defmac {VS, [@code{4}], man}
2599 Start printing a change bar in the margin if
2600 the number @code{4} is specified.
2601 Otherwise, this macro does nothing.
2605 End printing the change bar begun by @code{VS}.
2608 @unnumberedsubsubsec Simple example
2610 The following example @file{man.local} file
2611 alters the @code{SH} macro to add some extra
2612 vertical space before printing the heading.
2613 Headings are printed in Helvetica Bold.
2616 .\" Make the heading fonts Helvetica
2619 .\" Put more whitespace in front of headings.
2622 . if t .sp (u;\\n[PD]*2)
2627 @c =====================================================================
2629 @node mdoc, ms, man, Macro Packages
2630 @section @file{mdoc}
2631 @cindex @code{mdoc} macros
2633 @c XXX documentation
2634 @c XXX this is a placeholder until we get stuff knocked into shape
2635 See the @cite{groff_mdoc(7)} man page (type @command{man groff_mdoc}
2636 at the command line).
2639 @c =====================================================================
2641 @node ms, me, mdoc, Macro Packages
2643 @cindex @code{ms} macros
2646 macros are suitable for reports, letters, books,
2647 user manuals, and so forth.
2648 The package provides macros for cover pages, section headings,
2649 paragraphs, lists, footnotes, pagination,
2650 and a table of contents.
2654 * General ms Structure::
2655 * ms Document Control Registers::
2656 * ms Cover Page Macros::
2659 * Differences from AT&T ms::
2662 @c ---------------------------------------------------------------------
2664 @node ms Intro, General ms Structure, ms, ms
2665 @subsection Introduction to @file{ms}
2667 The original @file{-ms} macros were included with
2668 @acronym{AT&T} @code{troff} as well as the
2670 While the @file{man} package is intended for brief documents
2671 that can be read on-line as well as printed, the @file{ms}
2672 macros are suitable for longer documents that are meant to be
2673 printed rather than read on-line.
2675 The @file{ms} macro package included with @code{groff}
2676 is a complete, bottom-up re-implementation.
2677 Several macros (specific to @acronym{AT&T}
2678 or Berkeley) are not included, while several new commands are.
2679 @xref{Differences from AT&T ms}, for more information.
2681 @c ---------------------------------------------------------------------
2683 @node General ms Structure, ms Document Control Registers, ms Intro, ms
2684 @subsection General structure of an @file{ms} document
2685 @cindex @code{ms} macros, general structure
2687 The @file{ms} macro package expects a certain amount of structure,
2688 but not as much as packages such as @file{man} or @file{mdoc}.
2690 The simplest documents can begin with a paragraph macro
2691 (such as @code{LP} or @code{PP}),
2692 and consist of text separated by paragraph macros
2693 or even blank lines.
2694 Longer documents have a structure as follows:
2698 If you invoke the @code{RP}
2699 (report) macro on the first line of the document,
2700 @code{groff} prints the cover page information on its own page;
2701 otherwise it prints the information on the
2702 first page with your document text immediately following.
2703 Other document formats found in @acronym{AT&T} @code{troff}
2704 are specific to @acronym{AT&T} or Berkeley, and are not supported in
2707 @item Format and layout
2708 By setting number registers,
2709 you can change your document's type (font and size),
2710 margins, spacing, headers and footers, and footnotes.
2711 @xref{ms Document Control Registers}, for more details.
2714 A cover page consists of a title, the author's name and institution,
2715 an abstract, and the date.
2716 @footnote{Actually, only the title is required.}
2717 @xref{ms Cover Page Macros}, for more details.
2720 Following the cover page is your document.
2721 You can use the @file{ms}
2722 macros to write reports, letters, books, and so forth.
2723 The package is designed for structured documents,
2724 consisting of paragraphs interspersed with headings
2725 and augmented by lists, footnotes, tables, and other
2727 @xref{ms Body Text}, for more details.
2729 @item Table of contents
2730 Longer documents usually include a table of contents,
2731 which you can invoke by placing the
2733 macro at the end of your document.
2735 macros have minimal indexing facilities, consisting of the
2736 @code{IX} macro, which prints an entry on standard error.
2737 Printing the table of contents at the end is necessary since
2738 @code{groff} is a single-pass text formatter,
2739 thus it cannot determine the page number of each section
2740 until that section has actually been set and printed.
2741 Since @file{ms} output is intended for hardcopy,
2742 you can manually relocate the pages containing
2743 the table of contents between the cover page and the
2744 body text after printing.
2747 @c ---------------------------------------------------------------------
2749 @node ms Document Control Registers, ms Cover Page Macros, General ms Structure, ms
2750 @subsection Document control registers
2751 @cindex @code{ms} macros, document control registers
2753 The following is a list of document control number registers.
2754 For the sake of consistency,
2755 set registers related to margins at the beginning of your document,
2756 or just after the @code{RP} macro.
2757 You can set other registers later in your document,
2758 but you should keep them together at the beginning
2759 to make them easy to find and edit as necessary.
2761 @unnumberedsubsubsec Margin Settings
2764 Defines the page offset (i.e.@: the left margin).
2765 There is no explicit right margin setting; the combination of
2766 the @code{PO} and @code{LL} registers implicitly define the
2769 Effective: next page.
2771 Default value: 1@dmn{i}.
2775 Defines the line length (i.e.@: the width of the body text).
2777 Effective: next paragraph.
2783 Defines the title length (i.e.@: the header and footer width).
2784 This is usually the same as @code{LL}, but not necessarily.
2786 Effective: next paragraph.
2792 Defines the header margin height at the top of the page.
2794 Effective: next page.
2800 Defines the footer margin height at the bottom of the page.
2802 Effective: next page.
2807 @unnumberedsubsubsec Text Settings
2810 Defines the point size of the body text.
2812 Effective: next paragraph.
2818 Defines the space between lines (line height plus leading).
2820 Effective: next paragraph.
2825 @unnumberedsubsubsec Paragraph Settings
2828 Defines the initial indent of a @code{.PP} paragraph.
2830 Effective: next paragraph.
2836 Defines the space between paragraphs.
2838 Effective: next paragraph.
2840 Default: 0.3@dmn{v}.
2844 Defines the indent on both sides of a quoted (@code{.QP}) paragraph.
2846 Effective: next paragraph.
2851 @unnumberedsubsubsec Footnote Settings
2854 Defines the length of a footnote.
2856 Effective: next footnote.
2858 Default: @math{@code{@\n[LL]} * 5 / 6}.
2862 Defines the footnote indent.
2864 Effective: next footnote.
2870 The footnote format:
2873 Prints the footnote number as a superscript; indents the footnote (default).
2876 Prints the number followed by a period (like 1.)
2877 and indents the footnote.
2880 Like 1, without an indent.
2883 Like 1, but prints the footnote number as a hanging paragraph.
2886 Effective: next footnote.
2892 Defines the footnote point size.
2894 Effective: next footnote.
2896 Default: @math{@code{@\n[PS]} - 2}.
2900 Defines the footnote vertical spacing.
2902 Effective: next footnote.
2904 Default: @math{@code{@\n[FPS]} + 2}.
2908 Defines the footnote paragraph spacing.
2910 Effective: next footnote.
2912 Default: @math{@code{@\n[PD]} / 2}.
2915 @unnumberedsubsubsec Miscellaneous Number Registers
2917 @Defmpreg {MINGW, ms}
2918 Defines the minimum width between columns in a multi-column document.
2920 Effective: next page.
2925 @c ---------------------------------------------------------------------
2927 @node ms Cover Page Macros, ms Body Text, ms Document Control Registers, ms
2928 @subsection Cover page macros
2929 @cindex @code{ms} macros, cover page
2930 @cindex cover page macros, [@code{ms}]
2932 Use the following macros to create a cover page for your document
2935 @Defmac {RP, [@code{no}], ms}
2936 Specifies the report format for your document.
2937 The report format creates a separate cover page.
2938 The default action (no @code{.RP}
2939 macro) is to print a subset of the
2940 cover page on page 1 of your document.
2942 If you use the word @code{no} as an optional argument,
2943 @code{groff} prints a title page but
2944 does not repeat any of the title page information
2945 (title, author, abstract, etc.)
2946 on page 1 of the document.
2949 @Defmac {DA, [@dots{}], ms}
2950 (optional) Print the current date, or the arguments to the macro if any,
2951 on the title page (if specified) and in the footers.
2952 This is the default for @code{nroff}.
2955 @Defmac {ND, [@dots{}], ms}
2956 (optional) Print the current date, or the arguments to the macro if any,
2957 on the title page (if specified) but not in the footers.
2958 This is the default for @code{troff}.
2962 Specifies the document title.
2963 @code{groff} collects text following the @code{.TL}
2964 macro into the title, until reaching the author name or abstract.
2968 Specifies the author's name, which appears on the
2969 line (or lines) immediately following.
2970 You can specify multiple authors as follows:
2976 University of West Bumblefuzz
2980 Monolithic Corporation
2987 Specifies the author's institution.
2988 You can specify multiple institutions in the same way
2989 that you specify multiple authors.
2992 @Defmac {AB, [@code{no}], ms}
2993 Begins the abstract.
2994 The default is to print the word @acronym{ABSTRACT},
2995 centered and in italics, above the text of the abstract.
2996 The word @code{no} as an optional argument suppresses this heading.
3003 The following is example mark-up for a title page.
3004 @cindex title page, example markup
3005 @cindex example markup, title page
3011 The Inevitability of Code Bloat
3012 in Commercial and Free Software
3016 University of West Bumblefuzz
3018 This report examines the long-term growth
3019 of the code bases in two large, popular software
3020 packages; the free Emacs and the commercial
3022 While differences appear in the type or order
3023 of features added, due to the different
3024 methodologies used, the results are the same
3027 The free software approach is shown to be
3028 superior in that while free software can
3029 become as bloated as commercial offerings,
3030 free software tends to have fewer serious
3031 bugs and the added features are in line with
3035 ... the rest of the paper follows ...
3039 @c ---------------------------------------------------------------------
3041 @node ms Body Text, ms Page Layout, ms Cover Page Macros, ms
3042 @subsection Body text
3043 @cindex @code{ms} macros, body text
3045 This section describes macros used to mark up the body of your document.
3046 Examples include paragraphs, sections, and other groups.
3049 * Paragraphs in ms::
3051 * Highlighting in ms::
3055 * ms Displays and Keeps::
3057 * Example multi-page table::
3061 @c ---------------------------------------------------------------------
3063 @node Paragraphs in ms, Headings in ms, ms Body Text, ms Body Text
3064 @subsubsection Paragraphs
3065 @cindex @code{ms} macros, paragraph handling
3067 The following paragraph types are available.
3070 Sets a paragraph with an initial indent.
3074 Sets a paragraph with no initial indent.
3078 Sets a paragraph that is indented at both left and right margins.
3079 The effect is identical to the @acronym{HTML} @code{<BLOCKQUOTE>} element.
3080 The next paragraph or heading returns margins to normal.
3084 Sets a paragraph whose lines are indented,
3085 except for the first line.
3086 This is a Berkeley extension.
3089 The following markup uses all four paragraph macros.
3094 Cases used in the study
3096 The following software and versions were
3097 considered for this report.
3099 For commercial software, we chose
3100 .B "Microsoft Word for Windows" ,
3101 starting with version 1.0 through the
3102 current version (Word 2000).
3104 For free software, we chose
3106 from its first appearance as a standalone
3107 editor through the current version (v20).
3108 See [Bloggs 2002] for details.
3110 Franklin's Law applied to software:
3111 software expands to outgrow both
3112 RAM and disk space over time.
3117 .I "Everyone's a Critic" ,
3118 Underground Press, March 2002.
3119 A definitive work that answers all questions
3120 and criticisms about the quality and usability of
3125 @c ---------------------------------------------------------------------
3127 @node Headings in ms, Highlighting in ms, Paragraphs in ms, ms Body Text
3128 @subsubsection Headings
3129 @cindex @code{ms} macros, headings
3131 Use headings to create a hierarchical structure for your document.
3132 The @file{ms} macros print headings in @strong{bold},
3133 using the same font family and point size as the body text.
3135 The following describes the heading macros:
3137 @DefmacList {NH, @Var{curr-level}, ms}
3138 @DefmacListEnd {NH, @t{S} @Var{level0} @dots{}, ms}
3140 The argument is either a numeric argument to indicate the
3141 level of the heading, or the letter@tie{}@code{S} followed by numeric
3142 arguments to set the heading level explicitly.
3144 If you specify heading levels out of sequence, such as invoking
3145 @samp{.NH 3} after @samp{.NH 1}, @code{groff}
3146 prints a warning on standard error.
3150 Unnumbered subheading.
3153 @c ---------------------------------------------------------------------
3155 @node Highlighting in ms, Lists in ms, Headings in ms, ms Body Text
3156 @subsubsection Highlighting
3157 @cindex @code{ms} macros, highlighting
3159 The @file{ms} macros provide a variety of methods to highlight
3162 @Defmac {B, [@Var{txt} [@Var{post} [@Var{pre}]]], ms}
3163 Sets its first argument in @strong{bold type}.
3164 If you specify a second argument, @code{groff} prints it in the
3165 previous font after the bold text, with no intervening space
3166 (this allows you to set punctuation after the highlighted text
3167 without highlighting the punctuation).
3168 Similarly, it prints the third argument (if any) in the previous
3169 font @strong{before} the first argument.
3176 prints (@strong{foo}).
3178 If you give this macro no arguments, @code{groff}
3179 prints all text following in bold until
3180 the next highlighting, paragraph, or heading macro.
3183 @Defmac {R, [@Var{txt} [@Var{post} [@Var{pre}]]], ms}
3184 Sets its first argument in roman (or regular) type.
3185 It operates similarly to the @code{B}@tie{}macro otherwise.
3188 @Defmac {I, [@Var{txt} [@Var{post} [@Var{pre}]]], ms}
3189 Sets its first argument in @emph{italic type}.
3190 It operates similarly to the @code{B}@tie{}macro otherwise.
3193 @Defmac {CW, [@Var{txt} [@Var{post} [@Var{pre}]]], ms}
3194 Sets its first argument in a @code{constant width face}.
3195 It operates similarly to the @code{B}@tie{}macro otherwise.
3198 @Defmac {BI, [@Var{txt} [@Var{post} [@Var{pre}]]], ms}
3199 Sets its first argument in bold italic type.
3200 It operates similarly to the @code{B}@tie{}macro otherwise.
3203 @Defmac {BX, [@Var{txt}], ms}
3204 Prints its argument and draws a box around it.
3205 If you want to box a string that contains spaces,
3206 use a digit-width space (@code{\0}).
3209 @Defmac {UL, [@Var{txt} [@Var{post}]], ms}
3210 Prints its first argument with an underline.
3211 If you specify a second argument, @code{groff}
3212 prints it in the previous font after
3213 the underlined text, with no intervening space.
3217 Prints all text following in larger type
3218 (two points larger than the current point size) until
3219 the next font size, highlighting, paragraph, or heading macro.
3220 You can specify this macro multiple times
3221 to enlarge the point size as needed.
3225 Prints all text following in smaller type
3226 (two points smaller than the current point size) until
3227 the next type size, highlighting, paragraph, or heading macro.
3228 You can specify this macro multiple times
3229 to reduce the point size as needed.
3233 Prints all text following in the normal point size
3234 (that is, the value of the @code{PS} register).
3237 @c ---------------------------------------------------------------------
3239 @node Lists in ms, Indents in ms, Highlighting in ms, ms Body Text
3240 @subsubsection Lists
3241 @cindex @code{ms} macros, lists
3243 The @code{.IP} macro handles duties for all lists.
3245 @Defmac {IP, [@Var{marker} [@Var{width}]], ms}
3246 The @var{marker} is usually a bullet glyph (@code{\[bu]})
3247 for unordered lists, a number (or auto-incrementing number
3248 register) for numbered lists, or a word or phrase for indented
3249 (glossary-style) lists.
3251 The @var{width} specifies the indent for the body of each list item;
3252 its default unit is @samp{n}.
3253 Once specified, the indent remains the same for all
3254 list items in the document until specified again.
3257 The following is an example of a bulleted list.
3258 @cindex example markup, bulleted list [@code{ms}]
3259 @cindex bulleted list, example markup [@code{ms}]
3285 The following is an example of a numbered list.
3286 @cindex example markup, numbered list [@code{ms}]
3287 @cindex numbered list, example markup [@code{ms}]
3312 Note the use of the auto-incrementing number
3313 register in this example.
3316 The following is an example of a glossary-style list.
3317 @cindex example markup, glossary-style list [@code{ms}]
3318 @cindex glossary-style list, example markup [@code{ms}]
3321 A glossary-style list:
3323 Two or more attorneys.
3325 Firearms, preferably
3335 A glossary-style list:
3338 Two or more attorneys.
3340 guns Firearms, preferably large-caliber.
3343 Gotta pay for those lawyers and guns!
3346 In the last example, the @code{IP} macro places the definition
3347 on the same line as the term if it has enough space; otherwise,
3348 it breaks to the next line and starts the definition below the
3350 This may or may not be the effect you want, especially if some
3351 of the definitions break and some do not.
3352 The following examples show two possible ways to force a break.
3354 The first workaround uses the @code{br}
3355 request to force a break after printing the term or label.
3359 A glossary-style list:
3361 Two or more attorneys.
3364 Firearms, preferably large-caliber.
3366 Gotta pay for those lawyers and guns!
3371 The second workaround uses the @code{\p} escape to force the break.
3372 Note the space following the escape; this is important.
3373 If you omit the space, @code{groff} prints the first word on
3374 the same line as the term or label (if it fits) @strong{then}
3379 A glossary-style list:
3381 Two or more attorneys.
3383 \p Firearms, preferably large-caliber.
3385 Gotta pay for those lawyers and guns!
3390 To set nested lists, use the @code{RS} and @code{RE} macros.
3391 @xref{Indents in ms}, for more information.
3392 @cindex @code{ms} macros, nested lists
3393 @cindex nested lists [@code{ms}]
3428 @c ---------------------------------------------------------------------
3430 @node Indents in ms, Tabstops in ms, Lists in ms, ms Body Text
3431 @subsubsection Indents
3434 you may need to indent a section of text
3435 while still wrapping and filling.
3437 for an example of nested lists.
3439 @DefmacList {RS, , ms}
3440 @DefmacListEnd {RE, , ms}
3441 These macros begin and end an indented section.
3442 The @code{PI} register controls the amount of indent,
3443 allowing the indented text to line up under hanging
3444 and indented paragraphs.
3447 @xref{ms Displays and Keeps},
3448 for macros to indent and turn off filling.
3450 @c ---------------------------------------------------------------------
3452 @node Tabstops in ms, ms Displays and Keeps, Indents in ms, ms Body Text
3453 @subsubsection Tab Stops
3455 Use the @code{ta} request to define tab stops as needed.
3456 @xref{Tabs and Fields}.
3459 Use this macro to reset the tab stops to the default for @file{ms}
3461 You can redefine the @code{TA} macro to create a different set
3462 of default tab stops.
3465 @c ---------------------------------------------------------------------
3467 @node ms Displays and Keeps, ms Insertions, Tabstops in ms, ms Body Text
3468 @subsubsection Displays and keeps
3469 @cindex @code{ms} macros, displays
3470 @cindex @code{ms} macros, keeps
3471 @cindex keeps [@code{ms}]
3472 @cindex displays [@code{ms}]
3474 Use displays to show text-based examples or figures
3475 (such as code listings).
3477 Displays turn off filling, so lines of code are displayed
3478 as-is without inserting @code{br} requests in between each line.
3479 Displays can be @dfn{kept} on a single page, or allowed
3480 to break across pages.
3482 @DefmacList {DS, @t{L}, ms}
3483 @DefmacItem {LD, , ms}
3484 @DefmacListEnd {DE, , ms}
3485 Left-justified display.
3486 The @samp{.DS L} call generates a page break, if necessary,
3487 to keep the entire display on one page.
3488 The @code{LD} macro allows the display to break across pages.
3489 The @code{DE} macro ends the display.
3492 @DefmacList {DS, @t{I}, ms}
3493 @DefmacItem {ID, , ms}
3494 @DefmacListEnd {DE, , ms}
3495 Indents the display as defined by the @code{DI} register.
3496 The @samp{.DS I} call generates a page break, if necessary,
3497 to keep the entire display on one page.
3498 The @code{ID} macro allows the display to break across pages.
3499 The @code{DE} macro ends the display.
3502 @DefmacList {DS, @t{B}, ms}
3503 @DefmacItem {BD, , ms}
3504 @DefmacListEnd {DE, , ms}
3505 Sets a block-centered display: the entire display is left-justified,
3506 but indented so that the longest line in the display is centered
3508 The @samp{.DS B} call generates a page break, if necessary,
3509 to keep the entire display on one page.
3510 The @code{BD} macro allows the display to break across pages.
3511 The @code{DE} macro ends the display.
3514 @DefmacList {DS, @t{C}, ms}
3515 @DefmacItem {CD, , ms}
3516 @DefmacListEnd {DE, , ms}
3517 Sets a centered display: each line in the display is centered.
3518 The @samp{.DS C} call generates a page break, if necessary,
3519 to keep the entire display on one page.
3520 The @code{CD} macro allows the display to break across pages.
3521 The @code{DE} macro ends the display.
3524 @DefmacList {DS, @t{R}, ms}
3525 @DefmacItem {RD, , ms}
3526 @DefmacListEnd {DE, , ms}
3527 Right-justifies each line in the display.
3528 The @samp{.DS R} call generates a page break, if necessary,
3529 to keep the entire display on one page.
3530 The @code{RD} macro allows the display to break across pages.
3531 The @code{DE} macro ends the display.
3534 @DefmacList {Ds, , ms}
3535 @DefmacListEnd {De, , ms}
3536 These two macros are aliases for @code{DS} and @code{DE}, respectively.
3540 On occasion, you may want to @dfn{keep} other text together on a page.
3541 For example, you may want to keep two paragraphs together, or
3542 a paragraph that refers to a table (or list, or other item)
3543 immediately following.
3544 The @file{ms} macros provide the @code{KS} and @code{KE}
3545 macros for this purpose.
3547 @DefmacList {KS, , ms}
3548 @DefmacListEnd {KE, , ms}
3549 The @code{KS} macro begins a block of text to be kept on a
3550 single page, and the @code{KE} macro ends the block.
3553 @DefmacList {KF, , ms}
3554 @DefmacListEnd {KE, , ms}
3555 Specifies a @dfn{floating keep};
3556 if the keep cannot fit on the current page, @code{groff}
3557 holds the contents of the keep and allows text following
3558 the keep (in the source file) to fill in the remainder of
3560 When the page breaks, whether by an explicit @code{bp}
3561 request or by reaching the end of the page, @code{groff}
3562 prints the floating keep at the top of the new page.
3563 This is useful for printing large graphics or tables
3564 that do not need to appear exactly where specified.
3567 You can also use the @code{ne} request to force a page break if
3568 there is not enough vertical space remaining on the page.
3571 Use the following macros to draw a box around a section of
3572 text (such as a display).
3574 @DefmacList {B1, , ms}
3575 @DefmacListEnd {B2, , ms}
3576 Marks the beginning and ending of text that is to have a
3577 box drawn around it.
3578 The @code{B1} macro begins the box; the @code{B2} macro ends it.
3579 Text in the box is automatically placed in a diversion (keep).
3582 @c ---------------------------------------------------------------------
3584 @node ms Insertions, Example multi-page table, ms Displays and Keeps, ms Body Text
3585 @subsubsection Tables, figures, equations, and references
3586 @cindex @code{ms} macros, tables
3587 @cindex @code{ms} macros, figures
3588 @cindex @code{ms} macros, equations
3589 @cindex @code{ms} macros, references
3590 @cindex tables [@code{ms}]
3591 @cindex figures [@code{ms}]
3592 @cindex equations [@code{ms}]
3593 @cindex references [@code{ms}]
3595 The @file{ms} macros support the standard
3596 @code{groff} preprocessors:
3597 @code{tbl}, @code{pic}, @code{eqn}, and @code{refer}.
3602 You mark text meant for preprocessors by enclosing it
3603 in pairs of tags as follows.
3605 @DefmacList {TS, [@code{H}], ms}
3606 @DefmacListEnd {TE, , ms}
3607 Denotes a table, to be processed by the @code{tbl} preprocessor.
3608 The optional argument@tie{}@code{H} to @code{TS} instructs @code{groff}
3609 to create a running header with the information
3610 up to the @code{TH} macro.
3611 @code{groff} prints the header at the beginning of the
3612 table; if the table runs onto another page, @code{groff}
3613 prints the header on the next page as well.
3616 @DefmacList {PS, , ms}
3617 @DefmacListEnd {PE, , ms}
3618 Denotes a graphic, to be processed by the @code{pic} preprocessor.
3619 You can create a @code{pic} file by hand, using the @acronym{AT&T}
3620 @code{pic} manual available on the Web as a reference, or by using
3621 a graphics program such as @code{xfig}.
3624 @DefmacList {EQ, [@Var{align}], ms}
3625 @DefmacListEnd {EN, , ms}
3626 Denotes an equation, to be processed by the @code{eqn} preprocessor.
3627 The optional @var{align} argument can be @code{C}, @code{L},
3628 or@tie{}@code{I} to center (the default), left-justify, or indent the
3632 @DefmacList {[, , ms}
3633 @DefmacListEnd {], , ms}
3634 Denotes a reference, to be processed by the @code{refer} preprocessor.
3635 The @acronym{GNU} @cite{refer(1)} man page provides a comprehensive
3636 reference to the preprocessor and the format of the bibliographic
3641 * Example multi-page table::
3644 @c ---------------------------------------------------------------------
3646 @node Example multi-page table, ms Footnotes, ms Insertions, ms Body Text
3647 @subsubsection An example multi-page table
3648 @cindex example markup, multi-page table [@code{ms}]
3649 @cindex multi-page table, example markup [@code{ms}]
3651 The following is an example of how to set up a
3652 table that may print across two or more pages.
3659 Text ...of heading...
3664 ... the rest of the table follows...
3670 @c ---------------------------------------------------------------------
3672 @node ms Footnotes, , Example multi-page table, ms Body Text
3673 @subsubsection Footnotes
3674 @cindex @code{ms} macros, footnotes
3675 @cindex footnotes [@code{ms}]
3677 The @file{ms} macro package has a flexible footnote system.
3678 You can specify either numbered footnotes or symbolic footnotes
3679 (that is, using a marker such as a dagger symbol).
3682 Specifies the location of a numbered footnote marker in the text.
3685 @DefmacList {FS, , ms}
3686 @DefmacListEnd {FE, , ms}
3687 Specifies the text of the footnote.
3688 The default action is to create a numbered footnote;
3689 you can create a symbolic footnote by specifying
3691 (such as @code{\[dg]} for the dagger glyph)
3692 in the body text and as an argument to the @code{FS} macro,
3693 followed by the text of the footnote
3694 and the @code{FE} macro.
3697 You can control how @code{groff}
3698 prints footnote numbers by changing the value of the
3699 @code{FF} register. @xref{ms Document Control Registers}.
3701 @c ---------------------------------------------------------------------
3703 @node ms Page Layout, Differences from AT&T ms, ms Body Text, ms
3704 @subsection Page layout
3705 @cindex @code{ms} macros, page layout
3706 @cindex page layout [@code{ms}]
3708 The default output from the @file{ms}
3709 macros provides a minimalist page layout:
3710 it prints a single column, with the page number centered at the top
3712 It prints no footers.
3714 You can change the layout by setting
3715 the proper number registers and strings.
3718 * ms Headers and Footers::
3720 * ms Multiple Columns::
3722 * ms Strings and Special Characters::
3725 @c ---------------------------------------------------------------------
3727 @node ms Headers and Footers, ms Margins, ms Page Layout, ms Page Layout
3728 @subsubsection Headers and footers
3729 @cindex @code{ms} macros, headers
3730 @cindex @code{ms} macros, footers
3731 @cindex headers [@code{ms}]
3732 @cindex footers [@code{ms}]
3734 For documents that do not distinguish between odd and even pages,
3735 set the following strings:
3737 @DefstrList {LH, ms}
3738 @DefstrItem {CH, ms}
3739 @DefstrListEnd {RH, ms}
3740 Sets the left, center, and right headers.
3743 @DefstrList {LF, ms}
3744 @DefstrItem {CF, ms}
3745 @DefstrListEnd {RF, ms}
3746 Sets the left, center, and right footers.
3750 For documents that need different information printed in the
3751 even and odd pages, use the following macros:
3753 @DefmacList {OH, @t{'}@Var{left}@t{'}@Var{center}@t{'}@Var{right}@t{'}, ms}
3754 @DefmacItem {EH, @t{'}@Var{left}@t{'}@Var{center}@t{'}@Var{right}@t{'}, ms}
3755 @DefmacItem {OF, @t{'}@Var{left}@t{'}@Var{center}@t{'}@Var{right}@t{'}, ms}
3756 @DefmacListEnd {EF, @t{'}@Var{left}@t{'}@Var{center}@t{'}@Var{right}@t{'}, ms}
3757 The @code{OH} and @code{EH} macros define headers for the odd and even pages;
3758 the @code{OF} and @code{EF} macros define footers for the odd and even pages.
3759 This is more flexible than defining the individual strings.
3761 You can replace the quote (@code{'}) marks with any character not
3762 appearing in the header or footer text.
3765 @c ---------------------------------------------------------------------
3767 @node ms Margins, ms Multiple Columns, ms Headers and Footers, ms Page Layout
3768 @subsubsection Margins
3769 @cindex @code{ms} macros, margins
3771 You control margins using a set of number registers.
3772 @xref{ms Document Control Registers}, for details.
3774 @c ---------------------------------------------------------------------
3776 @node ms Multiple Columns, ms TOC, ms Margins, ms Page Layout
3777 @subsubsection Multiple columns
3778 @cindex @code{ms} macros, multiple columns
3779 @cindex multiple columns [@code{ms}]
3781 The @file{ms} macros can set text in as many columns as will
3782 reasonably fit on the page.
3783 The following macros are available;
3784 all of them force a page break if a multi-column mode is already set.
3785 However, if the current mode is single-column, starting a multi-column
3786 mode does @strong{not} force a page break.
3796 @Defmac {MC, [@Var{width} [@Var{gutter}]], ms}
3798 If you specify no arguments, it is equivalent to the
3800 Otherwise, @var{width} is the width of each column and
3801 @var{gutter} is the space between columns.
3802 The @code{MINGW} number register controls the default gutter width.
3805 @c ---------------------------------------------------------------------
3807 @node ms TOC, ms Strings and Special Characters, ms Multiple Columns, ms Page Layout
3808 @subsubsection Creating a table of contents
3809 @cindex @code{ms} macros, creating table of contents
3810 @cindex table of contents, creating [@code{ms}]
3812 The facilities in the @file{ms} macro package for creating
3813 a table of contents are semi-automated at best.
3814 Assuming that you want the table of contents to consist of
3815 the document's headings, you need to repeat those headings
3816 wrapped in @code{XS} and @code{XE} macros.
3818 @DefmacList {XS, [@Var{page}], ms}
3819 @DefmacItem {XA, [@Var{page}], ms}
3820 @DefmacListEnd {XE, , ms}
3821 These macros define a table of contents
3822 or an individual entry in the table of contents,
3823 depending on their use.
3824 The macros are very simple; they cannot indent a heading based on its level.
3825 The easiest way to work around this is to add tabs
3826 to the table of contents string.
3827 The following is an example:
3849 You can manually create a table of contents
3850 by beginning with the @code{XS} macro for the first entry,
3851 specifying the page number for that entry as the argument to @code{XS}.
3852 Add subsequent entries using the @code{XA} macro,
3853 specifying the page number for that entry as the argument to @code{XA}.
3854 The following is an example:
3861 A Brief History of the Universe
3863 Details of Galactic Formation
3870 @Defmac {TC, [@code{no}], ms}
3871 Prints the table of contents on a new page,
3872 setting the page number to@tie{}@strong{i} (Roman numeral one).
3873 You should usually place this macro at the end of the
3874 file, since @code{groff} is a single-pass formatter and
3875 can only print what has been collected up to the point
3876 that the @code{TC} macro appears.
3878 The optional argument @code{no} suppresses printing
3879 the title specified by the string register @code{TOC}.
3882 @Defmac{PX, [@code{no}], ms}
3883 Prints the table of contents on a new page,
3884 using the current page numbering sequence.
3885 Use this macro to print a manually-generated table of contents
3886 at the beginning of your document.
3888 The optional argument @code{no} suppresses printing
3889 the title specified by the string register @code{TOC}.
3892 The @cite{Groff and Friends HOWTO}
3893 includes a @code{sed} script that automatically inserts
3894 @code{XS} and @code{XE} macro entries after each heading in a document.
3896 Altering the @code{NH} macro to automatically build the table
3897 of contents is perhaps initially more difficult, but would save
3898 a great deal of time in the long run if you use @file{ms} regularly.
3900 @c ---------------------------------------------------------------------
3902 @node ms Strings and Special Characters, , ms TOC, ms Page Layout
3903 @subsubsection Strings and Special Characters
3904 @cindex @code{ms} macros, strings
3905 @cindex @code{ms} macros, special characters
3906 @cindex @code{ms} macros, accent marks
3907 @cindex accent marks [@code{ms}]
3908 @cindex special characters [@code{ms}]
3909 @cindex strings [@code{ms}]
3911 The @file{ms} macros provide the following predefined strings.
3912 You can change the string definitions to help in creating
3913 documents in languages other than English.
3915 @Defstr {REFERENCES, ms}
3916 Contains the string printed at the beginning of the
3917 references (bibliography) page.
3918 The default is @samp{References}.
3921 @Defstr {ABSTRACT, ms}
3922 Contains the string printed at the beginning of the abstract.
3923 The default is @samp{ABSTRACT}.
3927 Contains the string printed at the beginning of the table of contents.
3930 @DefstrList {MONTH1, ms}
3931 @DefstrItem {MONTH2, ms}
3932 @DefstrItem {MONTH3, ms}
3933 @DefstrItem {MONTH4, ms}
3934 @DefstrItem {MONTH5, ms}
3935 @DefstrItem {MONTH6, ms}
3936 @DefstrItem {MONTH7, ms}
3937 @DefstrItem {MONTH8, ms}
3938 @DefstrItem {MONTH9, ms}
3939 @DefstrItem {MONTH10, ms}
3940 @DefstrItem {MONTH11, ms}
3941 @DefstrListEnd {MONTH12, ms}
3942 Prints the full name of the month in dates.
3943 The default is @samp{January}, @samp{February}, etc.
3946 The following special characters are available@footnote{For an
3947 explanation what special characters are see @ref{Special Characters}.}:
3953 @DefstrList {*Q, ms}
3954 @DefstrListEnd {*U, ms}
3955 Prints typographer's quotes in troff,
3956 plain quotes in nroff.
3957 @code{*Q} is the left quote and @code{*U} is the right quote.
3960 Improved accent marks are available in the @file{ms} macros.
3963 Specify this macro at the beginning of your document
3964 to enable extended accent marks and special characters.
3965 This is a Berkeley extension.
3967 To use the accent marks, place them @strong{after}
3968 the character being accented.
3971 The following accent marks are available
3972 after invoking the @code{AM} macro:
3994 @deffn String @t{\*[:]}
3996 @stindex : @r{[}ms@r{]}
3999 @stindex \*[@r{<colon>}] @r{[}ms@r{]}
4020 The following are standalone characters
4021 available after invoking the @code{AM} macro:
4024 Upside-down question mark.
4028 Upside-down exclamation point.
4032 German @ss{} ligature.
4060 Lowercase @ae{} ligature.
4064 Uppercase @AE{} ligature.
4067 @c ---------------------------------------------------------------------
4069 @node Differences from AT&T ms, , ms Page Layout, ms
4070 @subsection Differences from @acronym{AT&T} @file{ms}
4071 @cindex @code{ms} macros, differences from @acronym{AT&T}
4072 @cindex @acronym{AT&T} @code{troff}, @code{ms} macro package differences
4074 This section lists the (minor) differences between the
4075 @code{groff -ms} macros and @acronym{AT&T}
4076 @code{troff -ms} macros.
4079 * Missing ms Macros::
4080 * Additional ms Macros::
4083 @c ---------------------------------------------------------------------
4085 @node Missing ms Macros, Additional ms Macros, Differences from AT&T ms, Differences from AT&T ms
4086 @subsubsection @code{troff} macros not appearing in @code{groff}
4088 Macros missing from @code{groff -ms}
4089 are cover page macros specific to Bell Labs.
4090 The macros known to be missing are:
4094 Technical memorandum; a cover sheet style
4097 Internal memorandum; a cover sheet style
4100 Memo for record; a cover sheet style
4103 Memo for file; a cover sheet style
4106 Engineer's notes; a cover sheet style
4109 Computing Science Tech Report; a cover sheet style
4115 Cover sheet information
4121 @c ---------------------------------------------------------------------
4123 @node Additional ms Macros, , Missing ms Macros, Differences from AT&T ms
4124 @subsubsection @code{groff} macros not appearing in @acronym{AT&T} @code{troff}
4126 The @code{groff -ms} macros have a few minor extensions
4127 compared to the @acronym{AT&T} @code{troff -ms} macros.
4130 Improved accent marks.
4131 @xref{ms Strings and Special Characters}, for details.
4134 @Defmac {DS, @t{I}, ms}
4136 The default behavior of @acronym{AT&T} @code{troff -ms}
4137 was to indent; the @code{groff} default prints displays
4138 flush left with the body text.
4142 Print text in @code{constant width} (Courier) font.
4146 Indexing term (printed on standard error).
4147 You can write a script to capture and process an index
4148 generated in this manner.
4152 The following additional number registers
4153 appear in @code{groff -ms}:
4155 @Defmpreg {MINGW, ms}
4156 Specifies a minimum space
4157 between columns (for multi-column output); this takes the
4158 place of the @code{GW} register that was documented but apparently
4159 not implemented in @acronym{AT&T} @code{troff}.
4163 Several new string registers are available as well.
4164 You can change these to handle (for example) the local language.
4165 @xref{ms Strings and Special Characters}, for details.
4168 @c =====================================================================
4170 @node me, mm, ms, Macro Packages
4172 @cindex @code{me} macro package
4174 @c XXX documentation
4175 @c XXX this is a placeholder until we get stuff knocked into shape
4176 See the @file{meintro.me} and @file{meref.me} documents in
4177 groff's @file{doc} directory.
4180 @c =====================================================================
4182 @node mm, , me, Macro Packages
4184 @cindex @code{mm} macro package
4186 @c XXX documentation
4187 @c XXX this is a placeholder until we get stuff knocked into shape
4188 See the @cite{groff_mm(7)} man page (type @command{man groff_mm} at
4192 @c =====================================================================
4193 @c =====================================================================
4195 @node gtroff Reference, Preprocessors, Macro Packages, Top
4196 @chapter @code{gtroff} Reference
4197 @cindex reference, @code{gtroff}
4198 @cindex @code{gtroff}, reference
4200 This chapter covers @strong{all} of the facilities of @code{gtroff}.
4201 Users of macro packages may skip it if not interested in details.
4209 * Embedded Commands::
4211 * Manipulating Filling and Adjusting::
4212 * Manipulating Hyphenation::
4213 * Manipulating Spacing::
4215 * Character Translations::
4216 * Troff and Nroff Mode::
4221 * Fonts and Symbols::
4224 * Conditionals and Loops::
4227 * Drawing Requests::
4231 * Suppressing output::
4234 * Postprocessor Access::
4236 * Gtroff Internals::
4238 * Implementation Differences::
4242 @c =====================================================================
4244 @node Text, Measurements, gtroff Reference, gtroff Reference
4246 @cindex text, @code{gtroff} processing
4248 @code{gtroff} input files contain text with control commands
4249 interspersed throughout. But, even without control codes, @code{gtroff}
4250 still does several things with the input text:
4254 filling and adjusting
4257 adding additional space after sentences
4263 inserting implicit line breaks
4267 * Filling and Adjusting::
4271 * Implicit Line Breaks::
4272 * Input Conventions::
4276 @c ---------------------------------------------------------------------
4278 @node Filling and Adjusting, Hyphenation, Text, Text
4279 @subsection Filling and Adjusting
4283 When @code{gtroff} reads text, it collects words from the input and fits
4284 as many of them together on one output line as it can. This is known as
4287 @cindex leading spaces
4288 @cindex spaces, leading and trailing
4289 @cindex extra spaces
4290 @cindex trailing spaces
4291 Once @code{gtroff} has a @dfn{filled} line, it tries to @dfn{adjust}
4292 it. This means it widens the spacing between words until the text
4293 reaches the right margin (in the default adjustment mode). Extra spaces
4294 between words are preserved, but spaces at the end of lines are ignored.
4295 Spaces at the front of a line cause a @dfn{break} (breaks are
4296 explained in @ref{Implicit Line Breaks}).
4298 @xref{Manipulating Filling and Adjusting}.
4300 @c ---------------------------------------------------------------------
4302 @node Hyphenation, Sentences, Filling and Adjusting, Text
4303 @subsection Hyphenation
4306 Since the odds are not great for finding a set of words, for every
4307 output line, which fit nicely on a line without inserting excessive
4308 amounts of space between words, @code{gtroff} hyphenates words so
4309 that it can justify lines without inserting too much space between
4310 words. It uses an internal hyphenation algorithm (a simplified version
4311 of the algorithm used within @TeX{}) to indicate which words can be
4312 hyphenated and how to do so. When a word is hyphenated, the first part
4313 of the word is added to the current filled line being output (with
4314 an attached hyphen), and the other portion is added to the next
4317 @xref{Manipulating Hyphenation}.
4319 @c ---------------------------------------------------------------------
4321 @node Sentences, Tab Stops, Hyphenation, Text
4322 @subsection Sentences
4325 Although it is often debated, some typesetting rules say there should be
4326 different amounts of space after various punctuation marks. For
4327 example, the @cite{Chicago typsetting manual} says that a period at the
4328 end of a sentence should have twice as much space following it as would
4329 a comma or a period as part of an abbreviation.
4331 @c XXX exact citation of Chicago manual
4333 @cindex sentence space
4334 @cindex space between sentences
4335 @cindex french-spacing
4336 @code{gtroff} does this by flagging certain characters (normally
4337 @samp{!}, @samp{?}, and @samp{.}) as @dfn{end-of-sentence} characters.
4338 When @code{gtroff} encounters one of these characters at the end of a
4339 line, it appends a normal space followed by a @dfn{sentence space} in
4340 the formatted output. (This justifies one of the conventions mentioned
4341 in @ref{Input Conventions}.)
4343 @cindex transparent characters
4344 @cindex character, transparent
4345 @cindex @code{dg} glyph, at end of sentence
4346 @cindex @code{rq} glyph, at end of sentence
4347 @cindex @code{"}, at end of sentence
4348 @cindex @code{'}, at end of sentence
4349 @cindex @code{)}, at end of sentence
4350 @cindex @code{]}, at end of sentence
4351 @cindex @code{*}, at end of sentence
4352 In addition, the following characters and symbols are treated
4353 transparently while handling end-of-sentence characters: @samp{"},
4354 @samp{'}, @samp{)}, @samp{]}, @samp{*}, @code{\[dg]}, and @code{\[rq]}.
4356 See the @code{cflags} request in @ref{Using Symbols}, for more details.
4358 @cindex @code{\&}, at end of sentence
4359 To prevent the insertion of extra space after an end-of-sentence
4360 character (at the end of a line), append @code{\&}.
4362 @c ---------------------------------------------------------------------
4364 @node Tab Stops, Implicit Line Breaks, Sentences, Text
4365 @subsection Tab Stops
4367 @cindex stops, tabulator
4368 @cindex tab character
4369 @cindex character, tabulator
4371 @cindex @acronym{EBCDIC} encoding
4372 @cindex encoding, @acronym{EBCDIC}
4373 @code{gtroff} translates @dfn{tabulator characters}, also called
4374 @dfn{tabs} (normally code point @acronym{ASCII} @code{0x09} or
4375 @acronym{EBCDIC} @code{0x05}), in the input into movements to the next
4376 tabulator stop. These tab stops are initially located every half inch
4377 across the page. Using this, simple tables can be made easily.
4378 However, it can often be deceptive as the appearance (and width) of the
4379 text on a terminal and the results from @code{gtroff} can vary greatly.
4381 Also, a possible sticking point is that lines beginning with tab
4382 characters are still filled, again producing unexpected results.
4383 For example, the following input
4385 @multitable {12345678} {12345678} {12345678} {12345678}
4387 @tab 1 @tab 2 @tab 3
4395 @multitable {12345678} {12345678} {12345678} {12345678} {12345678} {12345678} {12345678}
4397 @tab 1 @tab 2 @tab 3 @tab @tab 4 @tab 5
4400 @xref{Tabs and Fields}.
4402 @c ---------------------------------------------------------------------
4404 @node Implicit Line Breaks, Input Conventions, Tab Stops, Text
4405 @subsection Implicit Line Breaks
4406 @cindex implicit line breaks
4407 @cindex implicit breaks of lines
4408 @cindex line, implicit breaks
4409 @cindex break, implicit
4412 An important concept in @code{gtroff} is the @dfn{break}. When a break
4413 occurs, @code{gtroff} outputs the partially filled line
4414 (unjustified), and resumes collecting and filling text on the next output
4420 @cindex blank line macro (@code{blm})
4421 There are several ways to cause a break in @code{gtroff}. A blank
4422 line not only causes a break, but it also outputs a one-line vertical
4423 space (effectively a blank line). Note that this behaviour can be
4424 modified with the blank line macro request @code{blm}.
4425 @xref{Blank Line Traps}.
4429 A line that begins with a space causes a break and the space is
4430 output at the beginning of the next line. Note that this space isn't
4431 adjusted, even in fill mode.
4433 The end of file also causes a break -- otherwise the last line of
4434 the document may vanish!
4436 Certain requests also cause breaks, implicitly or explicitly. This is
4437 discussed in @ref{Manipulating Filling and Adjusting}.
4439 @c ---------------------------------------------------------------------
4441 @node Input Conventions, Input Encodings, Implicit Line Breaks, Text
4442 @subsection Input Conventions
4443 @cindex input conventions
4444 @cindex conventions for input
4446 Since @code{gtroff} does filling automatically, it is traditional in
4447 @code{groff} not to try and type things in as nicely formatted
4448 paragraphs. These are some conventions commonly used when typing
4453 Break lines after punctuation, particularly at the end of a sentence
4454 and in other logical places. Keep separate phrases on lines by
4455 themselves, as entire phrases are often added or deleted when editing.
4458 Try to keep lines less than 40-60@tie{}characters, to allow space for
4459 inserting more text.
4462 Do not try to do any formatting in a @acronym{WYSIWYG} manner (i.e.,
4463 don't try using spaces to get proper indentation).
4466 @c ---------------------------------------------------------------------
4468 @node Input Encodings, , Input Conventions, Text
4469 @subsection Input Encodings
4471 Currently, the following input encodings are available.
4475 @cindex encoding, input, @acronym{EBCDIC}
4476 @cindex @acronym{EBCDIC}, input encoding
4477 @cindex input encoding, @acronym{EBCDIC}
4478 @cindex encoding, input, cp1047
4479 @cindex cp1047, input encoding
4480 @cindex input encoding, cp1047
4481 @cindex IBM cp1047 input encoding
4483 This input encoding works only on @acronym{EBCDIC} platforms (and vice
4484 versa, the other input encodings don't work with @acronym{EBCDIC}); the
4485 file @file{cp1047.tmac} is by default loaded at start-up.
4488 @cindex encoding, input, @w{latin-1} (ISO @w{8859-1})
4489 @cindex @w{latin-1} (ISO @w{8859-1}), input encoding
4490 @cindex ISO @w{8859-1} (@w{latin-1}), input encoding
4491 @cindex input encoding, @w{latin-1} (ISO @w{8859-1})
4493 This is the default input encoding on non-@acronym{EBCDIC} platforms;
4494 the file @file{latin1.tmac} is loaded at start-up.
4497 @cindex encoding, input, @w{latin-2} (ISO @w{8859-2})
4498 @cindex @w{latin-2} (ISO @w{8859-2}), input encoding
4499 @cindex ISO @w{8859-2} (@w{latin-2}), input encoding
4500 @cindex input encoding, @w{latin-2} (ISO @w{8859-2})
4502 To use this encoding, either say @w{@samp{.mso latin2.tmac}} at the very
4503 beginning of your document or use @samp{-mlatin2} as a command line
4504 argument for @code{groff}.
4506 @item latin-9 (latin-0)
4507 @cindex encoding, input, @w{latin-9} (@w{latin-0}, ISO @w{8859-15})
4508 @cindex @w{latin-9} (@w{latin-0}, ISO @w{8859-15}), input encoding
4509 @cindex ISO @w{8859-15} (@w{latin-9}, @w{latin-0}), input encoding
4510 @cindex input encoding, @w{latin-9} (@w{latin-9}, ISO @w{8859-15})
4512 This encoding is intended (at least in Europe) to replace @w{latin-1}
4513 encoding. The main difference to @w{latin-1} is that @w{latin-9}
4514 contains the Euro character. To use this encoding, either say
4515 @w{@samp{.mso latin9.tmac}} at the very beginning of your document or
4516 use @samp{-mlatin9} as a command line argument for @code{groff}.
4519 Note that it can happen that some input encoding characters are not
4520 available for a particular output device. For example, saying
4523 groff -Tlatin1 -mlatin9 ...
4527 will fail if you use the Euro character in the input. Usually, this
4528 limitation is present only for devices which have a limited set of
4529 output glyphs (e.g.@: @option{-Tascii} and @option{-Tlatin1}); for other
4530 devices it is usually sufficient to install proper fonts which contain
4531 the necessary glyphs.
4533 @pindex freeeuro.pfa
4535 Due to the importance of the Euro glyph in Europe, the groff package now
4536 comes with a @sc{PostScript} font called @file{freeeuro.pfa} which
4537 provides various glyph shapes for the Euro. With other words,
4538 @w{latin-9} encoding is supported for the @option{-Tps} device out of
4539 the box (@w{latin-2} isn't).
4541 By its very nature, @option{-Tutf8} supports all input encodings;
4542 @option{-Tdvi} has support for both @w{latin-2} and @w{latin-9} if the
4543 command line @option{-mec} is used also to load the file @file{ec.tmac}
4544 (which flips to the EC fonts).
4547 @c =====================================================================
4549 @node Measurements, Expressions, Text, gtroff Reference
4550 @section Measurements
4551 @cindex measurements
4553 @cindex units of measurement
4554 @cindex basic unit (@code{u})
4555 @cindex machine unit (@code{u})
4556 @cindex measurement unit
4557 @cindex @code{u} unit
4558 @cindex unit, @code{u}
4559 @code{gtroff} (like many other programs) requires numeric parameters to
4560 specify various measurements. Most numeric parameters@footnote{those
4561 that specify vertical or horizontal motion or a type size} may have a
4562 @dfn{measurement unit} attached. These units are specified as a single
4563 character which immediately follows the number or expression. Each of
4564 these units are understood, by @code{gtroff}, to be a multiple of its
4565 @dfn{basic unit}. So, whenever a different measurement unit is
4566 specified @code{gtroff} converts this into its @dfn{basic units}. This
4567 basic unit, represented by a @samp{u}, is a device dependent measurement
4568 which is quite small, ranging from 1/75@dmn{th} to 1/72000@dmn{th} of an
4569 inch. The values may be given as fractional numbers; however,
4570 fractional basic units are always rounded to integers.
4572 Some of the measurement units are completely independent of any of the
4573 current settings (e.g.@: type size) of @code{gtroff}.
4577 @cindex inch unit (@code{i})
4578 @cindex @code{i} unit
4579 @cindex unit, @code{i}
4580 Inches. An antiquated measurement unit still in use in certain
4581 backwards countries with incredibly low-cost computer equipment. One
4582 inch is equal to@tie{}2.54@dmn{cm}.
4585 @cindex centimeter unit (@code{c})
4586 @cindex @code{c} unit
4587 @cindex unit, @code{c}
4588 Centimeters. One centimeter is equal to@tie{}0.3937@dmn{in}.
4591 @cindex point unit (@code{p})
4592 @cindex @code{p} unit
4593 @cindex unit, @code{p}
4594 Points. This is a typesetter's measurement used for measure type size.
4595 It is 72@tie{}points to an inch.
4598 @cindex pica unit (@code{P})
4599 @cindex @code{P} unit
4600 @cindex unit, @code{P}
4601 Pica. Another typesetting measurement. 6@tie{}Picas to an inch (and
4602 12@tie{}points to a pica).
4606 @cindex @code{s} unit
4607 @cindex unit, @code{s}
4608 @cindex @code{z} unit
4609 @cindex unit, @code{z}
4610 @xref{Fractional Type Sizes}, for a discussion of these units.
4613 @cindex @code{f} unit
4614 @cindex unit, @code{f}
4615 Fractions. Value is 65536.
4616 @xref{Colors}, for usage.
4619 The other measurements understood by @code{gtroff} depend on
4620 settings currently in effect in @code{gtroff}. These are very useful
4621 for specifying measurements which should look proper with any size of
4626 @cindex em unit (@code{m})
4627 @cindex @code{m} unit
4628 @cindex unit, @code{m}
4629 Ems. This unit is equal to the current font size in points. So called
4630 because it is @emph{approximately} the width of the letter@tie{}@samp{m}
4631 in the current font.
4634 @cindex en unit (@code{n})
4635 @cindex @code{n} unit
4636 @cindex unit, @code{n}
4637 Ens. In @code{groff}, this is half of an em.
4640 @cindex vertical space unit (@code{v})
4641 @cindex space, vertical, unit (@code{v})
4642 @cindex @code{v} unit
4643 @cindex unit, @code{v}
4644 Vertical space. This is equivalent to the current line spacing.
4645 @xref{Sizes}, for more information about this.
4648 @cindex @code{M} unit
4649 @cindex unit, @code{M}
4657 @c ---------------------------------------------------------------------
4659 @node Default Units, , Measurements, Measurements
4660 @subsection Default Units
4661 @cindex default units
4662 @cindex units, default
4664 Many requests take a default unit. While this can be helpful at times,
4665 it can cause strange errors in some expressions. For example, the line
4666 length request expects em units. Here are several attempts to get a
4667 line length of 3.5@tie{}inches and their results:
4673 (7 / 2)u @result{} 0i
4675 7i/2u @result{} 3.5i
4679 Everything is converted to basic units first. In the above example it
4680 is assumed that 1@dmn{i} equals@tie{}240@dmn{u}, and 1@dmn{m}
4681 equals@tie{}10@dmn{p} (thus 1@dmn{m} equals@tie{}33@dmn{u}). The value
4682 7@dmn{i}/2 is first handled as 7@dmn{i}/2@dmn{m}, then converted to
4683 1680@dmn{u}/66@dmn{u} which is 25@dmn{u}, and this is approximately
4684 0.1@dmn{i}. As can be seen, a scaling indicator after a closing
4685 parenthesis is simply ignored.
4687 @cindex measurements, specifying safely
4688 Thus, the safest way to specify measurements is to always
4689 attach a scaling indicator. If you want to multiply or divide by a
4690 certain scalar value, use @samp{u} as the unit for that value.
4693 @c =====================================================================
4695 @node Expressions, Identifiers, Measurements, gtroff Reference
4696 @section Expressions
4699 @code{gtroff} has most arithmetic operators common to other languages:
4703 @cindex arithmetic operators
4704 @cindex operators, arithmetic
4710 Arithmetic: @samp{+} (addition), @samp{-} (subtraction), @samp{/}
4711 (division), @samp{*} (multiplication), @samp{%} (modulo).
4713 @code{gtroff} only provides integer arithmetic. The internal type used
4714 for computing results is @samp{int}, which is usually a 32@dmn{bit}
4718 @cindex comparison operators
4719 @cindex operators, comparison
4726 Comparison: @samp{<} (less than), @samp{>} (greater than), @samp{<=}
4727 (less than or equal), @samp{>=} (greater than or equal), @samp{=}
4728 (equal), @samp{==} (the same as @samp{=}).
4731 @cindex logical operators
4732 @cindex operators, logical
4738 @opindex @r{<colon>}
4740 Logical: @samp{&} (logical and), @samp{:} (logical or).
4743 @cindex unary operators
4744 @cindex operators, unary
4748 @cindex @code{if} request, and the @samp{!} operator
4749 @cindex @code{while} request, and the @samp{!} operator
4750 Unary operators: @samp{-} (negating, i.e.@: changing the sign), @samp{+}
4751 (just for completeness; does nothing in expressions), @samp{!} (logical
4752 not; this works only within @code{if} and @code{while} requests). See
4753 below for the use of unary operators in motion requests.
4756 @cindex extremum operators (@code{>?}, @code{<?})
4757 @cindex operators, extremum (@code{>?}, @code{<?})
4760 Extrema: @samp{>?} (maximum), @samp{<?} (minimum).
4767 .nr z (\n[x] >? \n[y])
4771 The register@tie{}@code{z} now contains@tie{}5.
4774 @cindex scaling operator
4775 @cindex operator, scaling
4776 Scaling: @code{(@var{c};@var{e})}. Evaluate@tie{}@var{e} using@tie{}@var{c}
4777 as the default scaling indicator. If @var{c} is missing, ignore scaling
4778 indicators in the evaluation of@tie{}@var{e}.
4782 @cindex order of evaluation in expressions
4783 @cindex expression, order of evaluation
4786 Parentheses may be used as in any other language. However, in
4787 @code{gtroff} they are necessary to ensure order of evaluation.
4788 @code{gtroff} has no operator precedence; expressions are evaluated left
4789 to right. This means that @code{gtroff} evaluates @samp{3+5*4} as if it were
4790 parenthesized like @samp{(3+5)*4}, not as @samp{3+(5*4)}, as might be
4793 @cindex @code{+}, and page motion
4794 @cindex @code{-}, and page motion
4795 @cindex motion operators
4796 @cindex operators, motion
4797 For many requests which cause a motion on the page, the unary operators
4798 @samp{+} and @samp{-} work differently if leading an expression. They
4799 then indicate a motion relative to the current position (down or up,
4802 @cindex @code{|}, and page motion
4803 @cindex absolute position operator (@code{|})
4804 @cindex position, absolute, operator (@code{|})
4805 Similarly, a leading @samp{|} operator indicates an absolute position.
4806 For vertical movements, it specifies the distance from the top of the
4807 page; for horizontal movements, it gives the distance from the beginning
4808 of the @emph{input} line.
4810 @cindex @code{bp} request, using @code{+} and@tie{}@code{-}
4811 @cindex @code{in} request, using @code{+} and@tie{}@code{-}
4812 @cindex @code{ll} request, using @code{+} and@tie{}@code{-}
4813 @cindex @code{lt} request, using @code{+} and@tie{}@code{-}
4814 @cindex @code{nm} request, using @code{+} and@tie{}@code{-}
4815 @cindex @code{nr} request, using @code{+} and@tie{}@code{-}
4816 @cindex @code{pl} request, using @code{+} and@tie{}@code{-}
4817 @cindex @code{pn} request, using @code{+} and@tie{}@code{-}
4818 @cindex @code{po} request, using @code{+} and@tie{}@code{-}
4819 @cindex @code{ps} request, using @code{+} and@tie{}@code{-}
4820 @cindex @code{pvs} request, using @code{+} and@tie{}@code{-}
4821 @cindex @code{rt} request, using @code{+} and@tie{}@code{-}
4822 @cindex @code{ti} request, using @code{+} and@tie{}@code{-}
4823 @cindex @code{\H}, using @code{+} and@tie{}@code{-}
4824 @cindex @code{\R}, using @code{+} and@tie{}@code{-}
4825 @cindex @code{\s}, using @code{+} and@tie{}@code{-}
4826 @samp{+} and @samp{-} are also treated differently by the following
4827 requests and escapes: @code{bp}, @code{in}, @code{ll}, @code{lt},
4828 @code{nm}, @code{nr}, @code{pl}, @code{pn}, @code{po}, @code{ps},
4829 @code{pvs}, @code{rt}, @code{ti}, @code{\H}, @code{\R}, and @code{\s}.
4830 Here, leading plus and minus signs indicate increments and decrements.
4832 @xref{Setting Registers}, for some examples.
4834 @Defesc {\\B, ', anything, '}
4835 @cindex numeric expression, valid
4836 @cindex valid numeric expression
4837 Return@tie{}1 if @var{anything} is a valid numeric expression;
4838 or@tie{}0 if @var{anything} is empty or not a valid numeric expression.
4841 @cindex space characters, in expressions
4842 @cindex expressions, and space characters
4843 Due to the way arguments are parsed, spaces are not allowed in
4844 expressions, unless the entire expression is surrounded by parentheses.
4846 @xref{Request and Macro Arguments}, and @ref{Conditionals and Loops}.
4849 @c =====================================================================
4851 @node Identifiers, Embedded Commands, Expressions, gtroff Reference
4852 @section Identifiers
4855 Like any other language, @code{gtroff} has rules for properly formed
4856 @dfn{identifiers}. In @code{gtroff}, an identifier can be made up of
4857 almost any printable character, with the exception of the following
4862 @cindex whitespace characters
4863 @cindex newline character
4864 @cindex character, whitespace
4865 Whitespace characters (spaces, tabs, and newlines).
4868 @cindex character, backspace
4869 @cindex backspace character
4870 @cindex @acronym{EBCDIC} encoding of backspace
4871 Backspace (@acronym{ASCII}@tie{}@code{0x08} or
4872 @acronym{EBCDIC}@tie{}@code{0x16}) and character code @code{0x01}.
4875 @cindex invalid input characters
4876 @cindex input characters, invalid
4877 @cindex characters, invalid input
4879 The following input characters are invalid and are ignored if
4880 @code{groff} runs on a machine based on @acronym{ASCII}, causing a
4881 warning message of type @samp{input} (see @ref{Debugging}, for more
4882 details): @code{0x00}, @code{0x0B}, @code{0x0D}-@code{0x1F},
4883 @code{0x80}-@code{0x9F}.
4885 And here are the invalid input characters if @code{groff} runs on an
4886 @acronym{EBCDIC} host: @code{0x00}, @code{0x08}, @code{0x09},
4887 @code{0x0B}, @code{0x0D}-@code{0x14}, @code{0x17}-@code{0x1F},
4888 @code{0x30}-@code{0x3F}.
4890 Currently, some of these reserved codepoints are used internally, thus
4891 making it non-trivial to extend @code{gtroff} to cover Unicode or other
4892 character sets and encodings which use characters of these ranges.
4894 Note that invalid characters are removed before parsing; an
4895 identifier @code{foo}, followed by an invalid character, followed by
4896 @code{bar} is treated as @code{foobar}.
4899 For example, any of the following is valid.
4909 @cindex @code{]}, as part of an identifier
4911 Note that identifiers longer than two characters with a closing bracket
4912 (@samp{]}) in its name can't be accessed with escape sequences which
4913 expect an identifier as a parameter. For example, @samp{\[foo]]}
4914 accesses the glyph @samp{foo}, followed by @samp{]}, whereas
4915 @samp{\C'foo]'} really asks for glyph @samp{foo]}.
4917 @cindex @code{refer}, and macro names starting with @code{[} or @code{]}
4918 @cindex @code{[}, macro names starting with, and @code{refer}
4919 @cindex @code{]}, macro names starting with, and @code{refer}
4920 @cindex macro names, starting with @code{[} or @code{]}, and @code{refer}
4921 To avoid problems with the @code{refer} preprocessor, macro names
4922 should not start with @samp{[} or @samp{]}. Due to backwards
4923 compatibility, everything after @samp{.[} and @samp{.]} is handled as
4924 a special argument to @code{refer}. For example, @samp{.[foo} makes
4925 @code{refer} to start a reference, using @samp{foo} as a parameter.
4927 @Defesc {\\A, ', ident, '}
4928 Test whether an identifier @var{ident} is valid in @code{gtroff}. It
4929 expands to the character@tie{}1 or@tie{}0 according to whether its
4930 argument (usually delimited by quotes) is or is not acceptable as the
4931 name of a string, macro, diversion, number register, environment, or
4932 font. It returns@tie{}0 if no argument is given. This is useful for
4933 looking up user input in some sort of associative table.
4941 @xref{Escapes}, for details on parameter delimiting characters.
4943 Identifiers in @code{gtroff} can be any length, but, in some contexts,
4944 @code{gtroff} needs to be told where identifiers end and text begins
4945 (and in different ways depending on their length):
4951 @cindex @code{(}, starting a two-character identifier
4953 Two characters. Must be prefixed with @samp{(} in some situations.
4955 @cindex @code{[}, starting an identifier
4956 @cindex @code{]}, ending an identifier
4958 Arbitrary length (@code{gtroff} only). Must be bracketed with @samp{[}
4959 and@tie{}@samp{]} in some situations. Any length identifier can be put
4963 @cindex undefined identifiers
4964 @cindex identifiers, undefined
4965 Unlike many other programming languages, undefined identifiers are
4966 silently ignored or expanded to nothing.
4967 When @code{gtroff} finds an undefined identifier, it emits a
4968 warning, doing the following:
4972 If the identifier is a string, macro, or diversion,
4973 @code{gtroff} defines it as empty.
4976 If the identifier is a number register, @code{gtroff}
4977 defines it with a value of@tie{}0.
4980 @xref{Warnings}., @ref{Interpolating Registers}, and @ref{Strings}.
4982 Note that macros, strings, and diversions share the same name space.
4999 As can be seen in the previous example, @code{gtroff} reuses the
5000 identifier @samp{xxx}, changing it from a macro to a diversion.
5001 No warning is emitted! The contents of the first macro definition is
5004 @xref{Interpolating Registers}, and @ref{Strings}.
5007 @c =====================================================================
5009 @node Embedded Commands, Registers, Identifiers, gtroff Reference
5010 @section Embedded Commands
5011 @cindex embedded commands
5012 @cindex commands, embedded
5014 Most documents need more functionality beyond filling, adjusting and
5015 implicit line breaking. In order to gain further functionality,
5016 @code{gtroff} allows commands to be embedded into the text, in two ways.
5018 The first is a @dfn{request} which takes up an entire line, and does
5019 some large-scale operation (e.g.@: break lines, start new pages).
5021 The other is an @dfn{escape} which can be usually embedded anywhere
5022 in the text; most requests can accept it even as an argument.
5023 Escapes generally do more minor operations like sub- and superscripts,
5024 print a symbol, etc.
5032 @c ---------------------------------------------------------------------
5034 @node Requests, Macros, Embedded Commands, Embedded Commands
5035 @subsection Requests
5038 @cindex control character (@code{.})
5039 @cindex character, control (@code{.})
5040 @cindex no-break control character (@code{'})
5041 @cindex character, no-break control (@code{'})
5042 @cindex control character, no-break (@code{'})
5043 A request line begins with a control character, which is either a single
5044 quote (@samp{'}, the @dfn{no-break control character}) or a period
5045 (@samp{.}, the normal @dfn{control character}). These can be changed;
5046 see @ref{Character Translations}, for details. After this there may be
5047 optional tabs or spaces followed by an identifier which is the name of
5048 the request. This may be followed by any number of space-separated
5049 arguments (@emph{no} tabs here).
5051 @cindex structuring source code of documents or macro packages
5052 @cindex documents, structuring the source code
5053 @cindex macro packages, structuring the source code
5054 Since a control character followed by whitespace only is ignored, it
5055 is common practice to use this feature for structuring the source code
5056 of documents or macro packages.
5070 @cindex blank line macro (@code{blm})
5071 Another possibility is to use the blank line macro request @code{blm}
5072 by assigning an empty macro to it.
5077 .blm do-nothing \" activate blank line macro
5088 .blm \" deactivate blank line macro
5091 @xref{Blank Line Traps}.
5093 @cindex zero width space character (@code{\&})
5094 @cindex character, zero width space (@code{\&})
5095 @cindex space character, zero width (@code{\&})
5096 @cindex @code{\&}, escaping control characters
5097 To begin a line with a control character without it being interpreted,
5098 precede it with @code{\&}. This represents a zero width space, which
5099 means it does not affect the output.
5101 In most cases the period is used as a control character. Several
5102 requests cause a break implicitly; using the single quote control
5103 character prevents this.
5106 * Request and Macro Arguments::
5109 @node Request and Macro Arguments, , Requests, Requests
5110 @subsubsection Request and Macro Arguments
5111 @cindex request arguments
5112 @cindex macro arguments
5113 @cindex arguments to requests and macros
5115 Arguments to requests and macros are processed much like the shell:
5116 The line is split into arguments according to
5117 spaces.@footnote{Plan@tie{}9's @code{troff} implementation also allows
5118 tabs for argument separation -- @code{gtroff} intentionally doesn't
5121 @cindex spaces, in a macro argument
5122 An argument to a macro which is intended to contain spaces can either be
5123 enclosed in double quotes, or have the spaces @dfn{escaped} with
5124 backslashes. This is @emph{not} true for requests.
5126 Here are a few examples for a hypothetical macro @code{uh}:
5129 .uh The Mouse Problem
5130 .uh "The Mouse Problem"
5131 .uh The\ Mouse\ Problem
5134 @cindex @code{\~}, difference to @code{\@key{SP}}
5135 @cindex @code{\@key{SP}}, difference to @code{\~}
5137 The first line is the @code{uh} macro being called with 3 arguments,
5138 @samp{The}, @samp{Mouse}, and @samp{Problem}. The latter two have the
5139 same effect of calling the @code{uh} macro with one argument, @samp{The
5140 Mouse Problem}.@footnote{The last solution, i.e., using escaped spaces,
5141 is ``classical'' in the sense that it can be found in most @code{troff}
5142 documents. Nevertheless, it is not optimal in all situations, since
5143 @w{@samp{\ }} inserts a fixed-width, non-breaking space character which
5144 can't stretch. @code{gtroff} provides a different command @code{\~} to
5145 insert a stretchable, non-breaking space.}
5147 @cindex @code{"}, in a macro argument
5148 @cindex double quote, in a macro argument
5149 A double quote which isn't preceded by a space doesn't start a macro
5150 argument. If not closing a string, it is printed literally.
5155 .xxx a" "b c" "de"fg"
5159 has the arguments @samp{a"}, @w{@samp{b c}}, @samp{de}, and @samp{fg"}.
5160 Don't rely on this obscure behaviour!
5162 There are two possibilities to get a double quote reliably.
5166 Enclose the whole argument with double quotes and use two consecutive double
5167 quotes to represent a single one. This traditional solution has the
5168 disadvantage that double quotes don't survive argument expansion again if
5169 called in compatibility mode (using the @option{-C} option of @code{groff}):
5173 . tm xx: `\\$1' `\\$2' `\\$3'
5175 . yy "\\$1" "\\$2" "\\$3"
5178 . tm yy: `\\$1' `\\$2' `\\$3'
5180 .xx A "test with ""quotes""" .
5181 @result{} xx: `A' `test with "quotes"' `.'
5182 @result{} yy: `A' `test with ' `quotes""'
5186 If not in compatibility mode, you get the expected result
5189 xx: `A' `test with "quotes"' `.'
5190 yy: `A' `test with "quotes"' `.'
5194 since @code{gtroff} preserves the input level.
5197 Use the double quote glyph @code{\(dq}. This works with and without
5198 compatibility mode enabled since @code{gtroff} doesn't convert @code{\(dq}
5199 back to a double quote input character.
5201 Not that this method won't work with @acronym{UNIX} @code{troff} in general
5202 since the glyph `dq' isn't defined normally.
5205 @cindex @code{ds} request, and double quotes
5206 Double quotes in the @code{ds} request are handled differently.
5207 @xref{Strings}, for more details.
5209 @c ---------------------------------------------------------------------
5211 @node Macros, Escapes, Requests, Embedded Commands
5215 @code{gtroff} has a @dfn{macro} facility for defining a series of lines
5216 which can be invoked by name. They are called in the same manner as
5217 requests -- arguments also may be passed basically in the same manner.
5219 @xref{Writing Macros}, and @ref{Request and Macro Arguments}.
5221 @c ---------------------------------------------------------------------
5223 @node Escapes, , Macros, Embedded Commands
5227 Escapes may occur anywhere in the input to @code{gtroff}. They usually
5228 begin with a backslash and are followed by a single character which
5229 indicates the function to be performed. The escape character can be
5230 changed; see @ref{Character Translations}.
5232 Escape sequences which require an identifier as a parameter accept three
5233 possible syntax forms.
5237 The next single character is the identifier.
5239 @cindex @code{(}, starting a two-character identifier
5241 If this single character is an opening parenthesis, take the following
5242 two characters as the identifier. Note that there is no closing
5243 parenthesis after the identifier.
5245 @cindex @code{[}, starting an identifier
5246 @cindex @code{]}, ending an identifier
5248 If this single character is an opening bracket, take all characters
5249 until a closing bracket as the identifier.
5261 @cindex @code{'}, delimiting arguments
5262 @cindex argument delimiting characters
5263 @cindex characters, argument delimiting
5264 @cindex delimiting characters for arguments
5265 Other escapes may require several arguments and/or some special format.
5266 In such cases the argument is traditionally enclosed in single quotes
5267 (and quotes are always used in this manual for the definitions of escape
5268 sequences). The enclosed text is then processed according to what that
5269 escape expects. Example:
5275 @cindex @code{\o}, possible quote characters
5276 @cindex @code{\b}, possible quote characters
5277 @cindex @code{\X}, possible quote characters
5278 Note that the quote character can be replaced with any other character
5279 which does not occur in the argument (even a newline or a space
5280 character) in the following escapes: @code{\o}, @code{\b}, and
5281 @code{\X}. This makes e.g.
5290 @result{} A caf@'e in Paris
5294 possible, but it is better not to use this feature to avoid confusion.
5296 @cindex @code{\%}, used as delimiter
5297 @cindex @code{\@key{SP}}, used as delimiter
5298 @cindex @code{\|}, used as delimiter
5299 @cindex @code{\^}, used as delimiter
5300 @cindex @code{\@{}, used as delimiter
5301 @cindex @code{\@}}, used as delimiter
5302 @cindex @code{\'}, used as delimiter
5303 @cindex @code{\`}, used as delimiter
5304 @cindex @code{\-}, used as delimiter
5305 @cindex @code{\_}, used as delimiter
5306 @cindex @code{\!}, used as delimiter
5307 @cindex @code{\?}, used as delimiter
5308 @cindex @code{\@@}, used as delimiter
5309 @cindex @code{\)}, used as delimiter
5310 @cindex @code{\/}, used as delimiter
5311 @cindex @code{\,}, used as delimiter
5312 @cindex @code{\&}, used as delimiter
5314 @cindex @code{\:}, used as delimiter
5317 @cindex @code{\@r{<colon>}}, used as delimiter
5319 @cindex @code{\~}, used as delimiter
5320 @cindex @code{\0}, used as delimiter
5321 @cindex @code{\a}, used as delimiter
5322 @cindex @code{\c}, used as delimiter
5323 @cindex @code{\d}, used as delimiter
5324 @cindex @code{\e}, used as delimiter
5325 @cindex @code{\E}, used as delimiter
5326 @cindex @code{\p}, used as delimiter
5327 @cindex @code{\r}, used as delimiter
5328 @cindex @code{\t}, used as delimiter
5329 @cindex @code{\u}, used as delimiter
5330 The following escapes sequences (which are handled similarly to
5331 characters since they don't take a parameter) are also allowed as
5332 delimiters: @code{\%}, @w{@samp{\ }}, @code{\|}, @code{\^}, @code{\@{},
5333 @code{\@}}, @code{\'}, @code{\`}, @code{\-}, @code{\_}, @code{\!},
5334 @code{\?}, @code{\@@}, @code{\)}, @code{\/}, @code{\,}, @code{\&},
5335 @code{\:}, @code{\~}, @code{\0}, @code{\a}, @code{\c}, @code{\d},
5336 @code{\e}, @code{\E}, @code{\p}, @code{\r}, @code{\t}, and @code{\u}.
5337 Again, don't use these if possible.
5339 @cindex @code{\A}, allowed delimiters
5340 @cindex @code{\B}, allowed delimiters
5341 @cindex @code{\Z}, allowed delimiters
5342 @cindex @code{\C}, allowed delimiters
5343 @cindex @code{\w}, allowed delimiters
5344 No newline characters as delimiters are allowed in the following
5345 escapes: @code{\A}, @code{\B}, @code{\Z}, @code{\C}, and @code{\w}.
5347 @cindex @code{\D}, allowed delimiters
5348 @cindex @code{\h}, allowed delimiters
5349 @cindex @code{\H}, allowed delimiters
5350 @cindex @code{\l}, allowed delimiters
5351 @cindex @code{\L}, allowed delimiters
5352 @cindex @code{\N}, allowed delimiters
5353 @cindex @code{\R}, allowed delimiters
5354 @cindex @code{\s}, allowed delimiters
5355 @cindex @code{\S}, allowed delimiters
5356 @cindex @code{\v}, allowed delimiters
5357 @cindex @code{\x}, allowed delimiters
5358 Finally, the escapes @code{\D}, @code{\h}, @code{\H}, @code{\l},
5359 @code{\L}, @code{\N}, @code{\R}, @code{\s}, @code{\S}, @code{\v},
5360 and @code{\x} can't use the following characters as delimiters:
5364 @cindex numbers, and delimiters
5365 @cindex digits, and delimiters
5366 The digits @code{0}-@code{9}.
5369 @cindex operators, as delimiters
5370 @cindex @code{+}, as delimiter
5371 @cindex @code{-}, as delimiter
5372 @cindex @code{/}, as delimiter
5373 @cindex @code{*}, as delimiter
5374 @cindex @code{%}, as delimiter
5375 @cindex @code{<}, as delimiter
5376 @cindex @code{>}, as delimiter
5377 @cindex @code{=}, as delimiter
5378 @cindex @code{&}, as delimiter
5380 @cindex @code{:}, as delimiter
5383 @cindex <colon>, as delimiter
5385 @cindex @code{(}, as delimiter
5386 @cindex @code{)}, as delimiter
5387 @cindex @code{.}, as delimiter
5388 The (single-character) operators @samp{+-/*%<>=&:().}.
5391 @cindex space character
5392 @cindex character, space
5393 @cindex tab character
5394 @cindex character, tab
5395 @cindex newline character
5396 @cindex character, newline
5397 The space, tab, and newline characters.
5400 @cindex @code{\%}, used as delimiter
5402 @cindex @code{\:}, used as delimiter
5405 @cindex @code{\@r{<colon>}}, used as delimiter
5407 @cindex @code{\@{}, used as delimiter
5408 @cindex @code{\@}}, used as delimiter
5409 @cindex @code{\'}, used as delimiter
5410 @cindex @code{\`}, used as delimiter
5411 @cindex @code{\-}, used as delimiter
5412 @cindex @code{\_}, used as delimiter
5413 @cindex @code{\!}, used as delimiter
5414 @cindex @code{\@@}, used as delimiter
5415 @cindex @code{\/}, used as delimiter
5416 @cindex @code{\c}, used as delimiter
5417 @cindex @code{\e}, used as delimiter
5418 @cindex @code{\p}, used as delimiter
5419 All escape sequences except @code{\%}, @code{\:}, @code{\@{}, @code{\@}},
5420 @code{\'}, @code{\`}, @code{\-}, @code{\_}, @code{\!}, @code{\@@},
5421 @code{\/}, @code{\c}, @code{\e}, and @code{\p}.
5424 @cindex printing backslash (@code{\\}, @code{\e}, @code{\E}, @code{\[rs]})
5425 @cindex backslash, printing (@code{\\}, @code{\e}, @code{\E}, @code{\[rs]})
5426 To have a backslash (actually, the current escape character) appear in the
5427 output several escapes are defined: @code{\\}, @code{\e} or @code{\E}.
5428 These are very similar, and only differ with respect to being used in
5429 macros or diversions. @xref{Character Translations}, for an exact
5430 description of those escapes.
5432 @xref{Implementation Differences}, @ref{Copy-in Mode}, and @ref{Diversions},
5433 @ref{Identifiers}, for more information.
5439 @node Comments, , Escapes, Escapes
5440 @subsubsection Comments
5443 Probably one of the most@footnote{Unfortunately, this is a lie. But
5444 hopefully future @code{gtroff} hackers will believe it @code{:-)}}
5445 common forms of escapes is the comment.
5448 Start a comment. Everything to the end of the input line is ignored.
5450 This may sound simple, but it can be tricky to keep the comments from
5451 interfering with the appearance of the final output.
5453 @cindex @code{ds}, @code{ds1} requests, and comments
5454 @cindex @code{as}, @code{as1} requests, and comments
5455 If the escape is to the right of some text or a request, that portion
5456 of the line is ignored, but the space leading up to it is noticed by
5457 @code{gtroff}. This only affects the @code{ds} and @code{as}
5458 request and its variants.
5460 @cindex tabs, before comments
5461 @cindex comments, lining up with tabs
5462 One possibly irritating idiosyncracy is that tabs must not be used to
5463 line up comments. Tabs are not treated as whitespace between the
5464 request and macro arguments.
5466 @cindex undefined request
5467 @cindex request, undefined
5468 A comment on a line by itself is treated as a blank line, because
5469 after eliminating the comment, that is all that remains:
5486 To avoid this, it is common to start the line with @code{.\"} which
5487 causes the line to be treated as an undefined request and thus ignored
5490 @cindex @code{'}, as a comment
5491 Another commenting scheme seen sometimes is three consecutive single
5492 quotes (@code{'''}) at the beginning of a line. This works, but
5493 @code{gtroff} gives a warning about an undefined macro (namely
5494 @code{''}), which is harmless, but irritating.
5498 To avoid all this, @code{gtroff} has a new comment mechanism using the
5499 @code{\#} escape. This escape works the same as @code{\"} except that
5500 the newline is also ignored:
5519 @Defreq {ig, [@Var{end}]}
5520 Ignore all input until @code{gtroff} encounters the macro named
5521 @code{.}@var{end} on a line by itself (or @code{..} if @var{end} is not
5522 specified). This is useful for commenting out large blocks of text:
5527 This is part of a large block
5528 of text that has been
5529 temporarily(?) commented out.
5531 We can restore it simply by removing
5532 the .ig request and the ".." at the
5535 More text text text...
5542 text text text@dots{} More text text text@dots{}
5546 Note that the commented-out block of text does not
5549 The input is read in copy-mode; auto-incremented registers @emph{are}
5550 affected (@pxref{Auto-increment}).
5554 @c =====================================================================
5556 @node Registers, Manipulating Filling and Adjusting, Embedded Commands, gtroff Reference
5560 Numeric variables in @code{gtroff} are called @dfn{registers}. There
5561 are a number of built-in registers, supplying anything from the date to
5562 details of formatting parameters.
5564 @xref{Identifiers}, for details on register identifiers.
5567 * Setting Registers::
5568 * Interpolating Registers::
5570 * Assigning Formats::
5571 * Built-in Registers::
5574 @c ---------------------------------------------------------------------
5576 @node Setting Registers, Interpolating Registers, Registers, Registers
5577 @subsection Setting Registers
5578 @cindex setting registers (@code{nr}, @code{\R})
5579 @cindex registers, setting (@code{nr}, @code{\R})
5581 Define or set registers using the @code{nr} request or the
5584 @DefreqList {nr, ident value}
5585 @DefescListEnd {\\R, ', ident value, '}
5586 Set number register @var{ident} to @var{value}. If @var{ident}
5587 doesn't exist, @code{gtroff} creates it.
5589 The argument to @code{\R} usually has to be enclosed in quotes.
5590 @xref{Escapes}, for details on parameter delimiting characters.
5592 The @code{\R} escape doesn't produce an input token in @code{gtroff};
5593 with other words, it vanishes completely after @code{gtroff} has
5597 For example, the following two lines are equivalent:
5600 .nr a (((17 + (3 * 4))) % 4)
5601 \R'a (((17 + (3 * 4))) % 4)'
5605 Both @code{nr} and @code{\R} have two additional special forms to
5606 increment or decrement a register.
5608 @DefreqList {nr, ident @t{+}@Var{value}}
5609 @DefreqItem {nr, ident @t{-}@Var{value}}
5610 @DefescItem {\\R, ', ident @t{+}value, '}
5611 @DefescListEnd {\\R, ', ident @t{-}value, '}
5612 Increment (decrement) register @var{ident} by @var{value}.
5621 @cindex negating register values
5622 To assign the negated value of a register to another register, some care
5623 must be taken to get the desired result:
5637 The surrounding parentheses prevent the interpretation of the minus sign
5638 as a decrementing operator. An alternative is to start the assignment
5654 @cindex removing number register (@code{rr})
5655 @cindex number register, removing (@code{rr})
5656 @cindex register, removing (@code{rr})
5657 Remove number register @var{ident}. If @var{ident} doesn't exist, the
5661 @Defreq {rnn, ident1 ident2}
5662 @cindex renaming number register (@code{rnn})
5663 @cindex number register, renaming (@code{rnn})
5664 @cindex register, renaming (@code{rnn})
5665 Rename number register @var{ident1} to @var{ident2}. If either
5666 @var{ident1} or @var{ident2} doesn't exist, the request is ignored.
5669 @Defreq {aln, ident1 ident2}
5670 @cindex alias, number register, creating (@code{aln})
5671 @cindex creating alias, for number register (@code{aln})
5672 @cindex number register, creating alias (@code{aln})
5673 @cindex register, creating alias (@code{aln})
5674 Create an alias @var{ident1} for a number register @var{ident2}. The
5675 new name and the old name are exactly equivalent. If @var{ident1} is
5676 undefined, a warning of type @samp{reg} is generated, and the request
5677 is ignored. @xref{Debugging}, for information about warnings.
5680 @c ---------------------------------------------------------------------
5682 @node Interpolating Registers, Auto-increment, Setting Registers, Registers
5683 @subsection Interpolating Registers
5684 @cindex interpolating registers (@code{\n})
5685 @cindex registers, interpolating (@code{\n})
5687 Numeric registers can be accessed via the @code{\n} escape.
5689 @DefescList {\\n, , i, }
5690 @DefescItem {\\n, @lparen{}, id, }
5691 @DefescListEnd {\\n, @lbrack{}, ident, @rbrack}
5692 @cindex nested assignments
5693 @cindex assignments, nested
5694 @cindex indirect assignments
5695 @cindex assignments, indirect
5696 Interpolate number register with name @var{ident} (one-character
5697 name@tie{}@var{i}, two-character name @var{id}). This means that the value
5698 of the register is expanded in-place while @code{gtroff} is parsing the
5699 input line. Nested assignments (also called indirect assignments) are
5721 @c ---------------------------------------------------------------------
5723 @node Auto-increment, Assigning Formats, Interpolating Registers, Registers
5724 @subsection Auto-increment
5725 @cindex auto-increment
5726 @cindex increment, automatic
5728 Number registers can also be auto-incremented and auto-decremented.
5729 The increment or decrement value can be specified with a third
5730 argument to the @code{nr} request or @code{\R} escape.
5732 @Defreq {nr, ident value incr}
5733 @cindex @code{\R}, difference to @code{nr}
5734 Set number register @var{ident} to @var{value}; the increment for
5735 auto-incrementing is set to @var{incr}. Note that the @code{\R}
5736 escape doesn't support this notation.
5739 To activate auto-incrementing, the escape @code{\n} has a special
5742 @DefescList {\\n, +, i, }
5743 @DefescItem {\\n, -, i, }
5744 @DefescItem {\\n, @lparen{}+, id, }
5745 @DefescItem {\\n, @lparen{}-, id, }
5746 @DefescItem {\\n, +@lparen{}, id, }
5747 @DefescItem {\\n, -@lparen{}, id, }
5748 @DefescItem {\\n, @lbrack{}+, ident, @rbrack{}}
5749 @DefescItem {\\n, @lbrack{}-, ident, @rbrack{}}
5750 @DefescItem {\\n, +@lbrack{}, ident, @rbrack{}}
5751 @DefescListEnd {\\n, -@lbrack{}, ident, @rbrack{}}
5752 Before interpolating, increment or decrement @var{ident}
5753 (one-character name@tie{}@var{i}, two-character name @var{id}) by the
5754 auto-increment value as specified with the @code{nr} request (or the
5755 @code{\R} escape). If no auto-increment value has been specified,
5756 these syntax forms are identical to @code{\n}.
5765 \n+a, \n+a, \n+a, \n+a, \n+a
5767 \n-(xx, \n-(xx, \n-(xx, \n-(xx, \n-(xx
5769 \n+[foo], \n+[foo], \n+[foo], \n+[foo], \n+[foo]
5777 -5, -10, -15, -20, -25
5781 @cindex increment value without changing the register
5782 @cindex value, incrementing without changing the register
5783 To change the increment value without changing the value of a register
5784 (@var{a} in the example), the following can be used:
5790 @c ---------------------------------------------------------------------
5792 @node Assigning Formats, Built-in Registers, Auto-increment, Registers
5793 @subsection Assigning Formats
5794 @cindex assigning formats (@code{af})
5795 @cindex formats, assigning (@code{af})
5797 When a register is used in the text of an input file (as opposed to
5798 part of an expression), it is textually replaced (or interpolated)
5799 with a representation of that number. This output format can be
5800 changed to a variety of formats (numbers, Roman numerals, etc.). This
5801 is done using the @code{af} request.
5803 @Defreq {af, ident format}
5804 Change the output format of a number register. The first argument
5805 @var{ident} is the name of the number register to be changed, and the
5806 second argument @var{format} is the output format. The following
5807 output formats are available:
5811 Decimal arabic numbers. This is the default format: 0, 1, 2,
5815 Decimal numbers with as many digits as specified. So, @samp{00} would
5816 result in printing numbers as 01, 02, 03,@tie{}@enddots{}
5818 In fact, any digit instead of zero will do; @code{gtroff} only counts
5819 how many digits are specified. As a consequence, @code{af}'s default
5820 format @samp{1} could be specified as @samp{0} also (and exactly this is
5821 returned by the @code{\g} escape, see below).
5824 @cindex Roman numerals
5825 @cindex numerals, Roman
5826 Upper-case Roman numerals: 0, I, II, III, IV,@tie{}@enddots{}
5829 Lower-case Roman numerals: 0, i, ii, iii, iv,@tie{}@enddots{}
5832 Upper-case letters: 0, A, B, C, @dots{},@tie{}Z, AA, AB,@tie{}@enddots{}
5835 Lower-case letters: 0, a, b, c, @dots{},@tie{}z, aa, ab,@tie{}@enddots{}
5838 Omitting the number register format causes a warning of type
5839 @samp{missing}. @xref{Debugging}, for more details. Specifying a
5840 nonexistent format causes an error.
5842 The following example produces @samp{10, X, j, 010}:
5846 .af a 1 \" the default format
5856 @cindex Roman numerals, maximum and minimum
5857 @cindex maximum values of Roman numerals
5858 @cindex minimum values of Roman numerals
5859 The largest number representable for the @samp{i} and @samp{I} formats
5860 is 39999 (or @minus{}39999); @acronym{UNIX} @code{troff} uses @samp{z}
5861 and @samp{w} to represent 10000 and 5000 in Roman numerals, and so does
5862 @code{gtroff}. Currently, the correct glyphs of Roman numeral five
5863 thousand and Roman numeral ten thousand (Unicode code points
5864 @code{U+2182} and @code{U+2181}, respectively) are not available.
5866 If @var{ident} doesn't exist, it is created.
5868 @cindex read-only register, changing format
5869 @cindex changing format, and read-only registers
5870 Changing the output format of a read-only register causes an error. It
5871 is necessary to first copy the register's value to a writeable register,
5872 then apply the @code{af} request to this other register.
5875 @DefescList {\\g, , i, }
5876 @DefescItem {\\g, @lparen{}, id, }
5877 @DefescListEnd {\\g, @lbrack{}, ident, @rbrack{}}
5878 @cindex format of register (@code{\g})
5879 @cindex register, format (@code{\g})
5880 Return the current format of the specified register @var{ident}
5881 (one-character name@tie{}@var{i}, two-character name @var{id}). For
5882 example, @samp{\ga} after the previous example would produce the
5883 string @samp{000}. If the register hasn't been defined yet, nothing
5887 @c ---------------------------------------------------------------------
5889 @node Built-in Registers, , Assigning Formats, Registers
5890 @subsection Built-in Registers
5891 @cindex built-in registers
5892 @cindex registers, built-in
5894 The following lists some built-in registers which are not described
5895 elsewhere in this manual. Any register which begins with a @samp{.} is
5896 read-only. A complete listing of all built-in registers can be found in
5897 @ref{Register Index}.
5901 @cindex current input file name register (@code{.F})
5902 @cindex input file name, current, register (@code{.F})
5904 This string-valued register returns the current input file name.
5907 @cindex horizontal resolution register (@code{.H})
5908 @cindex resolution, horizontal, register (@code{.H})
5910 Horizontal resolution in basic units.
5916 @cindex mode, unsafe
5917 If @code{gtroff} is called with the @option{-U} command line option, the
5918 number register @code{.U} is set to@tie{}1, and zero otherwise.
5919 @xref{Groff Options}.
5922 @cindex vertical resolution register (@code{.V})
5923 @cindex resolution, vertical, register (@code{.V})
5925 Vertical resolution in basic units.
5928 @cindex seconds, current time (@code{seconds})
5929 @cindex time, current, seconds (@code{seconds})
5930 @cindex current time, seconds (@code{seconds})
5932 The number of seconds after the minute, normally in the range@tie{}0
5933 to@tie{}59, but can be up to@tie{}61 to allow for leap seconds. Initialized
5934 at start-up of @code{gtroff}.
5937 @cindex minutes, current time (@code{minutes})
5938 @cindex time, current, minutes (@code{minutes})
5939 @cindex current time, minutes (@code{minutes})
5941 The number of minutes after the hour, in the range@tie{}0 to@tie{}59.
5942 Initialized at start-up of @code{gtroff}.
5945 @cindex hours, current time (@code{hours})
5946 @cindex time, current, hours (@code{hours})
5947 @cindex current time, hours (@code{hours})
5949 The number of hours past midnight, in the range@tie{}0 to@tie{}23.
5950 Initialized at start-up of @code{gtroff}.
5953 @cindex day of the week register (@code{dw})
5954 @cindex date, day of the week register (@code{dw})
5956 Day of the week (1-7).
5959 @cindex day of the month register (@code{dy})
5960 @cindex date, day of the month register (@code{dy})
5962 Day of the month (1-31).
5965 @cindex month of the year register (@code{mo})
5966 @cindex date, month of the year register (@code{mo})
5968 Current month (1-12).
5971 @cindex date, year register (@code{year}, @code{yr})
5972 @cindex year, current, register (@code{year}, @code{yr})
5978 The current year minus@tie{}1900. Unfortunately, the documentation of
5979 @acronym{UNIX} Version@tie{}7's @code{troff} had a year@tie{}2000 bug: It
5980 incorrectly claimed that @code{yr} contains the last two digits of the
5981 year. That claim has never been true of either @acronym{AT&T}
5982 @code{troff} or GNU @code{troff}. Old @code{troff} input that looks
5986 '\" The following line stopped working after 1999
5987 This document was formatted in 19\n(yr.
5991 can be corrected as follows:
5994 This document was formatted in \n[year].
5998 or, to be portable to older @code{troff} versions, as follows:
6002 This document was formatted in \n(y4.
6009 @cindex input line number register (@code{.c}, @code{c.})
6010 @cindex line number, input, register (@code{.c}, @code{c.})
6011 The current @emph{input} line number. Register @samp{.c} is read-only,
6012 whereas @samp{c.} (a @code{gtroff} extension) is writable also,
6013 affecting both @samp{.c} and @samp{c.}.
6017 @cindex output line number register (@code{ln})
6018 @cindex line number, output, register (@code{ln})
6019 The current @emph{output} line number after a call to the @code{nm}
6020 request to activate line numbering.
6022 @xref{Miscellaneous}, for more information about line numbering.
6026 @cindex major version number register (@code{.x})
6027 @cindex version number, major, register (@code{.x})
6028 The major version number. For example, if the version number
6029 is 1.03 then @code{.x} contains@tie{}@samp{1}.
6033 @cindex minor version number register (@code{.y})
6034 @cindex version number, minor, register (@code{.y})
6035 The minor version number. For example, if the version number
6036 is 1.03 then @code{.y} contains@tie{}@samp{03}.
6040 @cindex revision number register (@code{.Y})
6041 The revision number of @code{groff}.
6045 @cindex process ID of @code{gtroff} register (@code{$$})
6046 @cindex @code{gtroff}, process ID register (@code{$$})
6047 The process ID of @code{gtroff}.
6051 @cindex @code{gtroff}, identification register (@code{.g})
6052 @cindex GNU-specific register (@code{.g})
6053 Always@tie{}1. Macros should use this to determine whether they are
6054 running under GNU @code{troff}.
6058 @cindex @acronym{ASCII} approximation output register (@code{.A})
6059 If the command line option @option{-a} is used to produce an
6060 @acronym{ASCII} approximation of the output, this is set to@tie{}1, zero
6061 otherwise. @xref{Groff Options}.
6065 This register is set to@tie{}1 (and to@tie{}0 otherwise) if the current
6066 page is actually being printed, i.e., if the @option{-o} option is being
6067 used to only print selected pages. @xref{Groff Options}, for more
6072 If @code{gtroff} is called with the @option{-T} command line option, the
6073 number register @code{.T} is set to@tie{}1, and zero otherwise.
6074 @xref{Groff Options}.
6078 @cindex output device name string register (@code{.T})
6079 A single read-write string register which contains the current output
6080 device (for example, @samp{latin1} or @samp{ps}). This is the only
6081 string register defined by @code{gtroff}.
6085 @c =====================================================================
6087 @node Manipulating Filling and Adjusting, Manipulating Hyphenation, Registers, gtroff Reference
6088 @section Manipulating Filling and Adjusting
6089 @cindex manipulating filling and adjusting
6090 @cindex filling and adjusting, manipulating
6091 @cindex adjusting and filling, manipulating
6092 @cindex justifying text
6093 @cindex text, justifying
6097 @cindex @code{bp} request, causing implicit linebreak
6098 @cindex @code{ce} request, causing implicit linebreak
6099 @cindex @code{cf} request, causing implicit linebreak
6100 @cindex @code{fi} request, causing implicit linebreak
6101 @cindex @code{fl} request, causing implicit linebreak
6102 @cindex @code{in} request, causing implicit linebreak
6103 @cindex @code{nf} request, causing implicit linebreak
6104 @cindex @code{rj} request, causing implicit linebreak
6105 @cindex @code{sp} request, causing implicit linebreak
6106 @cindex @code{ti} request, causing implicit linebreak
6107 @cindex @code{trf} request, causing implicit linebreak
6108 Various ways of causing @dfn{breaks} were given in @ref{Implicit Line
6109 Breaks}. The @code{br} request likewise causes a break. Several
6110 other requests also cause breaks, but implicitly. These are
6111 @code{bp}, @code{ce}, @code{cf}, @code{fi}, @code{fl}, @code{in},
6112 @code{nf}, @code{rj}, @code{sp}, @code{ti}, and @code{trf}.
6115 Break the current line, i.e., the input collected so far is emitted
6118 If the no-break control character is used, @code{gtroff} suppresses
6129 Initially, @code{gtroff} fills and adjusts text to both margins.
6130 Filling can be disabled via the @code{nf} request and re-enabled with
6131 the @code{fi} request.
6135 @cindex fill mode (@code{fi})
6136 @cindex mode, fill (@code{fi})
6137 Activate fill mode (which is the default). This request implicitly
6138 enables adjusting; it also inserts a break in the text currently being
6139 filled. The read-only number register @code{.u} is set to@tie{}1.
6141 The fill mode status is associated with the current environment
6142 (@pxref{Environments}).
6144 See @ref{Line Control}, for interaction with the @code{\c} escape.
6148 @cindex no-fill mode (@code{nf})
6149 @cindex mode, no-fill (@code{nf})
6150 Activate no-fill mode. Input lines are output as-is, retaining line
6151 breaks and ignoring the current line length. This command implicitly
6152 disables adjusting; it also causes a break. The number register
6153 @code{.u} is set to@tie{}0.
6155 The fill mode status is associated with the current environment
6156 (@pxref{Environments}).
6158 See @ref{Line Control}, for interaction with the @code{\c} escape.
6161 @DefreqList {ad, [@Var{mode}]}
6165 Activation and deactivation of adjusting is done implicitly with
6166 calls to the @code{fi} or @code{nf} requests.
6168 @var{mode} can have one of the following values:
6172 @cindex ragged-right
6173 Adjust text to the left margin. This produces what is traditionally
6174 called ragged-right text.
6178 Adjust text to the right margin, producing ragged-left text.
6181 @cindex centered text
6182 @cindex @code{ce} request, difference to @samp{.ad@tie{}c}
6183 Center filled text. This is different to the @code{ce} request which
6184 only centers text without filling.
6188 Justify to both margins. This is the default used by @code{gtroff}.
6191 Finally, @var{mode} can be the numeric argument returned by the @code{.j}
6194 With no argument, @code{gtroff} adjusts lines in the same way it did
6195 before adjusting was deactivated (with a call to @code{na}, for
6207 .ad \" back to centering
6209 .ad \n[ad] \" back to right justifying
6212 @cindex adjustment mode register (@code{.j})
6213 The current adjustment mode is available in the read-only number
6214 register @code{.j}; it can be stored and subsequently used to set
6217 The adjustment mode status is associated with the current environment
6218 (@pxref{Environments}).
6222 Disable adjusting. This request won't change the current adjustment
6223 mode: A subsequent call to @code{ad} uses the previous adjustment
6226 The adjustment mode status is associated with the current environment
6227 (@pxref{Environments}).
6231 @DefescListEnd {\\p, , , }
6232 Adjust the current line and cause a break.
6234 In most cases this produces very ugly results since @code{gtroff}
6235 doesn't have a sophisticated paragraph building algorithm (as @TeX{}
6236 have, for example); instead, @code{gtroff} fills and adjusts a paragraph
6240 This is an uninteresting sentence.
6241 This is an uninteresting sentence.\p
6242 This is an uninteresting sentence.
6249 This is an uninteresting sentence. This is an
6250 uninteresting sentence.
6251 This is an uninteresting sentence.
6255 @DefreqList {ss, word_space_size [@Var{sentence_space_size}]}
6257 @DefregListEnd {.sss}
6258 @cindex word space size register (@code{.ss})
6259 @cindex size of word space register (@code{.ss})
6260 @cindex space between words register (@code{.ss})
6261 @cindex sentence space size register (@code{.sss})
6262 @cindex size of sentence space register (@code{.sss})
6263 @cindex space between sentences register (@code{.sss})
6264 Change the size of a space between words. It takes its units as one
6265 twelfth of the space width parameter for the current font.
6266 Initially both the @var{word_space_size} and @var{sentence_space_size}
6267 are@tie{}12. In fill mode, the values specify the minimum distance.
6271 If two arguments are given to the @code{ss} request, the second
6272 argument sets the sentence space size. If the second argument is not
6273 given, sentence space size is set to @var{word_space_size}. The
6274 sentence space size is used in two circumstances: If the end of a
6275 sentence occurs at the end of a line in fill mode, then both an
6276 inter-word space and a sentence space are added; if two spaces follow
6277 the end of a sentence in the middle of a line, then the second space
6278 is a sentence space. If a second argument is never given to the
6279 @code{ss} request, the behaviour of @acronym{UNIX} @code{troff} is the
6280 same as that exhibited by GNU @code{troff}. In GNU @code{troff}, as
6281 in @acronym{UNIX} @code{troff}, a sentence should always be followed
6282 by either a newline or two spaces.
6284 The read-only number registers @code{.ss} and @code{.sss} hold the
6285 values of the parameters set by the first and second arguments of the
6288 The word space and sentence space values are associated with the current
6289 environment (@pxref{Environments}).
6291 Contrary to @acronym{AT&T} @code{troff}, this request is @emph{not}
6292 ignored if a TTY output device is used; the given values are then
6293 rounded down to a multiple of@tie{}12 (@pxref{Implementation Differences}).
6295 The request is ignored if there is no parameter.
6297 @cindex discardable horizontal space
6298 @cindex space, discardable, horizontal
6299 @cindex horizontal discardable space
6300 Another useful application of the @code{ss} request is to insert
6301 discardable horizontal space, i.e., space which is discarded at a line
6302 break. For example, paragraph-style footnotes could be separated this
6307 1.\ This is the first footnote.\c
6311 2.\ This is the second footnote.
6318 1. This is the first footnote. 2. This
6319 is the second footnote.
6323 Note that the @code{\h} escape produces unbreakable space.
6326 @DefreqList {ce, [@Var{nnn}]}
6327 @DefregListEnd {.ce}
6328 @cindex centering lines (@code{ce})
6329 @cindex lines, centering (@code{ce})
6330 Center text. While the @w{@samp{.ad c}} request also centers text,
6331 it fills the text as well. @code{ce} does not fill the
6332 text it affects. This request causes a break. The number of lines
6333 still to be centered is associated with the current environment
6334 (@pxref{Environments}).
6336 The following example demonstrates the differences.
6342 This is a small text fragment which shows the differences
6343 between the `.ce' and the `.ad c' request.
6347 This is a small text fragment which shows the differences
6348 between the `.ce' and the `.ad c' request.
6352 And here the result:
6355 This is a small text fragment which
6356 shows the differences
6357 between the `.ce' and the `.ad c' request.
6359 This is a small text fragment which
6360 shows the differences between the `.ce'
6361 and the `.ad c' request.
6364 With no arguments, @code{ce} centers the next line of text. @var{nnn}
6365 specifies the number of lines to be centered. If the argument is zero
6366 or negative, centering is disabled.
6368 The basic length for centering text is the line length (as set with the
6369 @code{ll} request) minus the indentation (as set with the @code{in}
6370 request). Temporary indentation is ignored.
6372 As can be seen in the previous example, it is a common idiom to turn
6373 on centering for a large number of lines, and to turn off centering
6374 after text to be centered. This is useful for any request which takes
6375 a number of lines as an argument.
6377 The @code{.ce} read-only number register contains the number of lines
6378 remaining to be centered, as set by the @code{ce} request.
6381 @DefreqList {rj, [@Var{nnn}]}
6382 @DefregListEnd {.rj}
6383 @cindex justifying text (@code{rj})
6384 @cindex text, justifying (@code{rj})
6385 @cindex right-justifying (@code{rj})
6386 Justify unfilled text to the right margin. Arguments are identical to
6387 the @code{ce} request. The @code{.rj} read-only number register is
6388 the number of lines to be right-justified as set by the @code{rj}
6389 request. This request causes a break. The number of lines still to be
6390 right-justified is associated with the current environment
6391 (@pxref{Environments}).
6395 @c =====================================================================
6397 @node Manipulating Hyphenation, Manipulating Spacing, Manipulating Filling and Adjusting, gtroff Reference
6398 @section Manipulating Hyphenation
6399 @cindex manipulating hyphenation
6400 @cindex hyphenation, manipulating
6402 As discussed in @ref{Hyphenation}, @code{gtroff} hyphenates words.
6403 There are a number of ways to influence hyphenation.
6405 @DefreqList {hy, [@Var{mode}]}
6406 @DefregListEnd {.hy}
6407 Enable hyphenation. The request has an optional numeric argument,
6408 @var{mode}, to restrict hyphenation if necessary:
6412 The default argument if @var{mode} is omitted. Hyphenate without
6413 restrictions. This is also the start-up value of @code{gtroff}.
6416 Do not hyphenate the last word on a page or column.
6419 Do not hyphenate the last two characters of a word.
6422 Do not hyphenate the first two characters of a word.
6425 Values in the previous table are additive. For example, the
6426 value@tie{}12 causes @code{gtroff} to neither hyphenate the last
6427 two nor the first two characters of a word.
6429 @cindex hyphenation restrictions register (@code{.hy})
6430 The current hyphenation restrictions can be found in the read-only
6431 number register @samp{.hy}.
6433 The hyphenation mode is associated with the current environment
6434 (@pxref{Environments}).
6438 Disable hyphenation (i.e., set the hyphenation mode to zero). Note
6439 that the hyphenation mode of the last call to @code{hy} is not
6442 The hyphenation mode is associated with the current environment
6443 (@pxref{Environments}).
6446 @DefreqList {hlm, [@Var{nnn}]}
6448 @DefregListEnd {.hlc}
6449 @cindex explicit hyphen (@code{\%})
6450 @cindex hyphen, explicit (@code{\%})
6451 @cindex consecutive hyphenated lines (@code{hlm})
6452 @cindex lines, consecutive hyphenated (@code{hlm})
6453 @cindex hyphenated lines, consecutive (@code{hlm})
6454 Set the maximum number of consecutive hyphenated lines to @var{nnn}.
6455 If this number is negative, there is no maximum. The default value
6456 is@tie{}@minus{}1 if @var{nnn} is omitted. This value is associated
6457 with the current environment (@pxref{Environments}). Only lines
6458 output from a given environment count towards the maximum associated
6459 with that environment. Hyphens resulting from @code{\%} are counted;
6460 explicit hyphens are not.
6462 The current setting of @code{hlm} is available in the @code{.hlm}
6463 read-only number register. Also the number of immediately preceding
6464 consecutive hyphenated lines are available in the read-only number
6465 register @samp{.hlc}.
6468 @Defreq {hw, word1 word2 @dots{}}
6469 Define how @var{word1}, @var{word2}, etc.@: are to be hyphenated. The
6470 words must be given with hyphens at the hyphenation points. For
6478 Besides the space character, any character whose hyphenation code value
6479 is zero can be used to separate the arguments of @code{hw} (see the
6480 documentation for the @code{hcode} request below for more information).
6481 In addition, this request can be used more than once.
6483 Hyphenation exceptions specified with the @code{hw} request are
6484 associated with the current hyphenation language; it causes an error
6485 if there is no current hyphenation language.
6487 This request is ignored if there is no parameter.
6489 In old versions of @code{troff} there was a limited amount of space to
6490 store such information; fortunately, with @code{gtroff}, this is no
6491 longer a restriction.
6494 @DefescList {\\%, , , }
6495 @deffnx Escape @t{\:}
6500 @esindex \@r{<colon>}
6502 @cindex hyphenation character (@code{\%})
6503 @cindex character, hyphenation (@code{\%})
6504 @cindex disabling hyphenation (@code{\%})
6505 @cindex hyphenation, disabling (@code{\%})
6506 To tell @code{gtroff} how to hyphenate words on the fly, use the
6507 @code{\%} escape, also known as the @dfn{hyphenation character}.
6508 Preceding a word with this character prevents it from being
6509 hyphenated; putting it inside a word indicates to @code{gtroff} that
6510 the word may be hyphenated at that point. Note that this mechanism
6511 only affects that one occurrence of the word; to change the
6512 hyphenation of a word for the entire document, use the @code{hw}
6515 The @code{\:} escape inserts a zero-width break point
6516 (that is, the word breaks but without adding a hyphen).
6519 ... check the /var/log/\:httpd/\:access_log file ...
6522 @cindex @code{\X}, followed by @code{\%}
6523 @cindex @code{\Y}, followed by @code{\%}
6524 @cindex @code{\%}, following @code{\X} or @code{\Y}
6525 Note that @code{\X} and @code{\Y} start a word, that is, the @code{\%}
6526 escape in (say) @w{@samp{\X'...'\%foobar}} and
6527 @w{@samp{\Y'...'\%foobar}} no longer prevents hyphenation but inserts
6528 a hyphenation point at the beginning of @samp{foobar}; most likely
6529 this isn't what you want to do.
6532 @Defreq {hc, [@Var{char}]}
6533 Change the hyphenation character to @var{char}. This character then
6534 works the same as the @code{\%} escape, and thus, no longer appears in
6535 the output. Without an argument, @code{hc} resets the hyphenation
6536 character to be @code{\%} (the default) only.
6538 The hyphenation character is associated with the current environment
6539 (@pxref{Environments}).
6542 @DefreqList {hpf, pattern_file}
6543 @DefreqItem {hpfa, pattern_file}
6544 @DefreqListEnd {hpfcode, a b [c d @dots{}]}
6545 @cindex hyphenation patterns (@code{hpf})
6546 @cindex patterns for hyphenation (@code{hpf})
6547 Read in a file of hyphenation patterns. This file is searched for in
6548 the same way as @file{@var{name}.tmac} (or @file{tmac.@var{name}}) is
6549 searched for if the @option{-m@var{name}} option is specified.
6551 It should have the same format as (simple) @TeX{} patterns files.
6552 More specifically, the following scanning rules are implemented.
6556 A percent sign starts a comment (up to the end of the line)
6557 even if preceded by a backslash.
6560 No support for `digraphs' like @code{\$}.
6563 @code{^^@var{xx}} (@var{x} is 0-9 or a-f) and @code{^^@var{x}} (character
6564 code of @var{x} in the range 0-127) are recognized; other use of @code{^}
6571 @code{hpf} checks for the expression @code{\patterns@{@dots{}@}}
6572 (possibly with whitespace before and after the braces).
6573 Everything between the braces is taken as hyphenation patterns.
6574 Consequently, @code{@{} and @code{@}} are not allowed in patterns.
6577 Similarly, @code{\hyphenation@{@dots{}@}} gives a list of hyphenation
6581 @code{\endinput} is recognized also.
6584 For backwards compatibility, if @code{\patterns} is missing,
6585 the whole file is treated as a list of hyphenation patterns
6586 (only recognizing the @code{%} character as the start of a comment).
6589 If no @code{hpf} request is specified (either in the document or in a
6590 macro package), @code{gtroff} won't hyphenate at all.
6592 The @code{hpfa} request appends a file of patterns to the current list.
6594 The @code{hpfcode} request defines mapping values for character codes in
6595 hyphenation patterns. @code{hpf} or @code{hpfa} then apply the mapping
6596 (after reading the patterns) before replacing or appending them to
6597 the current list of patterns. Its arguments are pairs of character codes
6598 -- integers from 0 to@tie{}255. The request maps character code@tie{}@var{a}
6599 to code@tie{}@var{b}, code@tie{}@var{c} to code@tie{}@var{d}, and so on. You
6600 can use character codes which would be invalid otherwise.
6606 The set of hyphenation patterns is associated with the current language
6607 set by the @code{hla} request. The @code{hpf} request is usually
6608 invoked by the @file{troffrc} or @file{troffrc-end} file; by default,
6609 @file{troffrc} loads hyphenation patterns and exceptions for American
6610 English (in files @file{hyphen.us} and @file{hyphenex.us}).
6612 A second call to @code{hpf} (for the same language) will replace the
6613 hyphenation patterns with the new ones.
6615 Invoking @code{hpf} causes an error if there is no current hyphenation
6619 @Defreq {hcode, c1 code1 c2 code2 @dots{}}
6620 @cindex hyphenation code (@code{hcode})
6621 @cindex code, hyphenation (@code{hcode})
6622 Set the hyphenation code of character @var{c1} to @var{code1}, that of
6623 @var{c2} to @var{code2}, etc. A hyphenation code must be a single
6624 input character (not a special character) other than a digit or a
6625 space. Initially each lower-case letter (@samp{a}-@samp{z}) has its
6626 hyphenation code set to itself, and each upper-case letter
6627 (@samp{A}-@samp{Z}) has a hyphenation code which is the lower-case
6630 This request is ignored if it has no parameter.
6633 @DefreqList {hym, [@Var{length}]}
6634 @DefregListEnd {.hym}
6635 @cindex hyphenation margin (@code{hym})
6636 @cindex margin for hyphenation (@code{hym})
6637 @cindex @code{ad} request, and hyphenation margin
6638 Set the (right) hyphenation margin to @var{length}. If the current
6639 adjustment mode is not @samp{b} or @samp{n}, the line is not
6640 hyphenated if it is shorter than @var{length}. Without an argument,
6641 the hyphenation margin is reset to its default value, which is@tie{}0.
6642 The default scaling indicator for this request is @samp{m}. The
6643 hyphenation margin is associated with the current environment
6644 (@pxref{Environments}).
6646 A negative argument resets the hyphenation margin to zero, emitting
6647 a warning of type @samp{range}.
6649 @cindex hyphenation margin register (@code{.hym})
6650 The current hyphenation margin is available in the @code{.hym} read-only
6654 @DefreqList {hys, [@Var{hyphenation_space}]}
6655 @DefregListEnd {.hys}
6656 @cindex hyphenation space (@code{hys})
6657 @cindex @code{ad} request, and hyphenation space
6658 Set the hyphenation space to @var{hyphenation_space}. If the current
6659 adjustment mode is @samp{b} or @samp{n}, don't hyphenate the line
6660 if it can be justified by adding no more than @var{hyphenation_space}
6661 extra space to each word space. Without argument, the hyphenation
6662 space is set to its default value, which is@tie{}0. The default
6663 scaling indicator for this request is @samp{m}. The hyphenation
6664 space is associated with the current environment
6665 (@pxref{Environments}).
6667 A negative argument resets the hyphenation space to zero, emitting a
6668 warning of type @samp{range}.
6670 @cindex hyphenation space register (@code{.hys})
6671 The current hyphenation space is available in the @code{.hys} read-only
6675 @Defreq {shc, [@Var{glyph}]}
6676 @cindex soft hyphen character, setting (@code{shc})
6677 @cindex character, soft hyphen, setting (@code{shc})
6678 @cindex glyph, soft hyphen (@code{hy})
6679 @cindex soft hyphen glyph (@code{hy})
6680 @cindex @code{char} request, and soft hyphen character
6681 @cindex @code{tr} request, and soft hyphen character
6682 Set the @dfn{soft hyphen character} to @var{glyph}.@footnote{@dfn{Soft
6683 hyphen character} is a misnomer since it is an output glyph.} If the
6684 argument is omitted, the soft hyphen character is set to the default
6685 glyph @code{\(hy} (this is the start-up value of @code{gtroff} also).
6686 The soft hyphen character is the glyph that is inserted when a word is
6687 hyphenated at a line break. If the soft hyphen character does not
6688 exist in the font of the character immediately preceding a potential
6689 break point, then the line is not broken at that point. Neither
6690 definitions (specified with the @code{char} request) nor translations
6691 (specified with the @code{tr} request) are considered when finding the
6692 soft hyphen character.
6695 @DefreqList {hla, language}
6696 @DefregListEnd {.hla}
6697 @cindex @code{hpf} request, and hyphenation language
6698 @cindex @code{hw} request, and hyphenation language
6701 Set the current hyphenation language to the string @var{language}.
6702 Hyphenation exceptions specified with the @code{hw} request and
6703 hyphenation patterns specified with the @code{hpf} and @code{hpfa}
6704 requests are both associated with the current hyphenation language.
6705 The @code{hla} request is usually invoked by the @file{troffrc} or the
6706 @file{troffrc-end} files; @file{troffrc} sets the default language to
6709 @cindex hyphenation language register (@code{.hla})
6710 The current hyphenation language is available as a string in the
6711 read-only number register @samp{.hla}.
6714 .ds curr_language \n[.hla]
6721 @c =====================================================================
6723 @node Manipulating Spacing, Tabs and Fields, Manipulating Hyphenation, gtroff Reference
6724 @section Manipulating Spacing
6725 @cindex manipulating spacing
6726 @cindex spacing, manipulating
6728 @Defreq {sp, [@Var{distance}]}
6729 Space downwards @var{distance}. With no argument it advances
6730 1@tie{}line. A negative argument causes @code{gtroff} to move up the page
6731 the specified distance. If the argument is preceded by a @samp{|}
6732 then @code{gtroff} moves that distance from the top of the page. This
6733 request causes a line break. The default scaling indicator is @samp{v}.
6735 If a vertical trap is sprung during execution of @code{sp}, the amount of
6736 vertical space after the trap is discarded. For example, this
6764 @cindex @code{sp} request, and traps
6765 @cindex discarded space in traps
6766 @cindex space, discarded, in traps
6767 @cindex traps, and discarded space
6768 The amount of discarded space is available in the number register
6771 To protect @code{sp} against vertical traps, use the @code{vpt} request:
6780 @DefreqList {ls, [@Var{nnn}]}
6782 @cindex double-spacing (@code{ls})
6783 Output @w{@var{nnn}@minus{}1} blank lines after each line of text.
6784 With no argument, @code{gtroff} uses the previous value before the
6785 last @code{ls} call.
6788 .ls 2 \" This causes double-spaced output
6789 .ls 3 \" This causes triple-spaced output
6790 .ls \" Again double-spaced
6793 The line spacing is associated with the current environment
6794 (@pxref{Environments}).
6796 @cindex line spacing register (@code{.L})
6797 The read-only number register @code{.L} contains the current line
6801 @xref{Changing Type Sizes}, for the requests @code{vs} and @code{pvs}
6802 as alternatives to @code{ls}.
6804 @DefescList {\\x, ', spacing, '}
6806 Sometimes, extra vertical spacing is only needed occasionally, e.g.@:
6807 to allow space for a tall construct (like an equation). The @code{\x}
6808 escape does this. The escape is given a numerical argument, usually
6809 enclosed in quotes (like @samp{\x'3p'}); the default scaling indicator
6810 is @samp{v}. If this number is positive extra vertical space is
6811 inserted below the current line. A negative number adds space above.
6812 If this escape is used multiple times on the same line, the maximum of
6815 @xref{Escapes}, for details on parameter delimiting characters.
6817 @cindex extra post-vertical line space register (@code{.a})
6818 The @code{.a} read-only number register contains the most recent
6819 (nonnegative) extra vertical line space.
6821 Using @code{\x} can be necessary in combination with the @code{\b}
6822 escape, as the following example shows.
6825 This is a test with the \[rs]b escape.
6827 This is a test with the \[rs]b escape.
6829 This is a test with \b'xyz'\x'-1m'\x'1m'.
6831 This is a test with the \[rs]b escape.
6833 This is a test with the \[rs]b escape.
6840 This is a test with the \b escape.
6841 This is a test with the \b escape.
6843 This is a test with y.
6845 This is a test with the \b escape.
6846 This is a test with the \b escape.
6852 @DefregListEnd {.ns}
6853 @cindex @code{sp} request, and no-space mode
6854 @cindex no-space mode (@code{ns})
6855 @cindex mode, no-space (@code{ns})
6856 @cindex blank lines, disabling
6857 @cindex lines, blank, disabling
6858 Enable @dfn{no-space mode}. In this mode, spacing (either via
6859 @code{sp} or via blank lines) is disabled. The @code{bp} request to
6860 advance to the next page is also disabled, except if it is accompanied
6861 by a page number (see @ref{Page Control}, for more information). This
6862 mode ends when actual text is output or the @code{rs} request is
6863 encountered which ends no-space mode. The read-only number register
6864 @code{.ns} is set to@tie{}1 as long as no-space mode is active.
6866 This request is useful for macros that conditionally
6867 insert vertical space before the text starts
6868 (for example, a paragraph macro could insert some space
6869 except when it is the first paragraph after a section header).
6873 @c =====================================================================
6875 @node Tabs and Fields, Character Translations, Manipulating Spacing, gtroff Reference
6876 @section Tabs and Fields
6877 @cindex tabs, and fields
6878 @cindex fields, and tabs
6880 @cindex @acronym{EBCDIC} encoding of a tab
6881 A tab character (@acronym{ASCII} char@tie{}9, @acronym{EBCDIC}
6882 char@tie{}5) causes a horizontal movement to the next tab stop (much
6883 like it did on a typewriter).
6886 @cindex tab character, non-interpreted (@code{\t})
6887 @cindex character, tab, non-interpreted (@code{\t})
6888 This escape is a non-interpreted tab character. In copy mode
6889 (@pxref{Copy-in Mode}), @code{\t} is the same as a real tab character.
6892 @DefreqList {ta, [@Var{n1} @Var{n2} @dots{} @Var{nn} @t{T} @Var{r1} @Var{r2} @dots{} @Var{rn}]}
6893 @DefregListEnd {.tabs}
6894 Change tab stop positions. This request takes a series of tab
6895 specifiers as arguments (optionally divided into two groups with the
6896 letter @samp{T}) which indicate where each tab stop is to be
6897 (overriding any previous settings).
6899 Tab stops can be specified absolutely, i.e., as the distance from the
6900 left margin. For example, the following sets 6@tie{}tab stops every
6904 .ta 1i 2i 3i 4i 5i 6i
6907 Tab stops can also be specified using a leading @samp{+}
6908 which means that the specified tab stop is set relative to
6909 the previous tab stop. For example, the following is equivalent to the
6913 .ta 1i +1i +1i +1i +1i +1i
6916 @code{gtroff} supports an extended syntax to specify repeat values after
6917 the @samp{T} mark (these values are always taken as relative) -- this is
6918 the usual way to specify tabs set at equal intervals. The following is,
6919 yet again, the same as the previous examples. It does even more since
6920 it defines an infinite number of tab stops separated by one inch.
6926 Now we are ready to interpret the full syntax given at the beginning:
6927 Set tabs at positions @var{n1}, @var{n2}, @dots{}, @var{nn} and then set
6928 tabs at @var{nn}+@var{r1}, @var{nn}+@var{r2}, @dots{}, @var{nn}+@var{rn}
6929 and then at @var{nn}+@var{rn}+@var{r1}, @var{nn}+@var{rn}+@var{r2},
6930 @dots{}, @var{nn}+@var{rn}+@var{rn}, and so on.
6932 Example: @samp{4c +6c T 3c 5c 2c} is equivalent to @samp{4c 10c 13c 18c
6933 20c 23c 28c 30c @dots{}}.
6935 The material in each tab column (i.e., the column between two tab stops)
6936 may be justified to the right or left or centered in the column. This
6937 is specified by appending @samp{R}, @samp{L}, or @samp{C} to the tab
6938 specifier. The default justification is @samp{L}. Example:
6948 The default unit of the @code{ta} request is @samp{m}.
6951 A tab stop is converted into a non-breakable horizontal movement which
6952 can be neither stretched nor squeezed. For example,
6961 creates a single line which is a bit longer than 10@tie{}inches (a string
6962 is used to show exactly where the tab characters are). Now consider the
6972 @code{gtroff} first converts the tab stops of the line into unbreakable
6973 horizontal movements, then splits the line after the second @samp{b}
6974 (assuming a sufficiently short line length). Usually, this isn't what
6978 Superfluous tabs (i.e., tab characters which do not correspond to a tab
6979 stop) are ignored except the first one which delimits the characters
6980 belonging to the last tab stop for right-justifying or centering.
6981 Consider the following example
6985 .ds ZZ foo\tbar\tfoobar
6986 .ds ZZZ foo\tbar\tfoo\tbar
6997 which produces the following output:
7006 The first line right-justifies the second `foo' relative to the tab
7007 stop. The second line right-justifies `foobar'. The third line finally
7008 right-justifies only `foo' because of the additional tab character which
7009 marks the end of the string belonging to the last defined tab stop.
7012 Tab stops are associated with the current environment
7013 (@pxref{Environments}).
7016 Calling @code{ta} without an argument removes all tab stops.
7019 @cindex tab stops, for TTY output devices
7020 The start-up value of @code{gtroff} is @w{@samp{T 0.8i}}.
7023 @cindex tab settings register (@code{.tabs})
7024 The read-only number register @code{.tabs} contains a string
7025 representation of the current tab settings suitable for use as an
7026 argument to the @code{ta} request.
7029 .ds tab-string \n[.tabs]
7034 @cindex @code{.S} register, Plan@tie{}9 alias for @code{.tabs}
7035 @cindex @code{.tabs} register, Plan@tie{}9 alias (@code{.S})
7036 The @code{troff} version of the Plan@tie{}9 operating system uses
7037 register @code{.S} for the same purpose.
7040 @Defreq {tc, [@Var{fill-glyph}]}
7041 @cindex tab repetition character (@code{tc})
7042 @cindex character, tab repetition (@code{tc})
7043 @cindex glyph, tab repetition (@code{tc})
7044 Normally @code{gtroff} fills the space to the next tab stop with
7045 whitespace. This can be changed with the @code{tc} request. With no
7046 argument @code{gtroff} reverts to using whitespace, which is the
7047 default. The value of this @dfn{tab repetition character} is
7048 associated with the current environment
7049 (@pxref{Environments}).@footnote{@dfn{Tab repetition character} is a
7050 misnomer since it is an output glyph.}
7053 @DefreqList {linetabs, n}
7054 @DefregListEnd {.linetabs}
7055 @cindex tab, line-tabs mode
7056 @cindex line-tabs mode
7057 @cindex mode, line-tabs
7058 If @var{n} is missing or not zero, enable @dfn{line-tabs} mode,
7059 or disable it otherwise (the default).
7060 In line-tabs mode, @code{gtroff} computes tab distances
7061 relative to the (current) output line instead of the input line.
7063 For example, the following code:
7076 in normal mode, results in the output
7083 in line-tabs mode, the same code outputs
7089 Line-tabs mode is associated with the current environment.
7090 The read-only register @code{.linetabs} is set to@tie{}1 if in line-tabs
7091 mode, and 0 in normal mode.
7099 @c ---------------------------------------------------------------------
7101 @node Leaders, Fields, Tabs and Fields, Tabs and Fields
7105 Sometimes it may may be desirable to use the @code{tc} request to fill a
7106 particular tab stop with a given glyph (for example dots in a table
7107 of contents), but also normal tab stops on the rest of the line. For
7108 this @code{gtroff} provides an alternate tab mechanism, called
7109 @dfn{leaders} which does just that.
7111 @cindex leader character
7112 A leader character (character code@tie{}1) behaves similarly to a tab
7113 character: It moves to the next tab stop. The only difference is that
7114 for this movement, the fill glyph defaults to a period character and
7118 @cindex leader character, non-interpreted (@code{\a})
7119 @cindex character, leader, non-interpreted (@code{\a})
7120 This escape is a non-interpreted leader character. In copy mode
7121 (@pxref{Copy-in Mode}), @code{\a} is the same as a real leader
7125 @Defreq {lc, [@Var{fill-glyph}]}
7126 @cindex leader repetition character (@code{lc})
7127 @cindex character, leader repetition (@code{lc})
7128 @cindex glyph, leader repetition (@code{lc})
7129 Declare the @dfn{leader repetition character}.@footnote{@dfn{Leader
7130 repetition character} is a misnomer since it is an output glyph.}
7131 Without an argument, leaders act the same as tabs (i.e., using
7132 whitespace for filling). @code{gtroff}'s start-up value is a dot
7133 (@samp{.}). The value of the leader repetition character is
7134 associated with the current environment (@pxref{Environments}).
7137 @cindex table of contents
7138 @cindex contents, table of
7139 For a table of contents, to name an example, tab stops may be defined so
7140 that the section number is one tab stop, the title is the second with
7141 the remaining space being filled with a line of dots, and then the page
7142 number slightly separated from the dots.
7145 .ds entry 1.1\tFoo\a\t12
7155 1.1 Foo.......................................... 12
7158 @c ---------------------------------------------------------------------
7160 @node Fields, , Leaders, Tabs and Fields
7164 @cindex field delimiting character (@code{fc})
7165 @cindex delimiting character, for fields (@code{fc})
7166 @cindex character, field delimiting (@code{fc})
7167 @cindex field padding character (@code{fc})
7168 @cindex padding character, for fields (@code{fc})
7169 @cindex character, field padding (@code{fc})
7170 @dfn{Fields} are a more general way of laying out tabular data. A field
7171 is defined as the data between a pair of @dfn{delimiting characters}.
7172 It contains substrings which are separated by @dfn{padding characters}.
7173 The width of a field is the distance on the @emph{input} line from the
7174 position where the field starts to the next tab stop. A padding
7175 character inserts stretchable space similar to @TeX{}'s @code{\hss}
7176 command (thus it can even be negative) to make the sum of all substring
7177 lengths plus the stretchable space equal to the field width. If more
7178 than one padding character is inserted, the available space is evenly
7179 distributed among them.
7181 @Defreq {fc, [@Var{delim-char} [@Var{padding-char}]]}
7182 Define a delimiting and a padding character for fields. If the latter
7183 is missing, the padding character defaults to a space character. If
7184 there is no argument at all, the field mechanism is disabled (which is
7185 the default). Note that contrary to e.g.@: the tab repetition
7186 character, delimiting and padding characters are @emph{not} associated
7187 to the current environment (@pxref{Environments}).
7200 and here the result:
7209 @c =====================================================================
7211 @node Character Translations, Troff and Nroff Mode, Tabs and Fields, gtroff Reference
7212 @section Character Translations
7213 @cindex character translations
7214 @cindex translations of characters
7216 @cindex control character, changing (@code{cc})
7217 @cindex character, control, changing (@code{cc})
7218 @cindex no-break control character, changing (@code{c2})
7219 @cindex character, no-break control, changing (@code{c2})
7220 @cindex control character, no-break, changing (@code{c2})
7221 The control character (@samp{.}) and the no-break control character
7222 (@samp{'}) can be changed with the @code{cc} and @code{c2} requests,
7225 @Defreq {cc, [@Var{c}]}
7226 Set the control character to@tie{}@var{c}. With no argument the default
7227 control character @samp{.} is restored. The value of the control
7228 character is associated with the current environment
7229 (@pxref{Environments}).
7232 @Defreq {c2, [@Var{c}]}
7233 Set the no-break control character to@tie{}@var{c}. With no argument the
7234 default control character @samp{'} is restored. The value of the
7235 no-break control character is associated with the current environment
7236 (@pxref{Environments}).
7240 @cindex disabling @code{\} (@code{eo})
7241 @cindex @code{\}, disabling (@code{eo})
7242 Disable the escape mechanism completely. After executing this
7243 request, the backslash character @samp{\} no longer starts an escape
7246 This request can be very helpful in writing macros since it is not
7247 necessary then to double the escape character. Here an example:
7250 .\" This is a simplified version of the
7251 .\" .BR request from the man macro package
7255 . while (\n[.$] >= 2) \@{\
7256 . as result \fB\$1\fR\$2
7259 . if \n[.$] .as result \fB\$1
7267 @Defreq {ec, [@Var{c}]}
7268 @cindex escape character, changing (@code{ec})
7269 @cindex character, escape, changing (@code{ec})
7270 Set the escape character to@tie{}@var{c}. With no argument the default
7271 escape character @samp{\} is restored. It can be also used to
7272 re-enable the escape mechanism after an @code{eo} request.
7274 Note that changing the escape character globally will likely break
7275 macro packages since @code{gtroff} has no mechanism to `intern' macros,
7276 i.e., to convert a macro definition into an internal form which is
7277 independent of its representation (@TeX{} has this mechanism).
7278 If a macro is called, it is executed literally.
7282 @DefreqListEnd {ecr, }
7283 The @code{ecs} request saves the current escape character
7284 in an internal register.
7285 Use this request in combination with the @code{ec} request to
7286 temporarily change the escape character.
7288 The @code{ecr} request restores the escape character
7289 saved with @code{ecs}.
7290 Without a previous call to @code{ecs}, this request
7291 sets the escape character to @code{\}.
7294 @DefescList {\\\\, , , }
7295 @DefescItem {\\e, , , }
7296 @DefescListEnd {\\E, , , }
7297 Print the current escape character (which is the backslash character
7298 @samp{\} by default).
7300 @code{\\} is a `delayed' backslash; more precisely, it is the default
7301 escape character followed by a backslash, which no longer has special
7302 meaning due to the leading escape character. It is @emph{not} an escape
7303 sequence in the usual sense! In any unknown escape sequence
7304 @code{\@var{X}} the escape character is ignored and @var{X} is printed.
7305 But if @var{X} is equal to the current escape character, no warning is
7308 As a consequence, only at top-level or in a diversion a backslash glyph is
7309 printed; in copy-in mode, it expands to a single backslash which then
7310 combines with the following character to an escape sequence.
7312 The @code{\E} escape differs from @code{\e} by printing an escape
7313 character that is not interpreted in copy mode.
7314 Use this to define strings with escapes that work
7315 when used in copy mode (for example, as a macro argument).
7316 The following example defines strings to begin and end
7320 .ds @{ \v'-.3m'\s'\En[.s]*60/100'
7324 Another example to demonstrate the differences between the various escape
7325 sequences, using a strange escape character, @samp{-}.
7337 The result is surprising for most users, expecting @samp{1} since
7338 @samp{foo} is a valid identifier. What has happened? As mentioned
7339 above, the leading escape character makes the following character
7340 ordinary. Written with the default escape character the sequence
7341 @samp{--} becomes @samp{\-} -- this is the minus sign.
7343 If the escape character followed by itself is a valid escape sequence,
7344 only @code{\E} yields the expected result:
7357 Similar to @code{\\}, the sequence @code{\.} isn't a real escape sequence.
7358 As before, a warning message is suppressed if the escape character is
7359 followed by a dot, and the dot itself is printed.
7376 The first backslash is consumed while the macro is read, and the second
7377 is swallowed while exexuting macro @code{foo}.
7380 A @dfn{translation} is a mapping of an input character to an output
7381 glyph. The mapping occurs at output time, i.e., the input character
7382 gets assigned the metric information of the mapped output character
7383 right before input tokens are converted to nodes (@pxref{Gtroff
7384 Internals}, for more on this process).
7386 @DefreqList {tr, @Var{a}@Var{b}@Var{c}@Var{d}@dots{}}
7387 @DefreqListEnd {trin, @Var{a}@Var{b}@Var{c}@Var{d}@dots{}}
7388 Translate character @var{a} to glyph@tie{}@var{b}, character @var{c} to
7389 glyph@tie{}@var{d}, etc. If there is an odd number of arguments, the
7390 last one is translated to an unstretchable space (@w{@samp{\ }}).
7392 The @code{trin} request is identical to @code{tr},
7393 but when you unformat a diversion with @code{asciify}
7394 it ignores the translation.
7395 @xref{Diversions}, for details about the @code{asciify} request.
7401 @cindex @code{\(}, and translations
7402 @cindex @code{\[}, and translations
7403 @cindex @code{\'}, and translations
7404 @cindex @code{\`}, and translations
7405 @cindex @code{\-}, and translations
7406 @cindex @code{\_}, and translations
7407 @cindex @code{\C}, and translations
7408 @cindex @code{\N}, and translations
7409 @cindex @code{char} request, and translations
7410 @cindex special characters
7411 @cindex character, special
7412 @cindex numbered glyph (@code{\N})
7413 @cindex glyph, numbered (@code{\N})
7414 Special characters (@code{\(@var{xx}}, @code{\[@var{xxx}]},
7415 @code{\C'@var{xxx}'}, @code{\'}, @code{\`}, @code{\-}, @code{\_}),
7416 glyphs defined with the @code{char} request, and numbered glyphs
7417 (@code{\N'@var{xxx}'}) can be translated also.
7420 @cindex @code{\e}, and translations
7421 The @code{\e} escape can be translated also.
7424 @cindex @code{\%}, and translations
7425 @cindex @code{\~}, and translations
7426 Characters can be mapped onto the @code{\%} and @code{\~} escapes (but
7427 @code{\%} and @code{\~} can't be mapped onto another glyph).
7430 @cindex backspace character, and translations
7431 @cindex character, backspace, and translations
7432 @cindex leader character, and translations
7433 @cindex character, leader, and translations
7434 @cindex newline character, and translations
7435 @cindex character, newline, and translations
7436 @cindex tab character, and translations
7437 @cindex character, tab, and translations
7438 @cindex @code{\a}, and translations
7439 @cindex @code{\t}, and translations
7440 The following characters can't be translated: space (with one exception,
7441 see below), backspace, newline, leader (and @code{\a}), tab (and
7445 @cindex @code{shc} request, and translations
7446 Translations are not considered for finding the soft hyphen character
7447 set with the @code{shc} request.
7450 @cindex @code{\&}, and translations
7451 The pair @samp{@var{c}\&} (this is an arbitrary character@tie{}@var{c}
7452 followed by the zero width space character) maps this character to nothing.
7461 It is even possible to map the space character to nothing:
7470 As shown in the example, the space character can't be the first
7471 character/glyph pair as an argument of @code{tr}. Additionally, it is
7472 not possible to map the space character to any other glyph; requests
7473 like @w{@samp{.tr aa x}} undo @w{@samp{.tr aa \&}} instead.
7475 If justification is active, lines are justified in spite of the
7476 `empty' space character (but there is no minimal distance, i.e.@: the
7477 space character, between words).
7480 After an output glyph has been constructed (this happens at the
7481 moment immediately before the glyph is appended to an output
7482 glyph list, either by direct output, in a macro, diversion, or
7483 string), it is no longer affected by @code{tr}.
7486 Translating character to glyphs where one of them or both are
7487 undefined is possible also; @code{tr} does not check whether the
7488 entities in its argument do exist.
7490 @xref{Gtroff Internals}.
7493 @code{troff} no longer has a hard-coded dependency on @w{Latin-1};
7494 all @code{char@var{XXX}} entities have been removed from the font
7495 description files. This has a notable consequence which shows up in
7496 warnings like @code{can't find character with input code @var{XXX}}
7497 if the @code{tr} request isn't handled properly.
7499 Consider the following translation:
7506 This maps input character @code{@'e} onto glyph @code{@'E}, which is
7507 identical to glyph @code{char201}. But this glyph intentionally
7508 doesn't exist! Instead, @code{\[char201]} is treated as an input
7509 character entity and is by default mapped onto @code{\['E]}, and
7510 @code{gtroff} doesn't handle translations of translations.
7512 The right way to write the above translation is
7519 With other words, the first argument of @code{tr} should be an input
7520 character or entity, and the second one a glyph entity.
7523 Without an argument, the @code{tr} request is ignored.
7527 @Defreq {trnt, @Var{a}@Var{b}@Var{c}@Var{d}@dots{}}
7528 @cindex @code{\!}, and @code{trnt}
7529 @code{trnt} is the same as the @code{tr} request except that the
7530 translations do not apply to text that is transparently throughput
7531 into a diversion with @code{\!}. @xref{Diversions}, for more
7545 prints @samp{b} to the standard error stream; if @code{trnt} is used
7546 instead of @code{tr} it prints @samp{a}.
7550 @c =====================================================================
7552 @node Troff and Nroff Mode, Line Layout, Character Translations, gtroff Reference
7553 @section Troff and Nroff Mode
7559 Originally, @code{nroff} and @code{troff} were two separate programs,
7560 the former for TTY output, the latter for everything else. With GNU
7561 @code{troff}, both programs are merged into one executable, sending
7562 its output to a device driver (@code{grotty} for TTY devices,
7563 @code{grops} for @sc{PostScript}, etc.) which interprets the
7564 intermediate output of @code{gtroff}. For @acronym{UNIX} @code{troff}
7565 it makes sense to talk about @dfn{Nroff mode} and @dfn{Troff mode}
7566 since the differences are hardcoded. For GNU @code{troff}, this
7567 distinction is not appropriate because @code{gtroff} simply takes the
7568 information given in the font files for a particular device without
7569 handling requests specially if a TTY output device is used.
7571 Usually, a macro package can be used with all output devices.
7572 Nevertheless, it is sometimes necessary to make a distinction between
7573 TTY and non-TTY devices: @code{gtroff} provides two built-in
7574 conditions @samp{n} and @samp{t} for the @code{if}, @code{ie}, and
7575 @code{while} requests to decide whether @code{gtroff} shall behave
7576 like @code{nroff} or like @code{troff}.
7581 Make the @samp{t} built-in condition true (and the @samp{n} built-in
7582 condition false) for @code{if}, @code{ie}, and @code{while}
7583 conditional requests. This is the default if @code{gtroff}
7584 (@emph{not} @code{groff}) is started with the @option{-R} switch to
7585 avoid loading of the start-up files @file{troffrc} and
7586 @file{troffrc-end}. Without @option{-R}, @code{gtroff} stays in troff
7587 mode if the output device is not a TTY (e.g.@: `ps').
7592 Make the @samp{n} built-in condition true (and the @samp{t} built-in
7593 condition false) for @code{if}, @code{ie}, and @code{while}
7594 conditional requests. This is the default if @code{gtroff} uses a TTY
7595 output device; the code for switching to nroff mode is in the file
7596 @file{tty.tmac} which is loaded by the start-up file @code{troffrc}.
7599 @xref{Conditionals and Loops}, for more details on built-in
7603 @c =====================================================================
7605 @node Line Layout, Line Control, Troff and Nroff Mode, gtroff Reference
7606 @section Line Layout
7608 @cindex layout, line
7610 @cindex dimensions, line
7611 @cindex line dimensions
7612 The following drawing shows the dimensions which @code{gtroff} uses for
7613 placing a line of output onto the page. They are labeled with the
7614 request which manipulates each dimension.
7618 |<-----------ll------------>|
7619 +----+----+----------------------+----+
7621 +----+----+----------------------+----+
7623 |<--------paper width---------------->|
7627 These dimensions are:
7631 @cindex left margin (@code{po})
7632 @cindex margin, left (@code{po})
7633 @cindex page offset (@code{po})
7634 @cindex offset, page (@code{po})
7635 @dfn{Page offset} -- this is the leftmost position of text on the final
7636 output, defining the @dfn{left margin}.
7639 @cindex indentation (@code{in})
7640 @cindex line indentation (@code{in})
7641 @dfn{Indentation} -- this is the distance from the left margin where
7645 @cindex line length (@code{ll})
7646 @cindex length of line (@code{ll})
7647 @dfn{Line length} -- this is the distance from the left margin to right
7651 A simple demonstration:
7655 This is text without indentation.
7656 The line length has been set to 3\~inch.
7659 Now the left and right margins are both increased.
7662 Calling .in and .ll without parameters restore
7663 the previous values.
7669 This is text without indenta-
7670 tion. The line length has
7675 Calling .in and .ll without
7676 parameters restore the previ-
7680 @DefreqList {po, [@Var{offset}]}
7681 @DefreqItem {po, @t{+}@Var{offset}}
7682 @DefreqItem {po, @t{-}@Var{offset}}
7685 Set horizontal page offset to @var{offset} (or increment or decrement
7686 the current value by @var{offset}). Note that this request does not
7687 cause a break, so changing the page offset in the middle of text being
7688 filled may not yield the expected result. The initial value is
7689 1@dmn{i}. For TTY output devices, it is set to 0 in the startup file
7690 @file{troffrc}; the default scaling indicator is @samp{m} (and
7691 not @samp{v} as incorrectly documented in the original
7692 @acronym{UNIX} troff manual).
7694 The current page offset can be found in the read-only number register
7697 If @code{po} is called without an argument, the page offset is reset to
7698 the previous value before the last call to @code{po}.
7713 @DefreqList {in, [@Var{indent}]}
7714 @DefreqItem {in, @t{+}@Var{indent}}
7715 @DefreqItem {in, @t{-}@Var{indent}}
7717 Set indentation to @var{indent} (or increment or decrement the
7718 current value by @var{indent}). This request causes a break.
7719 Initially, there is no indentation.
7721 If @code{in} is called without an argument, the indentation is reset to
7722 the previous value before the last call to @code{in}. The default
7723 scaling indicator is @samp{m}.
7725 The indentation is associated with the current environment
7726 (@pxref{Environments}).
7728 If a negative indentation value is specified (which is not allowed),
7729 @code{gtroff} emits a warning of type @samp{range} and sets the
7730 indentation to zero.
7732 The effect of @code{in} is delayed until a partially collected line (if
7733 it exists) is output. A temporary indent value is reset to zero also.
7735 The current indentation (as set by @code{in}) can be found in the
7736 read-only number register @samp{.i}.
7739 @DefreqList {ti, offset}
7740 @DefreqItem {ti, @t{+}@Var{offset}}
7741 @DefreqItem {ti, @t{-}@Var{offset}}
7742 @DefregListEnd {.in}
7743 Temporarily indent the next output line by @var{offset}. If an
7744 increment or decrement value is specified, adjust the temporary
7745 indentation relative to the value set by the @code{in} request.
7747 This request causes a break; its value is associated with the current
7748 environment (@pxref{Environments}). The default scaling indicator
7749 is @samp{m}. A call of @code{ti} without an argument is ignored.
7751 If the total indentation value is negative (which is not allowed),
7752 @code{gtroff} emits a warning of type @samp{range} and sets the
7753 temporary indentation to zero. `Total indentation' is either
7754 @var{offset} if specified as an absolute value, or the temporary plus
7755 normal indentation, if @var{offset} is given as a relative value.
7757 The effect of @code{ti} is delayed until a partially collected line (if
7758 it exists) is output.
7760 The read-only number register @code{.in} is the indentation that applies
7761 to the current output line.
7763 The difference between @code{.i} and @code{.in} is that the latter takes
7764 into account whether a partially collected line still uses the old
7765 indentation value or a temporary indentation value is active.
7768 @DefreqList {ll, [@Var{length}]}
7769 @DefreqItem {ll, @t{+}@Var{length}}
7770 @DefreqItem {ll, @t{-}@Var{length}}
7772 @DefregListEnd {.ll}
7773 Set the line length to @var{length} (or increment or decrement the
7774 current value by @var{length}). Initially, the line length is set to
7775 6.5@dmn{i}. The effect of @code{ll} is delayed until a partially
7776 collected line (if it exists) is output. The default scaling
7777 indicator is @samp{m}.
7779 If @code{ll} is called without an argument, the line length is reset to
7780 the previous value before the last call to @code{ll}. If a negative
7781 line length is specified (which is not allowed), @code{gtroff} emits a
7782 warning of type @samp{range} and sets the line length to zero.
7784 The line length is associated with the current environment
7785 (@pxref{Environments}).
7787 @cindex line length register (@code{.l})
7788 The current line length (as set by @code{ll}) can be found in the
7789 read-only number register @samp{.l}. The read-only number register
7790 @code{.ll} is the line length that applies to the current output line.
7792 Similar to @code{.i} and @code{.in}, the difference between @code{.l}
7793 and @code{.ll} is that the latter takes into account whether a partially
7794 collected line still uses the old line length value.
7798 @c =====================================================================
7800 @node Line Control, Page Layout, Line Layout, gtroff Reference
7801 @section Line Control
7802 @cindex line control
7803 @cindex control, line
7805 It is important to understand how @code{gtroff} handles input and output
7808 Many escapes use positioning relative to the input line. For example,
7812 This is a \h'|1.2i'test.
7827 The main usage of this feature is to define macros which act exactly
7828 at the place where called.
7831 .\" A simple macro to underline a word
7833 . nop \\$1\l'|0\[ul]'
7838 In the above example, @samp{|0} specifies a negative distance from the
7839 current position (at the end of the just emitted argument @code{\$1}) back
7840 to the beginning of the input line. Thus, the @samp{\l} escape draws a
7841 line from right to left.
7843 @cindex input line continuation (@code{\})
7844 @cindex line, input, continuation (@code{\})
7845 @cindex continuation, input line (@code{\})
7846 @cindex output line, continuation (@code{\c})
7847 @cindex line, output, continuation (@code{\c})
7848 @cindex continuation, output line (@code{\c})
7849 @cindex interrupted line
7850 @cindex line, interrupted
7851 @code{gtroff} makes a difference between input and output line
7852 continuation; the latter is also called @dfn{interrupting} a line.
7854 @DefescList {\\@key{RET}, , ,}
7855 @DefescItem {\\c, , ,}
7856 @DefregListEnd{.int}
7857 Continue a line. @code{\@key{RET}} (this is a backslash at the end
7858 of a line immediately followed by a newline) works on the input level,
7859 suppressing the effects of the following newline in the input.
7864 @result{} This is a .test
7867 The @samp{|} operator is also affected.
7869 @cindex @code{\R}, after @code{\c}
7870 @code{\c} works on the output level. Anything after this escape on the
7871 same line is ignored, except @code{\R} which works as usual. Anything
7872 before @code{\c} on the same line will be appended to the current partial
7873 output line. The next non-command line after an interrupted line counts
7874 as a new input line.
7876 The visual results depend on whether no-fill mode is active.
7880 @cindex @code{\c}, and no-fill mode
7881 @cindex no-fill mode, and @code{\c}
7882 @cindex mode, no-fill, and @code{\c}
7883 If no-fill mode is active (using the @code{nf} request), the next input
7884 text line after @code{\c} will be handled as a continuation of the same
7891 @result{} This is a test.
7895 @cindex @code{\c}, and fill mode
7896 @cindex fill mode, and @code{\c}
7897 @cindex mode, fill, and @code{\c}
7898 If fill mode is active (using the @code{fi} request), a word interrupted
7899 with @code{\c} will be continued with the text on the next input text line,
7900 without an intervening space.
7905 @result{} This is a test.
7909 Note that an intervening control line which causes a break is stronger
7910 than @code{\c}, flushing out the current partial line in the usual way.
7912 @cindex interrupted line register (@code{.int})
7913 The @code{.int} register contains a positive value
7914 if the last output line was interrupted with @code{\c}; this is
7915 associated with the current environment (@pxref{Environments}).
7918 @c =====================================================================
7920 @node Page Layout, Page Control, Line Control, gtroff Reference
7921 @section Page Layout
7923 @cindex layout, page
7925 @code{gtroff} provides some very primitive operations for controlling
7928 @DefreqList {pl, [@Var{length}]}
7929 @DefreqItem {pl, @t{+}@Var{length}}
7930 @DefreqItem {pl, @t{-}@Var{length}}
7932 @cindex page length (@code{pl})
7933 @cindex length of page (@code{pl})
7934 Set the @dfn{page length} to @var{length} (or increment or decrement
7935 the current value by @var{length}). This is the length of the
7936 physical output page. The default scaling indicator is @samp{v}.
7938 @cindex page length register (@code{.p})
7939 The current setting can be found in the read-only number register
7944 @cindex bottom margin
7945 @cindex margin, bottom
7946 Note that this only specifies the size of the page, not the top and
7947 bottom margins. Those are not set by @code{gtroff} directly.
7948 @xref{Traps}, for further information on how to do this.
7950 Negative @code{pl} values are possible also, but not very useful: No
7951 trap is sprung, and each line is output on a single page (thus
7952 suppressing all vertical spacing).
7954 If no argument or an invalid argument is given, @code{pl} sets the page
7955 length to 11@dmn{i}.
7961 @code{gtroff} provides several operations which help in setting up top
7962 and bottom titles (or headers and footers).
7964 @Defreq {tl, @t{'}@Var{left}@t{'}@Var{center}@t{'}@Var{right}@t{'}}
7965 @cindex title line (@code{tl})
7966 @cindex three-part title (@code{tl})
7967 @cindex page number character (@code{%})
7968 Print a @dfn{title line}. It consists of three parts: a left
7969 justified portion, a centered portion, and a right justified portion.
7970 The argument separator @samp{'} can be replaced with any character not
7971 occurring in the title line. The @samp{%} character is replaced with
7972 the current page number. This character can be changed with the
7973 @code{pc} request (see below).
7975 Without argument, @code{tl} is ignored.
7981 A title line is not restricted to the top or bottom of a page.
7984 @code{tl} prints the title line immediately, ignoring a partially filled
7985 line (which stays untouched).
7988 It is not an error to omit closing delimiters. For example,
7989 @w{@samp{.tl /foo}} is equivalent to @w{@samp{.tl /foo///}}: It prints a
7990 title line with the left justified word @samp{foo}; the centered and
7991 right justfied parts are empty.
7994 @code{tl} accepts the same parameter delimiting characters as the
7995 @code{\A} escape; see @ref{Escapes}.
7999 @DefreqList {lt, [@Var{length}]}
8000 @DefreqItem {lt, @t{+}@Var{length}}
8001 @DefreqItem {lt, @t{-}@Var{length}}
8002 @DefregListEnd {.lt}
8003 @cindex length of title line (@code{lt})
8004 @cindex title line, length (@code{lt})
8005 @cindex title line length register (@code{.lt})
8006 The title line is printed using its own line length, which is
8007 specified (or incremented or decremented) with the @code{lt} request.
8008 Initially, the title line length is set to 6.5@dmn{i}. If a negative
8009 line length is specified (which is not allowed), @code{gtroff} emits a
8010 warning of type @samp{range} and sets the title line length to zero.
8011 The default scaling indicator is @samp{m}. If @code{lt} is called
8012 without an argument, the title length is reset to the previous value
8013 before the last call to @code{lt}.
8015 The current setting of this is available in the @code{.lt} read-only
8016 number register; it is associated with the current environment
8017 (@pxref{Environments}).
8020 @DefreqList {pn, page}
8021 @DefreqItem {pn, @t{+}@Var{page}}
8022 @DefreqItem {pn, @t{-}@Var{page}}
8023 @DefregListEnd {.pn}
8024 @cindex page number (@code{pn})
8025 @cindex number, page (@code{pn})
8026 Change (increase or decrease) the page number of the @emph{next} page.
8027 The only argument is the page number; the request is ignored without a
8030 The read-only number register @code{.pn} contains the number of the next
8031 page: either the value set by a @code{pn} request, or the number of the
8032 current page plus@tie{}1.
8035 @Defreq {pc, [@Var{char}]}
8036 @cindex changing the page number character (@code{pc})
8037 @cindex page number character, changing (@code{pc})
8039 Change the page number character (used by the @code{tl} request) to a
8040 different character. With no argument, this mechanism is disabled.
8041 Note that this doesn't affect the number register@tie{}@code{%}.
8047 @c =====================================================================
8049 @node Page Control, Fonts and Symbols, Page Layout, gtroff Reference
8050 @section Page Control
8051 @cindex page control
8052 @cindex control, page
8054 @DefreqList {bp, [@Var{page}]}
8055 @DefreqItem {bp, @t{+}@Var{page}}
8056 @DefreqItem {bp, @t{-}@Var{page}}
8058 @cindex new page (@code{bp})
8059 @cindex page, new (@code{bp})
8060 Stop processing the current page and move to the next page. This
8061 request causes a break. It can also take an argument to set
8062 (increase, decrease) the page number of the next page (which actually
8063 becomes the current page after @code{bp} has finished). The
8064 difference between @code{bp} and @code{pn} is that @code{pn} does not
8065 cause a break or actually eject a page. @xref{Page Layout}.
8068 .de newpage \" define macro
8070 'sp .5i \" vertical space
8071 .tl 'left top'center top'right top' \" title
8072 'sp .3i \" vertical space
8076 @cindex @code{bp} request, and top-level diversion
8077 @cindex top-level diversion, and @code{bp}
8078 @cindex diversion, top-level, and @code{bp}
8079 @code{bp} has no effect if not called within the top-level diversion
8080 (@pxref{Diversions}).
8082 @cindex page number register (@code{%})
8083 @cindex current page number (@code{%})
8084 The read-write register@tie{}@code{%} holds the current page number.
8086 The number register @code{.pe} is set to@tie{}1 while @code{bp} is
8087 active. @xref{Page Location Traps}.
8090 @Defreq {ne, [@Var{space}]}
8091 @cindex orphan lines, preventing with @code{ne}
8092 @cindex conditional page break (@code{ne})
8093 @cindex page break, conditional (@code{ne})
8094 It is often necessary to force a certain amount of space before a new
8095 page occurs. This is most useful to make sure that there is not a
8096 single @dfn{orphan} line left at the bottom of a page. The @code{ne}
8097 request ensures that there is a certain distance, specified by the
8098 first argument, before the next page is triggered (see @ref{Traps},
8099 for further information). The default scaling indicator for @code{ne}
8100 is @samp{v}; the default value of @var{space} is@tie{}1@dmn{v} if no
8103 For example, to make sure that no fewer than 2@tie{}lines get orphaned,
8104 do the following before each paragraph:
8111 @code{ne} will then automatically cause a page break if there is space
8115 @DefreqList {sv, [@Var{space}]}
8116 @DefreqListEnd {os, }
8117 @cindex @code{ne} request, comparison with @code{sv}
8118 @code{sv} is similar to the @code{ne} request; it reserves the
8119 specified amount of vertical space. If the desired amount of space
8120 exists before the next trap (or the bottom page boundary if no trap is
8121 set), the space is output immediately (ignoring a partially filled line
8122 which stays untouched). If there is not enough space, it is stored for
8123 later output via the @code{os} request. The default value is@tie{}1@dmn{v}
8124 if no argument is given; the default scaling indicator is @samp{v}.
8126 @cindex @code{sv} request, and no-space mode
8127 @cindex @code{os} request, and no-space mode
8128 Both @code{sv} and @code{os} ignore no-space mode. While the @code{sv}
8129 request allows negative values for @var{space}, @code{os} will ignore
8134 @cindex current vertical position (@code{nl})
8135 @cindex vertical position, current (@code{nl})
8136 @cindex position, vertical, current (@code{nl})
8137 This register contains the current vertical position. If the vertical
8138 position is zero and the top of page transition hasn't happened yet,
8139 @code{nl} is set to negative value. @code{gtroff} itself does this at
8140 the very beginning of a document before anything has been printed, but
8141 the main usage is to plant a header trap on a page if this page has
8144 Consider the following:
8176 Without resetting @code{nl} to a negative value, the just planted trap
8177 would be active beginning with the @emph{next} page, not the current
8180 @xref{Diversions}, for a comparison with the @code{.h} and @code{.d}
8184 @c =====================================================================
8186 @node Fonts and Symbols, Sizes, Page Control, gtroff Reference
8187 @section Fonts and Symbols
8190 @code{gtroff} can switch fonts at any point in the text.
8192 The basic set of fonts is @samp{R}, @samp{I}, @samp{B}, and @samp{BI}.
8193 These are Times Roman, Italic, Bold, and Bold Italic. For non-TTY
8194 devices, there is also at least one symbol font which contains various
8195 special symbols (Greek, mathematics).
8203 * Artificial Fonts::
8204 * Ligatures and Kerning::
8207 @c ---------------------------------------------------------------------
8209 @node Changing Fonts, Font Families, Fonts and Symbols, Fonts and Symbols
8210 @subsection Changing Fonts
8213 @DefreqList {ft, [@Var{font}]}
8214 @DefescItem {\\f, , f, }
8215 @DefescItem {\\f, @lparen{}, fn, }
8216 @DefescListEnd {\\f, @lbrack{}, font, @rbrack}
8217 @cindex changing fonts (@code{ft}, @code{\f})
8218 @cindex fonts, changing (@code{ft}, @code{\f})
8219 @cindex @code{sty} request, and changing fonts
8220 @cindex @code{fam} request, and changing fonts
8221 @cindex @code{\F}, and changing fonts
8225 The @code{ft} request and the @code{\f} escape change the current font
8226 to @var{font} (one-character name@tie{}@var{f}, two-character name
8229 If @var{font} is a style name (as set with the @code{sty} request or
8230 with the @code{styles} command in the @file{DESC} file), use it within
8231 the current font family (as set with the @code{fam} request, @code{\F}
8232 escape, or with the @code{family} command in the @file{DESC} file).
8234 @cindex previous font (@code{ft}, @code{\f[]}, @code{\fP})
8235 @cindex font, previous (@code{ft}, @code{\f[]}, @code{\fP})
8236 With no argument or using @samp{P} as an argument, @code{.ft} switches
8237 to the previous font. Use @code{\f[]} to do this with the escape. The
8238 old syntax forms @code{\fP} or @code{\f[P]} are also supported.
8240 Fonts are generally specified as upper-case strings, which are usually
8241 1@tie{}to 4 characters representing an abbreviation or acronym of the
8242 font name. This is no limitation, just a convention.
8244 The example below produces two identical lines.
8253 eggs, bacon, \fBspam\fP and sausage.
8256 Note that @code{\f} doesn't produce an input token in @code{gtroff}.
8257 As a consequence, it can be used in requests like @code{mc} (which
8258 expects a single character as an argument) to change the font on
8265 @xref{Font Positions}, for an alternative syntax.
8268 @Defreq {ftr, f [@Var{g}]}
8269 @cindex @code{ft} request, and font translations
8270 @cindex @code{ul} request, and font translations
8271 @cindex @code{bd} request, and font translations
8272 @cindex @code{\f}, and font translations
8273 @cindex @code{cs} request, and font translations
8274 @cindex @code{tkf} request, and font translations
8275 @cindex @code{special} request, and font translations
8276 @cindex @code{fspecial} request, and font translations
8277 @cindex @code{fp} request, and font translations
8278 @cindex @code{sty} request, and font translations
8279 Translate font@tie{}@var{f} to font@tie{}@var{g}. Whenever a font
8280 named@tie{}@var{f} is referred to in a @code{\f} escape sequence, or in the
8281 @code{ft}, @code{ul}, @code{bd}, @code{cs}, @code{tkf},
8282 @code{special}, @code{fspecial}, @code{fp}, or @code{sty} requests,
8283 font@tie{}@var{g} is used. If @var{g} is missing or equal to@tie{}@var{f}
8284 the translation is undone.
8287 @c ---------------------------------------------------------------------
8289 @node Font Families, Font Positions, Changing Fonts, Fonts and Symbols
8290 @subsection Font Families
8291 @cindex font families
8292 @cindex families, font
8294 @cindex styles, font
8296 Due to the variety of fonts available, @code{gtroff} has added the
8297 concept of @dfn{font families} and @dfn{font styles}. The fonts are
8298 specified as the concatenation of the font family and style. Specifying
8299 a font without the family part causes @code{gtroff} to use that style of
8302 @cindex PostScript fonts
8303 @cindex fonts, PostScript
8304 Currently, fonts for the devices @option{-Tps}, @option{-Tdvi}, and
8305 @option{-Tlbp} are set up to this mechanism.
8306 By default, @code{gtroff} uses the Times family with the four styles
8307 @samp{R}, @samp{I}, @samp{B}, and @samp{BI}.
8309 This way, it is possible to use the basic four fonts and to select a
8310 different font family on the command line (@pxref{Groff Options}).
8312 @DefreqList {fam, [@Var{family}]}
8314 @DefescItem {\\F, , f, }
8315 @DefescItem {\\F, @lparen{}, fm, }
8316 @DefescItem {\\F, @lbrack{}, family, @rbrack}
8317 @DefregListEnd {.fn}
8318 @cindex changing font family (@code{fam}, @code{\F})
8319 @cindex font family, changing (@code{fam}, @code{\F})
8320 Switch font family to @var{family} (one-character name@tie{}@var{f},
8321 two-character name @var{fm}). If no argument is given, switch
8322 back to the previous font family. Use @code{\F[]} to do this with the
8323 escape. Note that @code{\FP} doesn't work; it selects font family
8326 The value at start-up is @samp{T}.
8327 The current font family is available in the read-only number register
8328 @samp{.fam} (this is a string-valued register); it is associated with
8329 the current environment.
8333 .fam H \" helvetica family
8334 spam, \" used font is family H + style R = HR
8335 .ft B \" family H + style B = font HB
8337 .fam T \" times family
8338 spam, \" used font is family T + style B = TB
8339 .ft AR \" font AR (not a style)
8341 .ft R \" family T + style R = font TR
8345 Note that @code{\F} doesn't produce an input token in @code{gtroff}.
8346 As a consequence, it can be used in requests like @code{mc} (which
8347 expects a single character as an argument) to change the font family on
8354 The @samp{.fn} register contains the current @dfn{real font name}
8355 of the current font.
8356 This is a string-valued register.
8357 If the current font is a style, the value of @code{\n[.fn]}
8358 is the proper concatenation of family and style name.
8361 @Defreq {sty, n style}
8362 @cindex changing font style (@code{sty})
8363 @cindex font style, changing (@code{sty})
8364 @cindex @code{cs} request, and font styles
8365 @cindex @code{bd} request, and font styles
8366 @cindex @code{tkf} request, and font styles
8367 @cindex @code{uf} request, and font styles
8368 @cindex @code{fspecial} request, and font styles
8369 Associate @var{style} with font position@tie{}@var{n}. A font position
8370 can be associated either with a font or with a style. The current
8371 font is the index of a font position and so is also either a font or a
8372 style. If it is a style, the font that is actually used is the font
8373 which name is the concatenation of the name of the current
8374 family and the name of the current style. For example, if the current
8375 font is@tie{}1 and font position@tie{}1 is associated with style
8376 @samp{R} and the current font family is @samp{T}, then font
8377 @samp{TR} will be used. If the current font is not a style, then the
8378 current family is ignored. If the requests @code{cs}, @code{bd},
8379 @code{tkf}, @code{uf}, or @code{fspecial} are applied to a style,
8380 they will instead be applied to the member of the current family
8381 corresponding to that style.
8383 @var{n}@tie{}must be a non-negative integer value.
8387 The default family can be set with the @option{-f} option
8388 (@pxref{Groff Options}). The @code{styles} command in the @file{DESC}
8389 file controls which font positions (if any) are initially associated
8390 with styles rather than fonts. For example, the default setting for
8391 @sc{PostScript} fonts
8407 @code{fam} and @code{\F} always check whether the current font position
8408 is valid; this can give surprising results if the current font position is
8409 associated with a style.
8411 In the following example, we want to access the @sc{PostScript} font
8412 @code{FooBar} from the font family @code{Foo}:
8417 @result{} warning: can't find font `FooR'
8421 The default font position at start-up is@tie{}1; for the
8422 @sc{PostScript} device, this is associated with style @samp{R}, so
8423 @code{gtroff} tries to open @code{FooR}.
8425 A solution to this problem is to use a dummy font like the following:
8428 .fp 0 dummy TR \" set up dummy font at position 0
8429 .sty \n[.fp] Bar \" register style `Bar'
8430 .ft 0 \" switch to font at position 0
8431 .fam Foo \" activate family `Foo'
8432 .ft Bar \" switch to font `FooBar'
8435 @xref{Font Positions}.
8438 @c ---------------------------------------------------------------------
8440 @node Font Positions, Using Symbols, Font Families, Fonts and Symbols
8441 @subsection Font Positions
8442 @cindex font positions
8443 @cindex positions, font
8445 For the sake of old phototypesetters and compatibility with old versions
8446 of @code{troff}, @code{gtroff} has the concept of font @dfn{positions},
8447 on which various fonts are mounted.
8449 @DefreqList {fp, pos font [@Var{external-name}]}
8451 @DefregListEnd {.fp}
8452 @cindex mounting font (@code{fp})
8453 @cindex font, mounting (@code{fp})
8454 Mount font @var{font} at position @var{pos} (which must be a
8455 non-negative integer). This numeric position can then be referred to
8456 with font changing commands. When @code{gtroff} starts it is using
8457 font position@tie{}1 (which must exist; position@tie{}0 is unused
8458 usually at start-up).
8460 @cindex font position register (@code{.f})
8461 The current font in use, as a font position, is available in the
8462 read-only number register @samp{.f}. This can be useful to remember the
8463 current font for later recall. It is associated with the current
8464 environment (@pxref{Environments}).
8467 .nr save-font \n[.f]
8469 ... text text text ...
8473 @cindex next free font position register (@code{.fp})
8474 The number of the next free font position is available in the read-only
8475 number register @samp{.fp}. This is useful when mounting a new font,
8479 .fp \n[.fp] NEATOFONT
8482 @pindex DESC@r{, and font mounting}
8483 Fonts not listed in the @file{DESC} file are automatically mounted on
8484 the next available font position when they are referenced. If a font
8485 is to be mounted explicitly with the @code{fp} request on an unused
8486 font position, it should be mounted on the first unused font position,
8487 which can be found in the @code{.fp} register. Although @code{gtroff}
8488 does not enforce this strictly, it is not allowed to mount a font at a
8489 position whose number is much greater (approx.@: 1000 positions) than
8490 that of any currently used position.
8492 The @code{fp} request has an optional third argument. This argument
8493 gives the external name of the font, which is used for finding the font
8494 description file. The second argument gives the internal name of the
8495 font which is used to refer to the font in @code{gtroff} after it has
8496 been mounted. If there is no third argument then the internal name is
8497 used as the external name. This feature makes it possible to use
8498 fonts with long names in compatibility mode.
8501 Both the @code{ft} request and the @code{\f} escape have alternative
8502 syntax forms to access font positions.
8504 @DefreqList {ft, nnn}
8505 @DefescItem {\\f, , n, }
8506 @DefescItem {\\f, @lparen{}, nn, }
8507 @DefescListEnd {\\f, @lbrack{}, nnn, @rbrack}
8508 @cindex changing font position (@code{\f})
8509 @cindex font position, changing (@code{\f})
8510 @cindex @code{sty} request, and font positions
8511 @cindex @code{fam} request, and font positions
8512 @cindex @code{\F}, and font positions
8516 Change the current font position to @var{nnn} (one-digit
8517 position@tie{}@var{n}, two-digit position @var{nn}), which must be a
8518 non-negative integer.
8520 If @var{nnn} is associated with a style (as set with the @code{sty}
8521 request or with the @code{styles} command in the @file{DESC} file), use
8522 it within the current font family (as set with the @code{fam} request,
8523 the @code{\F} escape, or with the @code{family} command in the @file{DESC}
8530 .ft \" switch back to font 1
8534 this is font 1 again
8537 @xref{Changing Fonts}, for the standard syntax form.
8540 @c ---------------------------------------------------------------------
8542 @node Using Symbols, Special Fonts, Font Positions, Fonts and Symbols
8543 @subsection Using Symbols
8544 @cindex using symbols
8545 @cindex symbols, using
8550 A @dfn{glyph} is a graphical representation of a @dfn{character}.
8551 While a character is an abstract entity containing semantic
8552 information, a glyph is something which can be actually seen on screen
8553 or paper. It is possible that a character has multiple glyph
8554 representation forms (for example, the character `A' can be either
8555 written in a roman or an italic font, yielding two different glyphs);
8556 sometimes more than one character maps to a single glyph (this is a
8557 @dfn{ligature} -- the most common is `fi').
8560 @cindex special fonts
8563 @cindex @code{special} request, and glyph search order
8564 @cindex @code{fspecial} request, and glyph search order
8565 A @dfn{symbol} is simply a named glyph. Within @code{gtroff}, all
8566 glyph names of a particular font are defined in its font file. If the
8567 user requests a glyph not available in this font, @code{gtroff} looks
8568 up an ordered list of @dfn{special fonts}. By default, the
8569 @sc{PostScript} output device supports the two special fonts @samp{SS}
8570 (slanted symbols) and @samp{S} (symbols) (the former is looked up
8571 before the latter). Other output devices use different names for
8572 special fonts. Fonts mounted with the @code{fonts} keyword in the
8573 @file{DESC} file are globally available. To install additional
8574 special fonts locally (i.e.@: for a particular font), use the
8575 @code{fspecial} request.
8577 Here the exact rules how @code{gtroff} searches a given symbol:
8581 If the symbol has been defined with the @code{char} request, use it.
8582 This hides a symbol with the same name in the current font.
8585 Check the current font.
8588 If the symbol has been defined with the @code{fchar} request, use it.
8591 Check whether the current font has a font-specific list of special fonts;
8592 test all fonts in the order of appearance in the last @code{fspecial}
8593 call if appropriate.
8596 If the symbol has been defined with the @code{fschar} request for the
8597 current font, use it.
8600 Check all fonts in the order of appearance in the last @code{special}
8604 If the symbol has been defined with the @code{schar} request, use it.
8607 As a last resort, consult all fonts loaded up to now for special fonts
8608 and check them, starting with the lowest font number. Note that this can
8609 sometimes lead to surprising results since the @code{fonts} line in the
8610 @file{DESC} file often contains empty positions which are filled later
8611 on. For example, consider the following:
8618 This mounts font @code{foo} at font position@tie{}3. We assume that
8619 @code{FOO} is a special font, containing glyph @code{foo},
8620 and that no font has been loaded yet. The line
8627 makes font @code{BAZ} special only if font @code{BAR} is active. We
8628 further assume that @code{BAZ} is really a special font, i.e., the font
8629 description file contains the @code{special} keyword, and that it
8630 also contains glyph @code{foo} with a special shape fitting to font
8631 @code{BAR}. After executing @code{fspecial}, font @code{BAR} is loaded at
8632 font position@tie{}1, and @code{BAZ} at position@tie{}2.
8634 We now switch to a new font @code{XXX}, trying to access glyph @code{foo}
8635 which is assumed to be missing. There are neither font-specific special
8636 fonts for @code{XXX} nor any other fonts made special with the
8637 @code{special} request, so @code{gtroff} starts the search for special
8638 fonts in the list of already mounted fonts, with increasing font
8639 positions. Consequently, it finds @code{BAZ} before @code{FOO} even for
8640 @code{XXX} which is not the intended behaviour.
8643 @xref{Font Files}, and @ref{Special Fonts}, for more details.
8645 @cindex list of available glyphs (@cite{groff_char(7)} man page)
8646 @cindex available glyphs, list (@cite{groff_char(7)} man page)
8647 @cindex glyphs, available, list (@cite{groff_char(7)} man page)
8648 The list of available symbols is device dependent; see the
8649 @cite{groff_char(7)} man page for a complete list of all glyphs. For
8653 man -Tdvi groff_char > groff_char.dvi
8657 for a list using the default DVI fonts (not all versions of the
8658 @code{man} program support the @option{-T} option). If you want to
8659 use an additional macro package to change the used fonts, @code{groff}
8660 must be called directly:
8663 groff -Tdvi -mec -man groff_char.7 > groff_char.dvi
8666 @cindex composite glyph names
8667 @cindex glyph names, composite
8668 @cindex groff glyph list (GGL)
8669 @cindex GGL (groff glyph list)
8670 @cindex adobe glyph list (AGL)
8671 @cindex AGL (adobe glyph list)
8672 Glyph names not listed in groff_char(7) are derived algorithmically,
8673 using a simplified version of the Adobe Glyph List (AGL) algorithm
8674 which is described in
8675 @uref{http://partners.adobe.com@//asn@//tech@//type@//unicodegn.jsp}.
8676 The (frozen) set of glyph names which can't be derived algorithmically
8677 is called @dfn{groff glyph list (GGL)}.
8681 A glyph for Unicode character U+@var{XXXX}[@var{X}[@var{X}]] which is
8682 not a composite character will be named
8683 @code{u@var{XXXX}@r{[}@var{X}@r{[}@var{X}@r{]]}}. @var{X} must be an
8684 uppercase hexadecimal digit. Examples: @code{u1234}, @code{u008E},
8685 @code{u12DB8}. The largest Unicode value is 0x10FFFF. There must be at
8686 least four @code{X} digits; if necessary, add leading zeroes (after the
8687 @samp{u}). No zero padding is allowed for character codes greater than
8688 0xFFFF. Surrogates (i.e., Unicode values greater than 0xFFFF
8689 represented with character codes from the surrogate area U+D800-U+DFFF)
8690 are not allowed too.
8693 A glyph representing more than a single input character will be named
8696 @samp{u} @var{component1} @samp{_} @var{component2} @samp{_} @var{component3} @dots{}
8700 Example: @code{u0045_0302_0301}.
8702 For simplicity, all Unicode characters which are composites must be
8703 decomposed maximally (this is normalization form@tie{}D in the Unicode
8704 standard); for example, @code{u00CA_0301} is not a valid glyph name
8705 since U+00CA (@sc{latin capital letter e with circumflex}) can be
8706 further decomposed into U+0045 (@sc{latin capital letter e}) and U+0302
8707 (@sc{combining circumflex accent}). @code{u0045_0302_0301} is thus the
8708 glyph name for U+1EBE, @sc{latin capital letter e with circumflex and
8712 groff maintains a table to decompose all algorithmically derived glyph
8713 names which are composites itself. For example, @code{u0100} (@sc{latin
8714 letter a with macron}) will be automatically decomposed into
8715 @code{u0041_0304}. Additionally, a glyph name of the GGL is preferred
8716 to an algorithmically derived glyph name; groff also automatically does
8717 the mapping. Example: The glyph @code{u0045_0302} will be mapped to
8721 glyph names of the GGL can't be used in composite glyph names; for
8722 example, @code{^E_u0301} is invalid.
8725 @DefescList {\\, @lparen{}, nm, }
8726 @DefescItem {\\, @lbrack{}, name, @rbrack}
8727 @DefescListEnd {\\, @lbrack{}, component1 component2 @dots{}, @rbrack}
8728 Insert a symbol @var{name} (two-character name @var{nm}) or a composite
8729 glyph with component glyphs @var{component1}, @var{component2},
8730 @enddots{} There is no special syntax for one-character names -- the
8731 natural form @samp{\@var{n}} would collide with escapes.@footnote{Note
8732 that a one-character symbol is not the same as an input character, i.e.,
8733 the character @code{a} is not the same as @code{\[a]}. By default,
8734 @code{groff} defines only a single one-character symbol, @code{\[-]}; it
8735 is usually accessed as @code{\-}. On the other hand, @code{gtroff} has
8736 the special feature that @code{\[char@var{XXX}]} is the same as the
8737 input character with character code @var{XXX}. For example,
8738 @code{\[char97]} is identical to the letter @code{a} if @acronym{ASCII}
8739 encoding is active.}
8741 If @var{name} is undefined, a warning of type @samp{char} is generated,
8742 and the escape is ignored. @xref{Debugging}, for information about
8745 groff resolves @code{\[...]} with more than a single component as
8750 Any component which is found in the GGL will be converted to the
8751 @code{u@var{XXXX}} form.
8754 Any component @code{u@var{XXXX}} which is found in the list of
8755 decomposable glyphs will be decomposed.
8758 The resulting elements are then concatenated with @samp{_} inbetween,
8759 dropping the leading @samp{u} in all elements but the first.
8762 No check for the existence of any component (similar to @code{tr}
8763 request) will be done.
8769 @samp{A} maps to @code{u0041}, @samp{ho} maps to @code{u02DB}, thus the
8770 final glyph name would be @code{u0041_02DB}. Note this is not the
8771 expected result: The ogonek glyph @samp{ho} is a spacing ogonek, but for
8772 a proper composite a non-spacing ogonek (U+0328) is necessary. Looking
8773 into the file @file{composite.tmac} one can find @w{@samp{.composite ho
8774 u0328}} which changes the mapping of @samp{ho} while a composite glyph
8775 name is constructed, causing the final glyph name to be
8782 @samp{^E} maps to @code{u0045_0302}, thus the final glyph name is
8783 @code{u0045_0302_0301} in all forms (assuming proper calls of the
8784 @code{composite} request).
8787 It is not possible to define glyphs with names like @w{@samp{A ho}}
8788 within a groff font file. This is not really a limitation; instead, you
8789 have to define @code{u0041_0328}.
8792 @Defesc {\\C, ', xxx, '}
8793 @cindex named character (@code{\C})
8794 @cindex character, named (@code{\C})
8795 Typeset the glyph named @var{xxx}.@footnote{@code{\C} is actually a
8796 misnomer since it accesses an output glyph.} Normally it is more
8797 convenient to use @code{\[@var{xxx}]}, but @code{\C} has the advantage
8798 that it is compatible with newer versions of @acronym{AT&T}
8799 @code{troff} and is available in compatibility mode.
8802 @Defreq {composite, from to}
8803 @pindex composite.tmac
8804 Map glyph name @var{from} to glyph name @var{to} if it is used in
8805 @code{\[...]} with more than one component. See above for examples.
8807 This mapping is based on glyph names only; no check for the existence of
8808 either glyph is done.
8810 A set of default mappings for many accents can be found in the file
8811 @file{composite.tmac} which is loaded at start-up.
8814 @Defesc {\\N, ', n, '}
8815 @cindex numbered glyph (@code{\N})
8816 @cindex glyph, numbered (@code{\N})
8817 @cindex @code{char} request, used with @code{\N}
8819 Typeset the glyph with code@tie{}@var{n} in the current font
8820 (@code{n}@tie{}is @strong{not} the input character code). The
8821 number @var{n}@tie{}can be any non-negative decimal integer. Most devices
8822 only have glyphs with codes between 0 and@tie{}255; the Unicode
8823 output device uses codes in the range 0--65535. If the current
8824 font does not contain a glyph with that code, special fonts are
8825 @emph{not} searched. The @code{\N} escape sequence can be
8826 conveniently used in conjunction with the @code{char} request:
8829 .char \[phone] \f[ZD]\N'37'
8834 @cindex unnamed glyphs
8835 @cindex glyphs, unnamed
8836 The code of each glyph is given in the fourth column in the font
8837 description file after the @code{charset} command. It is possible to
8838 include unnamed glyphs in the font description file by using a
8839 name of @samp{---}; the @code{\N} escape sequence is the only way to
8842 No kerning is applied to glyphs accessed with @code{\N}.
8845 Some escape sequences directly map onto special glyphs.
8848 This is a backslash followed by the apostrophe character, @acronym{ASCII}
8849 character @code{0x27} (@acronym{EBCDIC} character @code{0x7D}). The same
8850 as @code{\[aa]}, the acute accent.
8854 This is a backslash followed by @acronym{ASCII} character @code{0x60}
8855 (@acronym{EBCDIC} character @code{0x79} usually). The same as
8856 @code{\[ga]}, the grave accent.
8860 This is the same as @code{\[-]}, the minus sign in the current font.
8863 @Defreq {cflags, n c1 c2 @dots{}}
8864 @cindex glyph properties (@code{cflags})
8865 @cindex character properties (@code{cflags})
8866 @cindex properties of glyphs (@code{cflags})
8867 @cindex properties of characters (@code{cflags})
8868 Input characters and symbols have certain properties associated
8869 with it.@footnote{Note that the output glyphs themselves don't have
8870 such properties. For @code{gtroff}, a glyph is a numbered box with
8871 a given width, depth, and height, nothing else. All manipulations
8872 with the @code{cflags} request work on the input level.} These
8873 properties can be modified with the @code{cflags} request. The
8874 first argument is the sum of the desired flags and the remaining
8875 arguments are the characters or symbols to have those properties.
8876 It is possible to omit the spaces between the characters or symbols.
8880 @cindex end-of-sentence characters
8881 @cindex characters, end-of-sentence
8882 The character ends sentences (initially characters @samp{.?!} have this
8886 @cindex hyphenating characters
8887 @cindex characters, hyphenation
8888 Lines can be broken before the character (initially no characters have
8892 @cindex @code{hy} glyph, and @code{cflags}
8893 @cindex @code{em} glyph, and @code{cflags}
8894 Lines can be broken after the character (initially the character
8895 @samp{-} and the symbols @samp{\[hy]} and @samp{\[em]} have this property).
8898 @cindex overlapping characters
8899 @cindex characters, overlapping
8900 @cindex @code{ul} glyph, and @code{cflags}
8901 @cindex @code{rn} glyph, and @code{cflags}
8902 @cindex @code{ru} glyph, and @code{cflags}
8903 @cindex @code{radicalex} glyph, and @code{cflags}
8904 @cindex @code{sqrtex} glyph, and @code{cflags}
8905 The character overlaps horizontally if used as a horizontal line building
8906 element. Initially the symbols @samp{\[ul]}, @samp{\[rn]}, @samp{\[ru]},
8907 @samp{\[radicalex]}, and @samp{\[sqrtex]} have this property.
8910 @cindex @code{br} glyph, and @code{cflags}
8911 The character overlaps vertically if used as vertical line building element.
8912 Initially symbol @samp{\[br]} has this property.
8915 @cindex transparent characters
8916 @cindex character, transparent
8917 @cindex @code{"}, at end of sentence
8918 @cindex @code{'}, at end of sentence
8919 @cindex @code{)}, at end of sentence
8920 @cindex @code{]}, at end of sentence
8921 @cindex @code{*}, at end of sentence
8922 @cindex @code{dg} glyph, at end of sentence
8923 @cindex @code{rq} glyph, at end of sentence
8924 An end-of-sentence character followed by any number of characters with
8925 this property is treated as the end of a sentence if followed by a
8926 newline or two spaces; in other words the character is
8927 @dfn{transparent} for the purposes of end-of-sentence recognition --
8928 this is the same as having a zero space factor in @TeX{} (initially
8929 characters @samp{"')]*} and the symbols @samp{\[dg]} and @samp{\[rq]} have
8934 @DefreqList {char, g [@Var{string}]}
8935 @DefreqItem {fchar, g [@Var{string}]}
8936 @DefreqItem {fschar, f g [@Var{string}]}
8937 @DefreqListEnd {schar, g [@Var{string}]}
8938 @cindex defining character (@code{char})
8939 @cindex defining fallback character (@code{fchar}, @code{fschar}, @code{schar})
8940 @cindex character, defining (@code{char})
8941 @cindex character, defining fallback (@code{fchar}, @code{fschar}, @code{schar})
8942 @cindex fallback character, defining (@code{fchar}, @code{fschar}, @code{schar})
8943 @cindex creating new characters (@code{char})
8944 @cindex defining symbol (@code{char})
8945 @cindex symbol, defining (@code{char})
8946 @cindex defining glyph (@code{char})
8947 @cindex glyph, defining (@code{char})
8948 @cindex escape character, while defining glyph
8949 @cindex character, escape, while defining glyph
8950 @cindex @code{tr} request, and glyph definitions
8951 @cindex @code{cp} request, and glyph definitions
8952 @cindex @code{rc} request, and glyph definitions
8953 @cindex @code{lc} request, and glyph definitions
8954 @cindex @code{\l}, and glyph definitions
8955 @cindex @code{\L}, and glyph definitions
8956 @cindex @code{\&}, and glyph definitions
8957 @cindex @code{\e}, and glyph definitions
8958 @cindex @code{hcode} request, and glyph definitions
8959 Define a new glyph@tie{}@var{g} to be @var{string} (which can be
8960 empty).@footnote{@code{char} is a misnomer since an output glyph is
8961 defined.} Every time glyph@tie{}@var{g} needs to be printed,
8962 @var{string} is processed in a temporary environment and the result is
8963 wrapped up into a single object. Compatibility mode is turned off and
8964 the escape character is set to @samp{\} while @var{string} is being
8965 processed. Any emboldening, constant spacing or track kerning is
8966 applied to this object rather than to individual characters in
8969 A glyph defined by these requests can be used just
8970 like a normal glyph provided by the output device. In particular,
8971 other characters can be translated to it with the @code{tr} or
8972 @code{trin} requests; it can be made the leader character by the
8973 @code{lc} request; repeated patterns can be drawn with the glyph
8974 using the @code{\l} and @code{\L} escape sequences; words containing
8975 the glyph can be hyphenated correctly if the @code{hcode} request
8976 is used to give the glyph's symbol a hyphenation code.
8978 There is a special anti-recursion feature: Use of @code{g} within
8979 the glyph's definition is handled like normal characters and symbols
8980 not defined with @code{char}.
8982 Note that the @code{tr} and @code{trin} requests take precedence if
8983 @code{char} accesses the same symbol.
8997 The @code{fchar} request defines a fallback glyph:
8998 @code{gtroff} only checks for glyphs defined with @code{fchar}
8999 if it cannot find the glyph in the current font.
9000 @code{gtroff} carries out this test before checking special fonts.
9002 @code{fschar} defines a fallback glyph for font@tie{}@var{f}: @code{gtroff}
9003 checks for glyphs defined with @code{fschar} after the list of fonts
9004 declared as font-specific special fonts with the @code{fspecial} request,
9005 but before the list of fonts declared as global special fonts with the
9006 @code{special} request.
9008 Finally, the @code{schar} request defines a global fallback glyph:
9009 @code{gtroff} checks for glyphs defined with @code{schar} after the list
9010 of fonts declared as global special fonts with the @code{special} request,
9011 but before the already mounted special fonts.
9013 @xref{Using Symbols}, for a detailed description of the glyph
9014 searching mechanism in @code{gtroff}.
9017 @DefreqList {rchar, c1 c2 @dots{}}
9018 @DefreqListEnd {rfschar, f c1 c2 @dots{}}
9019 @cindex removing glyph definition (@code{rchar}, @code{rfschar})
9020 @cindex glyph, removing definition (@code{rchar}, @code{rfschar})
9021 @cindex fallback glyph, removing definition (@code{rchar}, @code{rfschar})
9022 Remove the definitions of glyphs @var{c1}, @var{c2},@tie{}@enddots{}
9023 This undoes the effect of a @code{char}, @code{fchar}, or
9024 @code{schar} request.
9026 It is possible to omit the whitespace between arguments.
9028 The request @code{rfschar} removes glyph definitions defined with
9029 @code{fschar} for glyph@tie{}f.
9032 @xref{Special Characters}.
9034 @c ---------------------------------------------------------------------
9036 @node Special Fonts, Artificial Fonts, Using Symbols, Fonts and Symbols
9037 @subsection Special Fonts
9038 @cindex special fonts
9039 @cindex fonts, special
9041 Special fonts are those that @code{gtroff} searches
9042 when it cannot find the requested glyph in the current font.
9043 The Symbol font is usually a special font.
9045 @code{gtroff} provides the following two requests to add more special
9046 fonts. @xref{Using Symbols}, for a detailed description of the glyph
9047 searching mechanism in @code{gtroff}.
9049 Usually, only non-TTY devices have special fonts.
9051 @DefreqList {special, [@Var{s1} @Var{s2} @dots{}]}
9052 @DefreqListEnd {fspecial, f [@Var{s1} @Var{s2} @dots{}]}
9055 Use the @code{special} request to define special fonts. Initially, this
9058 Use the @code{fspecial} request to designate special fonts only when
9059 font@tie{}@var{f} is active. Initially, this list is empty.
9061 Previous calls to @code{special} or @code{fspecial} are overwritten;
9062 without arguments, the particular list of special fonts is set to empty.
9063 Special fonts are searched in the order they appear as arguments.
9065 All fonts which appear in a call to @code{special} or @code{fspecial} are
9068 @xref{Using Symbols}, for the exact search order of glyphs.
9071 @c ---------------------------------------------------------------------
9073 @node Artificial Fonts, Ligatures and Kerning, Special Fonts, Fonts and Symbols
9074 @subsection Artificial Fonts
9075 @cindex artificial fonts
9076 @cindex fonts, artificial
9078 There are a number of requests and escapes for artificially creating
9079 fonts. These are largely vestiges of the days when output devices
9080 did not have a wide variety of fonts, and when @code{nroff} and
9081 @code{troff} were separate programs. Most of them are no longer
9082 necessary in GNU @code{troff}. Nevertheless, they are supported.
9084 @DefescList {\\H, ', height, '}
9085 @DefescItem {\\H, ', @t{+}height, '}
9086 @DefescItem {\\H, ', @t{-}height, '}
9087 @DefregListEnd {.height}
9088 @cindex changing the font height (@code{\H})
9089 @cindex font height, changing (@code{\H})
9090 @cindex height, font, changing (@code{\H})
9091 Change (increment, decrement) the height of the current font, but not
9092 the width. If @var{height} is zero, restore the original height.
9093 Default scaling indicator is @samp{z}.
9095 The read-only number register @code{.height} contains the font height as
9098 Currently, only the @option{-Tps} device supports this feature.
9100 Note that @code{\H} doesn't produce an input token in @code{gtroff}.
9101 As a consequence, it can be used in requests like @code{mc} (which
9102 expects a single character as an argument) to change the font on
9109 In compatibility mode, @code{gtroff} behaves differently: If an
9110 increment or decrement is used, it is always taken relative to the
9111 current point size and not relative to the previously selected font
9116 \H'+5'test \H'+5'test
9120 prints the word @samp{test} twice with the same font height (five
9121 points larger than the current font size).
9124 @DefescList {\\S, ', slant, '}
9125 @DefregListEnd {.slant}
9126 @cindex changing the font slant (@code{\S})
9127 @cindex font slant, changing (@code{\S})
9128 @cindex slant, font, changing (@code{\S})
9129 Slant the current font by @var{slant} degrees. Positive values slant
9130 to the right. Only integer values are possible.
9132 The read-only number register @code{.slant} contains the font slant as
9135 Currently, only the @option{-Tps} device supports this feature.
9137 Note that @code{\S} doesn't produce an input token in @code{gtroff}.
9138 As a consequence, it can be used in requests like @code{mc} (which
9139 expects a single character as an argument) to change the font on
9146 This request is incorrectly documented in the original @acronym{UNIX}
9147 troff manual; the slant is always set to an absolute value.
9150 @Defreq {ul, [@Var{lines}]}
9151 @cindex underlining (@code{ul})
9152 The @code{ul} request normally underlines subsequent lines if a TTY
9153 output device is used. Otherwise, the lines are printed in italics
9154 (only the term `underlined' is used in the following). The single
9155 argument is the number of input lines to be underlined; with no
9156 argument, the next line is underlined. If @var{lines} is zero or
9157 negative, stop the effects of @code{ul} (if it was active). Requests
9158 and empty lines do not count for computing the number of underlined
9159 input lines, even if they produce some output like @code{tl}. Lines
9160 inserted by macros (e.g.@: invoked by a trap) do count.
9162 At the beginning of @code{ul}, the current font is stored and the
9163 underline font is activated. Within the span of a @code{ul} request,
9164 it is possible to change fonts, but after the last line affected by
9165 @code{ul} the saved font is restored.
9167 This number of lines still to be underlined is associated with the
9168 current environment (@pxref{Environments}). The underline font can be
9169 changed with the @code{uf} request.
9171 @c XXX @xref should be changed to grotty
9173 @c @xref{Troff and Nroff Mode}, for a discussion how underlining is
9174 @c implemented in for TTY output devices, and which problems can arise.
9176 The @code{ul} request does not underline spaces.
9179 @Defreq {cu, [@Var{lines}]}
9180 @cindex continuous underlining (@code{cu})
9181 @cindex underlining, continuous (@code{cu})
9182 The @code{cu} request is similar to @code{ul} but underlines spaces as
9183 well (if a TTY output device is used).
9187 @cindex underline font (@code{uf})
9188 @cindex font for underlining (@code{uf})
9189 Set the underline font (globally) used by @code{ul} and @code{cu}. By
9190 default, this is the font at position@tie{}2. @var{font} can be either
9191 a non-negative font position or the name of a font.
9194 @DefreqList {bd, font [@Var{offset}]}
9195 @DefreqItem {bd, font1 font2 [@Var{offset}]}
9197 @cindex imitating bold face (@code{bd})
9198 @cindex bold face, imitating (@code{bd})
9199 Artificially create a bold font by printing each glyph twice,
9202 Two syntax forms are available.
9206 Imitate a bold font unconditionally. The first argument specifies the
9207 font to embolden, and the second is the number of basic units, minus
9208 one, by which the two glyphs are offset. If the second argument is
9209 missing, emboldening is turned off.
9211 @var{font} can be either a non-negative font position or the name of a
9214 @var{offset} is available in the @code{.b} read-only register if a
9215 special font is active; in the @code{bd} request, its default unit is
9218 @cindex @code{fspecial} request, and imitating bold
9220 @cindex embolding of special fonts
9221 @cindex special fonts, emboldening
9223 Imitate a bold form conditionally. Embolden @var{font1} by
9224 @var{offset} only if font @var{font2} is the current font. This
9225 command can be issued repeatedly to set up different emboldening
9226 values for different current fonts. If the second argument is
9227 missing, emboldening is turned off for this particular current font.
9229 This affects special fonts only (either set up with the @code{special}
9230 command in font files or with the @code{fspecial} request).
9234 @Defreq {cs, font [@Var{width} [@Var{em-size}]]}
9235 @cindex constant glyph space mode (@code{cs})
9236 @cindex mode for constant glyph space (@code{cs})
9237 @cindex glyph, constant space
9238 @cindex @code{ps} request, and constant glyph space mode
9239 Switch to and from @dfn{constant glyph space mode}. If activated, the
9240 width of every glyph is @math{@var{width}/36} ems. The em size is
9241 given absolutely by @var{em-size}; if this argument is missing, the em
9242 value is taken from the current font size (as set with the @code{ps}
9243 request) when the font is effectively in use. Without second and
9244 third argument, constant glyph space mode is deactivated.
9246 Default scaling indicator for @var{em-size} is @samp{z}; @var{width} is
9250 @c ---------------------------------------------------------------------
9252 @node Ligatures and Kerning, , Artificial Fonts, Fonts and Symbols
9253 @subsection Ligatures and Kerning
9254 @cindex ligatures and kerning
9255 @cindex kerning and ligatures
9257 Ligatures are groups of characters that are run together, i.e, producing
9258 a single glyph. For example, the letters `f' and `i' can form a
9259 ligature `fi' as in the word `file'. This produces a cleaner look
9260 (albeit subtle) to the printed output. Usually, ligatures are not
9261 available in fonts for TTY output devices.
9263 Most @sc{PostScript} fonts support the fi and fl ligatures. The C/A/T
9264 typesetter that was the target of @acronym{AT&T} @code{troff} also
9265 supported `ff', `ffi', and `ffl' ligatures. Advanced typesetters or
9266 `expert' fonts may include ligatures for `ft' and `ct', although GNU
9267 @code{troff} does not support these (yet).
9269 Only the current font is checked for ligatures and kerns; neither special
9270 fonts nor entities defined with the @code{char} request (and its siblings)
9271 are taken into account.
9273 @DefreqList {lg, [@Var{flag}]}
9274 @DefregListEnd {.lg}
9275 @cindex activating ligatures (@code{lg})
9276 @cindex ligatures, activating (@code{lg})
9277 @cindex ligatures enabled register (@code{.lg})
9278 Switch the ligature mechanism on or off; if the parameter is non-zero
9279 or missing, ligatures are enabled, otherwise disabled. Default is on.
9280 The current ligature mode can be found in the read-only number register
9281 @code{.lg} (set to 1 or@tie{}2 if ligatures are enabled, 0@tie{}otherwise).
9283 Setting the ligature mode to@tie{}2 enables the two-character ligatures
9284 (fi, fl, and ff) and disables the three-character ligatures (ffi and
9288 @dfn{Pairwise kerning} is another subtle typesetting mechanism that
9289 modifies the distance between a glyph pair to improve readability.
9290 In most cases (but not always) the distance is decreased.
9292 For example, compare the combination of the letters `V' and `A'. With
9293 kerning, `VA' is printed. Without kerning it appears as `V@w{}A'.
9295 Typewriter-like fonts and fonts for terminals where all glyphs
9296 have the same width don't use kerning.
9298 @DefreqList {kern, [@Var{flag}]}
9299 @DefregListEnd {.kern}
9300 @cindex activating kerning (@code{kern})
9301 @cindex kerning, activating (@code{kern})
9302 @cindex kerning enabled register (@code{.kern})
9303 Switch kerning on or off. If the parameter is non-zero or missing,
9304 enable pairwise kerning, otherwise disable it. The read-only number
9305 register @code{.kern} is set to@tie{}1 if pairwise kerning is enabled,
9308 @cindex zero width space character (@code{\&})
9309 @cindex character, zero width space (@code{\&})
9310 @cindex space character, zero width (@code{\&})
9311 If the font description file contains pairwise kerning information,
9312 glyphs from that font are kerned. Kerning between two glyphs
9313 can be inhibited by placing @code{\&} between them: @samp{V\&A}.
9315 @xref{Font File Format}.
9318 @cindex track kerning
9319 @cindex kerning, track
9320 @dfn{Track kerning} expands or reduces the space between glyphs.
9321 This can be handy, for example, if you need to squeeze a long word
9322 onto a single line or spread some text to fill a narrow column. It
9323 must be used with great care since it is usually considered bad
9324 typography if the reader notices the effect.
9326 @Defreq {tkf, f s1 n1 s2 n2}
9327 @cindex activating track kerning (@code{tkf})
9328 @cindex track kerning, activating (@code{tkf})
9329 Enable track kerning for font@tie{}@var{f}. If the current font
9330 is@tie{}@var{f} the width of every glyph is increased by an amount
9331 between @var{n1} and @var{n2} (@var{n1}, @var{n2} can be negative); if
9332 the current point size is less than or equal to @var{s1} the width is
9333 increased by @var{n1}; if it is greater than or equal to @var{s2} the
9334 width is increased by @var{n2}; if the point size is greater than or
9335 equal to @var{s1} and less than or equal to @var{s2} the increase in
9336 width is a linear function of the point size.
9338 The default scaling indicator is @samp{z} for @var{s1} and @var{s2},
9339 @samp{p} for @var{n1} and @var{n2}.
9341 Note that the track kerning amount is added even to the rightmost glyph
9342 in a line; for large values it is thus recommended to increase the line
9343 length by the same amount to compensate it.
9346 Sometimes, when typesetting letters of different fonts, more or less
9347 space at such boundaries are needed. There are two escapes to help
9351 @cindex italic correction (@code{\/})
9352 @cindex correction, italic (@code{\/})
9353 @cindex correction between italic and roman glyph (@code{\/}, @code{\,})
9354 @cindex roman glyph, correction after italic glyph (@code{\/})
9355 @cindex italic glyph, correction before roman glyph (@code{\/})
9356 @cindex glyph, italic correction (@code{\/})
9357 Increase the width of the preceding glyph so that the spacing
9358 between that glyph and the following glyph is correct if the
9359 following glyph is a roman glyph. For example, if an
9360 italic@tie{}@code{f} is immediately followed by a roman right
9361 parenthesis, then in many fonts the top right portion of the@tie{}@code{f}
9362 overlaps the top left of the right parenthesis. Use this escape
9363 sequence whenever an italic glyph is immediately followed by a
9364 roman glyph without any intervening space. This small amount of
9365 space is also called @dfn{italic correction}.
9371 @result{} {@it f}@r{)}
9373 @result{} @i{f}@r{)}
9379 @Defesc {\\\,, , , }
9380 @cindex left italic correction (@code{\,})
9381 @cindex correction, left italic (@code{\,})
9382 @cindex glyph, left italic correction (@code{\,})
9383 @cindex roman glyph, correction before italic glyph (@code{\,})
9384 @cindex italic glyph, correction after roman glyph (@code{\,})
9385 Modify the spacing of the following glyph so that the spacing
9386 between that glyph and the preceding glyph is correct if the
9387 preceding glyph is a roman glyph. Use this escape sequence
9388 whenever a roman glyph is immediately followed by an italic
9389 glyph without any intervening space. In analogy to above, this
9390 space could be called @dfn{left italic correction}, but this term
9397 @result{} @r{q}@i{f}
9399 @result{} @r{q}@math{@ptexcomma}@i{f}
9406 Insert a zero-width character, which is invisible. Its intended use
9407 is to stop interaction of a character with its surrounding.
9411 It prevents the insertion of extra space after an end-of-sentence
9417 @result{} Test. Test.
9420 @result{} Test. Test.
9424 It prevents interpretation of a control character at the beginning of
9429 @result{} warning: `Test' not defined
9435 It prevents kerning between two glyphs.
9443 @result{} @r{V@w{}A}
9449 It is needed to map an arbitrary character to nothing in the @code{tr}
9450 request (@pxref{Character Translations}).
9455 This escape is similar to @code{\&} except that it behaves like a
9456 character declared with the @code{cflags} request to be transparent
9457 for the purposes of an end-of-sentence character.
9459 Its main usage is in macro definitions to protect against arguments
9460 starting with a control character.
9472 @result{}This is a test.' This is a test.
9476 @result{}This is a test.' This is a test.
9481 @c =====================================================================
9483 @node Sizes, Strings, Fonts and Symbols, gtroff Reference
9489 @cindex size of type
9490 @cindex vertical spacing
9491 @cindex spacing, vertical
9492 @code{gtroff} uses two dimensions with each line of text, type size
9493 and vertical spacing. The @dfn{type size} is approximately the height
9494 of the tallest glyph.@footnote{This is usually the parenthesis.
9495 Note that in most cases the real dimensions of the glyphs in a font
9496 are @emph{not} related to its type size! For example, the standard
9497 @sc{PostScript} font families `Times Roman', `Helvetica', and
9498 `Courier' can't be used together at 10@dmn{pt}; to get acceptable
9499 output, the size of `Helvetica' has to be reduced by one point, and
9500 the size of `Courier' must be increased by one point.} @dfn{Vertical
9501 spacing} is the amount of space @code{gtroff} allows for a line of
9502 text; normally, this is about 20%@tie{}larger than the current type
9503 size. Ratios smaller than this can result in hard-to-read text;
9504 larger than this, it spreads the text out more vertically (useful for
9505 term papers). By default, @code{gtroff} uses 10@tie{}point type on
9506 12@tie{}point spacing.
9509 The difference between type size and vertical spacing is known, by
9510 typesetters, as @dfn{leading} (this is pronounced `ledding').
9513 * Changing Type Sizes::
9514 * Fractional Type Sizes::
9517 @c ---------------------------------------------------------------------
9519 @node Changing Type Sizes, Fractional Type Sizes, Sizes, Sizes
9520 @subsection Changing Type Sizes
9522 @DefreqList {ps, [@Var{size}]}
9523 @DefreqItem {ps, @t{+}@Var{size}}
9524 @DefreqItem {ps, @t{-}@Var{size}}
9525 @DefescItem {\\s, , size, }
9527 @cindex changing type sizes (@code{ps}, @code{\s})
9528 @cindex type sizes, changing (@code{ps}, @code{\s})
9529 @cindex point sizes, changing (@code{ps}, @code{\s})
9530 Use the @code{ps} request or the @code{\s} escape to change (increase,
9531 decrease) the type size (in points). Specify @var{size} as either an
9532 absolute point size, or as a relative change from the current size.
9533 The size@tie{}0, or no argument, goes back to the previous size.
9535 Default scaling indicator of @code{size} is @samp{z}. If @code{size}
9536 is zero or negative, it is set to 1@dmn{u}.
9538 @cindex type size registers (@code{.s}, @code{.ps})
9539 @cindex point size registers (@code{.s}, @code{.ps})
9540 The read-only number register @code{.s} returns the point size in
9541 points as a decimal fraction. This is a string. To get the point
9542 size in scaled points, use the @code{.ps} register instead.
9544 @code{.s} is associated with the current environment
9545 (@pxref{Environments}).
9552 wink, wink, \s+2nudge, nudge,\s+8 say no more!
9556 The @code{\s} escape may be called in a variety of ways. Much like
9557 other escapes there must be a way to determine where the argument ends
9558 and the text begins. Any of the following forms are valid:
9562 Set the point size to @var{n}@tie{}points. @var{n}@tie{}must be either
9563 0 or in the range 4 to@tie{}39.
9567 Increase or decrease the point size by @var{n}@tie{}points.
9568 @var{n}@tie{}must be exactly one digit.
9571 Set the point size to @var{nn}@tie{}points. @var{nn} must be exactly
9578 Increase or decrease the point size by @var{nn}@tie{}points. @var{nn}
9579 must be exactly two digits.
9582 Note that @code{\s} doesn't produce an input token in @code{gtroff}.
9583 As a consequence, it can be used in requests like @code{mc} (which
9584 expects a single character as an argument) to change the font on
9591 @xref{Fractional Type Sizes}, for yet another syntactical form of
9592 using the @code{\s} escape.
9595 @Defreq {sizes, s1 s2 @dots{} sn [0]}
9596 Some devices may only have certain permissible sizes, in which case
9597 @code{gtroff} rounds to the nearest permissible size.
9598 The @file{DESC} file specifies which sizes are permissible for the device.
9600 Use the @code{sizes} request to change the permissible sizes
9601 for the current output device.
9602 Arguments are in scaled points;
9603 the @code{sizescale} line in the
9604 @file{DESC} file for the output device
9605 provides the scaling factor.
9606 For example, if the scaling factor is 1000,
9607 then the value 12000 is 12@tie{}points.
9609 Each argument can be a single point size (such as @samp{12000}),
9610 or a range of sizes (such as @samp{4000-72000}).
9611 You can optionally end the list with a zero.
9614 @DefreqList {vs, [@Var{space}]}
9615 @DefreqItem {vs, @t{+}@Var{space}}
9616 @DefreqItem {vs, @t{-}@Var{space}}
9618 @cindex changing vertical line spacing (@code{vs})
9619 @cindex vertical line spacing, changing (@code{vs})
9620 @cindex vertical line spacing register (@code{.v})
9621 Change (increase, decrease) the vertical spacing by @var{space}. The
9622 default scaling indicator is @samp{p}.
9624 If @code{vs} is called without an argument, the vertical spacing is
9625 reset to the previous value before the last call to @code{vs}.
9627 @cindex @code{.V} register, and @code{vs}
9628 @code{gtroff} creates a warning of type @samp{range} if @var{space} is
9629 negative; the vertical spacing is then set to smallest positive value,
9630 the vertical resolution (as given in the @code{.V} register).
9632 Note that @w{@samp{.vs 0}} isn't saved in a diversion since it doesn't
9633 result in a vertical motion. You explicitly have to repeat this command
9634 before inserting the diversion.
9636 The read-only number register @code{.v} contains the current vertical
9637 spacing; it is associated with the current environment
9638 (@pxref{Environments}).
9641 @cindex vertical line spacing, effective value
9642 The effective vertical line spacing consists of four components. Breaking
9643 a line causes the following actions (in the given order).
9647 @cindex extra pre-vertical line space (@code{\x})
9648 @cindex line space, extra pre-vertical (@code{\x})
9649 Move the current point vertically by the @dfn{extra pre-vertical line
9650 space}. This is the minimum value of all @code{\x} escapes with a
9651 negative argument in the current output line.
9654 Move the current point vertically by the vertical line spacing as set with
9655 the @code{vs} request.
9658 Output the current line.
9661 @cindex extra post-vertical line space (@code{\x})
9662 @cindex line space, extra post-vertical (@code{\x})
9663 Move the current point vertically by the @dfn{extra post-vertical line
9664 space}. This is the maximum value of all @code{\x} escapes with a
9665 positive argument in the line which has just been output.
9668 @cindex post-vertical line spacing
9669 @cindex line spacing, post-vertical (@code{pvs})
9670 Move the current point vertically by the @dfn{post-vertical line spacing}
9671 as set with the @code{pvs} request.
9674 @cindex double-spacing (@code{vs}, @code{pvs})
9675 It is usually better to use @code{vs} or @code{pvs} instead of @code{ls}
9676 to produce double-spaced documents: @code{vs} and @code{pvs} have a finer
9677 granularity for the inserted vertical space compared to @code{ls};
9678 furthermore, certain preprocessors assume single-spacing.
9680 @xref{Manipulating Spacing}, for more details on the @code{\x} escape
9681 and the @code{ls} request.
9683 @DefreqList {pvs, [@Var{space}]}
9684 @DefreqItem {pvs, @t{+}@Var{space}}
9685 @DefreqItem {pvs, @t{-}@Var{space}}
9686 @DefregListEnd {.pvs}
9687 @cindex @code{ls} request, alternative to (@code{pvs})
9688 @cindex post-vertical line spacing, changing (@code{pvs})
9689 @cindex post-vertical line spacing register (@code{.pvs})
9690 Change (increase, decrease) the post-vertical spacing by
9691 @var{space}. The default scaling indicator is @samp{p}.
9693 If @code{pvs} is called without an argument, the post-vertical spacing is
9694 reset to the previous value before the last call to @code{pvs}.
9696 @code{gtroff} creates a warning of type @samp{range} if @var{space} is
9697 zero or negative; the vertical spacing is then set to zero.
9699 The read-only number register @code{.pvs} contains the current
9700 post-vertical spacing; it is associated with the current environment
9701 (@pxref{Environments}).
9704 @c ---------------------------------------------------------------------
9706 @node Fractional Type Sizes, , Changing Type Sizes, Sizes
9707 @subsection Fractional Type Sizes
9708 @cindex fractional type sizes
9709 @cindex fractional point sizes
9710 @cindex type sizes, fractional
9711 @cindex point sizes, fractional
9712 @cindex sizes, fractional
9714 @cindex @code{s} unit
9715 @cindex unit, @code{s}
9716 @cindex @code{z} unit
9717 @cindex unit, @code{z}
9718 @cindex @code{ps} request, with fractional type sizes
9719 @cindex @code{cs} request, with fractional type sizes
9720 @cindex @code{tkf} request, with fractional type sizes
9721 @cindex @code{\H}, with fractional type sizes
9722 @cindex @code{\s}, with fractional type sizes
9723 A @dfn{scaled point} is equal to @math{1/@var{sizescale}} points,
9724 where @var{sizescale} is specified in the @file{DESC} file (1@tie{}by
9725 default). There is a new scale indicator @samp{z} which has the
9726 effect of multiplying by @var{sizescale}. Requests and escape
9727 sequences in @code{gtroff} interpret arguments that represent a point
9728 size as being in units of scaled points, but they evaluate each such
9729 argument using a default scale indicator of @samp{z}. Arguments
9730 treated in this way are the argument to the @code{ps} request, the
9731 third argument to the @code{cs} request, the second and fourth
9732 arguments to the @code{tkf} request, the argument to the @code{\H}
9733 escape sequence, and those variants of the @code{\s} escape sequence
9734 that take a numeric expression as their argument (see below).
9736 For example, suppose @var{sizescale} is@tie{}1000; then a scaled point
9737 is equivalent to a millipoint; the request @w{@samp{.ps 10.25}} is
9738 equivalent to @w{@samp{.ps 10.25z}} and thus sets the point size to
9739 10250@tie{}scaled points, which is equal to 10.25@tie{}points.
9741 @code{gtroff} disallows the use of the @samp{z} scale indicator in
9742 instances where it would make no sense, such as a numeric
9743 expression whose default scale indicator was neither @samp{u} nor
9744 @samp{z}. Similarly it would make
9745 no sense to use a scaling indicator other than @samp{z} or @samp{u} in a
9746 numeric expression whose default scale indicator was @samp{z}, and so
9747 @code{gtroff} disallows this as well.
9749 There is also new scale indicator @samp{s} which multiplies by the
9750 number of units in a scaled point. So, for example, @samp{\n[.ps]s} is
9751 equal to @samp{1m}. Be sure not to confuse the @samp{s} and @samp{z}
9755 A read-only number register returning the point size in scaled points.
9757 @code{.ps} is associated with the current environment
9758 (@pxref{Environments}).
9762 @DefregListEnd {.sr}
9763 @cindex last-requested point size registers (@code{.psr}, @code{.sr})
9764 @cindex point size registers, last-requested (@code{.psr}, @code{.sr})
9765 @cindex @code{.ps} register, in comparison with @code{.psr}
9766 @cindex @code{.s} register, in comparison with @code{.sr}
9767 The last-requested point size in scaled points is contained in the
9768 @code{.psr} read-only number register. The last requested point size
9769 in points as a decimal fraction can be found in @code{.sr}. This is a
9770 string-valued read-only number register.
9772 Note that the requested point sizes are device-independent, whereas
9773 the values returned by the @code{.ps} and @code{.s} registers are not.
9774 For example, if a point size of 11@dmn{pt} is requested, and a
9775 @code{sizes} request (or a @code{sizescale} line in a @file{DESC} file)
9776 specifies 10.95@dmn{pt} instead, this value is actually used.
9778 Both registers are associated with the current environment
9779 (@pxref{Environments}).
9782 The @code{\s} escape has the following syntax for working with
9783 fractional type sizes:
9788 Set the point size to @var{n}@tie{}scaled points; @var{n}@tie{}is a numeric
9789 expression with a default scale indicator of @samp{z}.
9799 Increase or or decrease the point size by @var{n}@tie{}scaled points;
9800 @var{n}@tie{}is a numeric expression with a default scale indicator of
9807 @c =====================================================================
9809 @node Strings, Conditionals and Loops, Sizes, gtroff Reference
9813 @code{gtroff} has string variables, which are entirely for user
9814 convenience (i.e.@: there are no built-in strings exept @code{.T}, but
9815 even this is a read-write string variable).
9817 @DefreqList {ds, name [@Var{string}]}
9818 @DefreqItem {ds1, name [@Var{string}]}
9819 @DefescItem {\\*, , n, }
9820 @DefescItem {\\*, @lparen{}, nm, }
9821 @DefescListEnd {\\*, @lbrack{}, name arg1 arg2 @dots{}, @rbrack{}}
9822 @cindex string interpolation (@code{\*})
9823 @cindex string expansion (@code{\*})
9824 @cindex interpolation of strings (@code{\*})
9825 @cindex expansion of strings (@code{\*})
9826 @cindex string arguments
9827 @cindex arguments, of strings
9828 Define and access a string variable @var{name} (one-character
9829 name@tie{}@var{n}, two-character name @var{nm}). If @var{name} already
9830 exists, @code{ds} overwrites the previous definition. Only the syntax form
9831 using brackets can take arguments which are handled identically to
9832 macro arguments; the single exception is that a closing bracket as an
9833 argument must be enclosed in double quotes. @xref{Request and Macro
9834 Arguments}, and @ref{Parameters}.
9841 This is \*[foo nice].
9842 @result{} This is a nice test.
9845 The @code{\*} escape @dfn{interpolates} (expands in-place) a
9846 previously-defined string variable. To be more precise, the stored
9847 string is pushed onto the input stack which is then parsed by
9848 @code{gtroff}. Similar to number registers, it is possible to nest
9849 strings, i.e. string variables can be called within string variables.
9851 If the string named by the @code{\*} escape does not exist, it is
9852 defined as empty, and a warning of type @samp{mac} is emitted (see
9853 @ref{Debugging}, for more details).
9855 @cindex comments, with @code{ds}
9856 @cindex @code{ds} request, and comments
9857 @strong{Caution:} Unlike other requests, the second argument to the
9858 @code{ds} request takes up the entire line including trailing spaces.
9859 This means that comments on a line with such a request can introduce
9860 unwanted space into a string.
9863 .ds UX \s-1UNIX\s0\u\s-3tm\s0\d \" UNIX trademark
9867 Instead the comment should be put on another line or have the comment
9868 escape adjacent with the end of the string.
9871 .ds UX \s-1UNIX\s0\u\s-3tm\s0\d\" UNIX trademark
9874 @cindex trailing quotes
9875 @cindex quotes, trailing
9876 @cindex leading spaces with @code{ds}
9877 @cindex spaces with @code{ds}
9878 @cindex @code{ds} request, and leading spaces
9879 To produce leading space the string can be started with a double
9880 quote. No trailing quote is needed; in fact, any trailing quote is
9881 included in your string.
9884 .ds sign " Yours in a white wine sauce,
9887 @cindex multi-line strings
9888 @cindex strings, multi-line
9889 @cindex newline character, in strings, escaping
9890 @cindex escaping newline characters, in strings
9891 Strings are not limited to a single line of text. A string can span
9892 several lines by escaping the newlines with a backslash. The
9893 resulting string is stored @emph{without} the newlines.
9896 .ds foo lots and lots \
9897 of text are on these \
9901 It is not possible to have real newlines in a string. To put a single
9902 double quote character into a string, use two consecutive double quote
9905 The @code{ds1} request turns off compatibility mode
9906 while interpreting a string. To be more precise, a @dfn{compatibility
9907 save} input token is inserted at the beginning of the string, and a
9908 @dfn{compatibility restore} input token at the end.
9912 .ds aa The value of xxx is \\n[xxx].
9913 .ds1 bb The value of xxx ix \\n[xxx].
9918 @result{} warning: number register `[' not defined
9919 @result{} The value of xxx is 0xxx].
9921 @result{} The value of xxx ix 12345.
9924 @cindex name space, common, of macros, diversions, and strings
9925 @cindex common name space of macros, diversions, and strings
9926 @cindex macros, shared name space with strings and diversions
9927 @cindex strings, shared name space with macros and diversions
9928 @cindex diversions, shared name space with macros and strings
9929 Strings, macros, and diversions (and boxes) share the same name space.
9930 Internally, even the same mechanism is used to store them. This has
9931 some interesting consequences. For example, it is possible to call a
9932 macro with string syntax and vice versa.
9939 @result{} This is a funny test.
9941 .ds yyy a funny test
9944 @result{} This is a funny test.
9947 Diversions and boxes can be also called with string syntax.
9949 Another consequence is that you can copy one-line diversions or boxes
9957 .ds yyy This is \*[xxx]\c
9959 @result{} @r{This is a }@i{test}.
9963 As the previous example shows, it is possible to store formatted
9964 output in strings. The @code{\c} escape prevents the insertion of an
9965 additional blank line in the output.
9967 Copying diversions longer than a single output line produces
9977 .ds yyy This is \*[xxx]\c
9979 @result{} test This is a funny.
9982 Usually, it is not predictable whether a diversion contains one or
9983 more output lines, so this mechanism should be avoided. With
9984 @acronym{UNIX} @code{troff}, this was the only solution to strip off a
9985 final newline from a diversion. Another disadvantage is that the
9986 spaces in the copied string are already formatted, making them
9987 unstretchable. This can cause ugly results.
9989 @cindex stripping final newline in diversions
9990 @cindex diversion, stripping final newline
9991 @cindex final newline, stripping in diversions
9992 @cindex newline, final, stripping in diversions
9993 @cindex horizontal space, unformatting
9994 @cindex space, horizontal, unformatting
9995 @cindex unformatting horizontal space
9996 A clean solution to this problem is available in GNU @code{troff},
9997 using the requests @code{chop} to remove the final newline of a
9998 diversion, and @code{unformat} to make the horizontal spaces
10011 @result{} This is a funny test.
10014 @xref{Gtroff Internals}, for more information.
10017 @DefreqList {as, name [@Var{string}]}
10018 @DefreqListEnd {as1, name [@Var{string}]}
10019 @cindex appending to a string (@code{as})
10020 @cindex string, appending (@code{as})
10021 The @code{as} request is similar to @code{ds} but appends @var{string}
10022 to the string stored as @var{name} instead of redefining it. If
10023 @var{name} doesn't exist yet, it is created.
10026 .as sign " with shallots, onions and garlic,
10029 The @code{as1} request is similar to @code{as}, but compatibility mode
10030 is switched off while the appended string is interpreted. To be more
10031 precise, a @dfn{compatibility save} input token is inserted at the
10032 beginning of the appended string, and a @dfn{compatibility restore}
10033 input token at the end.
10036 Rudimentary string manipulation routines are given with the next two
10039 @Defreq {substring, str n1 [@Var{n2}]}
10040 @cindex substring (@code{substring})
10041 Replace the string named @var{str} with the substring
10042 defined by the indices @var{n1} and@tie{}@var{n2}. The first character
10043 in the string has index@tie{}0. If @var{n2} is omitted, it is taken to
10044 be equal to the string's length. If the index value @var{n1} or
10045 @var{n2} is negative, it is counted from the end of the
10046 string, going backwards: The last character has index@tie{}@minus{}1, the
10047 character before the last character has index@tie{}@minus{}2, etc.
10051 .substring xxx 1 -4
10057 @Defreq {length, reg str}
10058 @cindex length of a string (@code{length})
10059 @cindex string, length of (@code{length})
10060 Compute the number of characters of @var{str} and return it in the
10061 number register @var{reg}. If @var{reg} doesn't exist, it is created.
10062 @code{str} is read in copy mode.
10065 .ds xxx abcd\h'3i'efgh
10066 .length yyy \*[xxx]
10072 @Defreq {rn, xx yy}
10073 @cindex renaming request (@code{rn})
10074 @cindex request, renaming (@code{rn})
10075 @cindex renaming macro (@code{rn})
10076 @cindex macro, renaming (@code{rn})
10077 @cindex renaming string (@code{rn})
10078 @cindex string, renaming (@code{rn})
10079 @cindex renaming diversion (@code{rn})
10080 @cindex diversion, renaming (@code{rn})
10081 Rename the request, macro, diversion, or string @var{xx} to @var{yy}.
10085 @cindex removing request (@code{rm})
10086 @cindex request, removing (@code{rm})
10087 @cindex removing macro (@code{rm})
10088 @cindex macro, removing (@code{rm})
10089 @cindex removing string (@code{rm})
10090 @cindex string, removing (@code{rm})
10091 @cindex removing diversion (@code{rm})
10092 @cindex diversion, removing (@code{rm})
10093 Remove the request, macro, diversion, or string @var{xx}. @code{gtroff}
10094 treats subsequent invocations as if the object had never been defined.
10097 @Defreq {als, new old}
10098 @cindex alias, string, creating (@code{als})
10099 @cindex alias, macro, creating (@code{als})
10100 @cindex alias, diversion, creating (@code{als})
10101 @cindex creating alias, for string (@code{als})
10102 @cindex creating alias, for macro (@code{als})
10103 @cindex creating alias, for diversion (@code{als})
10104 @cindex string, creating alias (@code{als})
10105 @cindex macro, creating alias (@code{als})
10106 @cindex diversion, creating alias (@code{als})
10107 Create an alias named @var{new} for the request, string, macro, or
10108 diversion object named @var{old}. The new name and the old name are
10109 exactly equivalent (it is similar to a hard rather than a soft
10110 link). If @var{old} is undefined, @code{gtroff} generates a warning of
10111 type @samp{mac} and ignores the request.
10115 Remove (chop) the last character from the macro, string, or diversion
10116 named @var{xx}. This is useful for removing the newline from the end
10117 of diversions that are to be interpolated as strings. This command
10118 can be used repeatedly; see @ref{Gtroff Internals}, for details on
10119 nodes inserted additionally by @code{gtroff}.
10122 @xref{Identifiers}, and @ref{Comments}.
10125 @c =====================================================================
10127 @node Conditionals and Loops, Writing Macros, Strings, gtroff Reference
10128 @section Conditionals and Loops
10129 @cindex conditionals and loops
10130 @cindex loops and conditionals
10133 * Operators in Conditionals::
10138 @c ---------------------------------------------------------------------
10140 @node Operators in Conditionals, if-else, Conditionals and Loops, Conditionals and Loops
10141 @subsection Operators in Conditionals
10143 @cindex @code{if} request, operators to use with
10144 @cindex @code{while} request, operators to use with
10145 In @code{if} and @code{while} requests, there are several more
10146 operators available:
10151 True if the current page is even or odd numbered (respectively).
10154 True if the document is being processed in nroff mode (i.e., the
10155 @code{.nroff} command has been issued).
10158 True if the document is being processed in troff mode (i.e., the
10159 @code{.troff} command has been issued).
10162 Always false. This condition is for compatibility with other
10163 @code{troff} versions only (identifying a @code{-Tversatec} device).
10165 @item '@var{xxx}'@var{yyy}'
10166 True if the string @var{xxx} is equal to the string @var{yyy}. Other
10167 characters can be used in place of the single quotes; the same set of
10168 delimiters as for the @code{\D} escape is used (@pxref{Escapes}).
10169 @code{gtroff} formats the strings before being compared:
10180 The resulting motions, glyph sizes, and fonts have to
10181 match,@footnote{The created output nodes must be identical.
10182 @xref{Gtroff Internals}.} and not the individual motion, size, and
10183 font requests. In the previous example, @samp{|} and @samp{\fR|\fP}
10184 both result in a roman @samp{|} glyph with the same point size and
10185 at the same location on the page, so the strings are equal. If
10186 @samp{.ft@tie{}I} had been added before the @samp{.ie}, the result
10187 would be ``false'' because (the first) @samp{|} produces an italic
10188 @samp{|} rather than a roman one.
10191 True if there is a number register named @var{xxx}.
10194 True if there is a string, macro, diversion, or request named @var{xxx}.
10197 True if there is a color named @var{xxx}.
10200 True if there is a glyph @var{g} available@footnote{The name of this
10201 conditional operator is a misnomer since it tests names of output
10202 glyphs.}; @var{g} is either an @acronym{ASCII} character or a special
10203 character (@code{\(@var{gg}} or @code{\[@var{ggg}]}); the condition
10204 is also true if @var{g} has been defined by the @code{char} request.
10207 Note that these operators can't be combined with other operators like
10208 @samp{:} or @samp{&}; only a leading @samp{!} (without whitespace
10209 between the exclamation mark and the operator) can be used to negate
10221 A whitespace after @samp{!} always evaluates to zero (this bizarre
10222 behaviour is due to compatibility with @acronym{UNIX} @code{troff}).
10230 @result{} r xxx true
10233 It is possible to omit the whitespace before the argument to the
10234 @samp{r}, @samp{d}, and @samp{c} operators.
10236 @xref{Expressions}.
10238 @c ---------------------------------------------------------------------
10240 @node if-else, while, Operators in Conditionals, Conditionals and Loops
10241 @subsection if-else
10244 @code{gtroff} has if-then-else constructs like other languages, although
10245 the formatting can be painful.
10247 @Defreq {if, expr anything}
10249 Evaluate the expression @var{expr}, and executes @var{anything} (the
10250 remainder of the line) if @var{expr} evaluates to a value greater than
10251 zero (true). @var{anything} is interpreted as though it was on a line
10252 by itself (except that leading spaces are swallowed).
10253 @xref{Expressions}, for more info.
10258 .if ((\n[xxx] == 1) & (\n[yyy] == 2)) true
10263 @Defreq{nop, anything}
10264 Executes @var{anything}.
10265 This is similar to @code{.if@tie{}1}.
10268 @DefreqList {ie, expr anything}
10269 @DefreqListEnd {el, anything}
10270 Use the @code{ie} and @code{el} requests to write an if-then-else.
10271 The first request is the `if' part and the latter is the `else' part.
10274 .ie n .ls 2 \" double-spacing in nroff
10275 .el .ls 1 \" single-spacing in troff
10279 @c there is a bug in makeinfo <= 4.1a: you can't have `@{' as an argument
10282 @c and in 4.2 you still can't use @{ in macros.
10284 @c @DefescList {\@{, , , }
10285 @c @DefescListEnd {\@}, , , }
10286 @deffn Escape @t{\@{}
10287 @deffnx Escape @t{\@}}
10290 @cindex begin of conditional block (@code{\@{})
10291 @cindex end of conditional block (@code{\@}})
10292 @cindex conditional block, begin (@code{\@{})
10293 @cindex conditional block, end (@code{\@}})
10294 @cindex block, conditional, begin (@code{\@{})
10295 @cindex block, condititional, end (@code{\@}})
10296 In many cases, an if (or if-else) construct needs to execute more than
10297 one request. This can be done using the @code{\@{} and @code{\@}}
10298 escapes. The following example shows the possible ways to use these
10299 escapes (note the position of the opening and closing braces).
10314 @xref{Expressions}.
10316 @c ---------------------------------------------------------------------
10318 @node while, , if-else, Conditionals and Loops
10322 @code{gtroff} provides a looping construct using the @code{while}
10323 request, which is used much like the @code{if} (and related) requests.
10325 @Defreq {while, expr anything}
10326 Evaluate the expression @var{expr}, and repeatedly execute
10327 @var{anything} (the remainder of the line) until @var{expr} evaluates
10332 .while (\na < 9) \@{\
10336 @result{} 1, 2, 3, 4, 5, 6, 7, 8, 9, 10
10341 @cindex @code{de} request, and @code{while}
10344 The body of a @code{while} request is treated like the body of a
10345 @code{de} request: @code{gtroff} temporarily stores it in a macro
10346 which is deleted after the loop has been exited. It can considerably
10347 slow down a macro if the body of the @code{while} request (within the
10348 macro) is large. Each time the macro is executed, the @code{while}
10349 body is parsed and stored again as a temporary macro.
10354 . while (\\n[num] > 0) \@{\
10355 . \" many lines of code
10361 @cindex recursive macros
10362 @cindex macros, recursive
10364 The traditional and ofter better solution (@acronym{UNIX} @code{troff}
10365 doesn't have the @code{while} request) is to use a recursive macro
10366 instead which is parsed only once during its definition.
10370 . if (\\n[num] > 0) \@{\
10371 . \" many lines of code
10384 Note that the number of available recursion levels is set to@tie{}1000
10385 (this is a compile-time constant value of @code{gtroff}).
10388 The closing brace of a @code{while} body must end a line.
10393 . while (\n[a] < 10) \@{\
10396 @result{} unbalanced \@{ \@}
10402 @cindex @code{while} request, confusing with @code{br}
10403 @cindex @code{break} request, in a @code{while} loop
10404 @cindex @code{continue} request, in a @code{while} loop
10405 Break out of a @code{while} loop. Be sure not to confuse this with
10406 the @code{br} request (causing a line break).
10409 @Defreq {continue, }
10410 Finish the current iteration of a @code{while} loop, immediately
10411 restarting the next iteration.
10414 @xref{Expressions}.
10417 @c =====================================================================
10419 @node Writing Macros, Page Motions, Conditionals and Loops, gtroff Reference
10420 @section Writing Macros
10421 @cindex writing macros
10422 @cindex macros, writing
10424 A @dfn{macro} is a collection of text and embedded commands which can
10425 be invoked multiple times. Use macros to define common operations.
10427 @DefreqList {de, name [@Var{end}]}
10428 @DefreqItem {de1, name [@Var{end}]}
10429 @DefreqItem {dei, name [@Var{end}]}
10430 @DefreqListEnd {dei1, name [@Var{end}]}
10431 Define a new macro named @var{name}. @code{gtroff} copies subsequent
10432 lines (starting with the next one) into an internal buffer until it
10433 encounters the line @samp{..} (two dots). The optional second
10434 argument to @code{de} changes this to a macro to @samp{.@var{end}}.
10436 There can be whitespace after the first dot in the line containing the
10437 ending token (either @samp{.} or macro @samp{@var{end}}).
10439 Here a small example macro called @samp{P} which causes a break and
10440 inserts some vertical space. It could be used to separate paragraphs.
10449 The following example defines a macro within another. Remember that
10450 expansion must be protected twice; once for reading the macro and
10451 once for executing.
10454 \# a dummy macro to avoid a warning
10460 . nop \f[B]Hallo \\\\$1!\f[]
10466 @result{} @b{Hallo Joe!}
10470 Since @code{\f} has no expansion, it isn't necessary to protect its
10471 backslash. Had we defined another macro within @code{bar} which takes
10472 a parameter, eight backslashes would be necessary before @samp{$1}.
10474 The @code{de1} request turns off compatibility mode
10475 while executing the macro. On entry, the current compatibility mode
10476 is saved and restored at exit.
10482 The value of xxx is \\n[xxx].
10485 The value of xxx ix \\n[xxx].
10491 @result{} warning: number register
\e' not defined
10492 @result{} The value of xxx is 0xxx].
10494 @result{} The value of xxx ix 12345.
10497 The @code{dei} request defines a macro indirectly.
10498 That is, it expands strings whose names
10499 are @var{name} or @var{end} before performing the append.
10516 The @code{dei1} request is similar to @code{dei} but with compatibility
10517 mode switched off during execution of the defined macro.
10520 Using @file{trace.tmac}, you can trace calls to @code{de} and @code{de1}.
10522 Note that macro identifiers are shared with identifiers for strings and
10526 @DefreqList {am, name [@Var{end}]}
10527 @DefreqItem {am1, name [@Var{end}]}
10528 @DefreqItem {ami, name [@Var{end}]}
10529 @DefreqListEnd {ami1, name [@Var{end}]}
10530 @cindex appending to a macro (@code{am})
10531 @cindex macro, appending (@code{am})
10532 Works similarly to @code{de} except it appends onto the macro named
10533 @var{name}. So, to make the previously defined @samp{P} macro actually
10534 do indented instead of block paragraphs, add the necessary code to the
10535 existing macro like this:
10543 The @code{am1} request turns off compatibility mode
10544 while executing the appended macro piece. To be more precise, a
10545 @dfn{compatibility save} input token is inserted at the beginning of
10546 the appended code, and a @dfn{compatibility restore} input token at
10549 The @code{ami} request appends indirectly,
10550 meaning that @code{gtroff} expands strings whose names
10551 are @var{name} or @var{end} before performing the append.
10553 The @code{ami1} request is similar to @code{ami} but compatibility mode
10554 is switched off during execution of the defined macro.
10557 Using @file{trace.tmac}, you can trace calls to @code{am} and @code{am1}.
10560 @xref{Strings}, for the @code{als} request to rename a macro.
10562 The @code{de}, @code{am}, @code{di}, @code{da}, @code{ds}, and
10563 @code{as} requests (together with its variants) only create a new object
10564 if the name of the macro, diversion or string diversion is currently
10565 undefined or if it is defined to be a request; normally they modify the
10566 value of an existing object.
10568 @Defreq {return, [@Var{anything}]}
10569 Exit a macro, immediately returning to the caller.
10571 If called with an argument, exit twice, namely the current macro and the
10572 macro one level higher. This is used to define a wrapper macro for
10573 @code{return} in @file{trace.tmac}.
10581 @c ---------------------------------------------------------------------
10583 @node Copy-in Mode, Parameters, Writing Macros, Writing Macros
10584 @subsection Copy-in Mode
10585 @cindex copy-in mode
10586 @cindex mode, copy-in
10588 @cindex @code{\n}, when reading text for a macro
10589 @cindex @code{\$}, when reading text for a macro
10590 @cindex @code{\*}, when reading text for a macro
10591 @cindex @code{\\}, when reading text for a macro
10592 @cindex \@key{RET}, when reading text for a macro
10593 When @code{gtroff} reads in the text for a macro, string, or diversion,
10594 it copies the text (including request lines, but excluding escapes) into
10595 an internal buffer. Escapes are converted into an internal form,
10596 except for @code{\n}, @code{\$}, @code{\*}, @code{\\} and
10597 @code{\@key{RET}} which are evaluated and inserted into the text where
10598 the escape was located. This is known as @dfn{copy-in} mode or
10601 What this means is that you can specify when these escapes are to be
10602 evaluated (either at copy-in time or at the time of use) by insulating
10603 the escapes with an extra backslash. Compare this to the @code{\def}
10604 and @code{\edef} commands in @TeX{}.
10606 The following example prints the numbers 20 and@tie{}10:
10618 @c ---------------------------------------------------------------------
10620 @node Parameters, , Copy-in Mode, Writing Macros
10621 @subsection Parameters
10624 The arguments to a macro or string can be examined using a variety of
10628 @cindex number of arguments register (@code{.$})
10629 The number of arguments passed to a macro or string. This is a read-only
10632 Note that the @code{shift} request can change its value.
10635 Any individual argument can be retrieved with one of the following
10638 @DefescList {\\$, , n, }
10639 @DefescItem {\\$, @lparen{}, nn, }
10640 @DefescListEnd {\\$, @lbrack{}, nnn, @rbrack{}}
10641 @cindex copy-in mode, and macro arguments
10642 @cindex macro, arguments (@code{\$})
10643 @cindex arguments, macro (@code{\$})
10644 Retrieve the @var{n}@dmn{th}, @var{nn}@dmn{th} or @var{nnn}@dmn{th}
10645 argument. As usual, the first form only accepts a single number
10646 (larger than zero), the second a two-digit number (larger or equal
10647 to@tie{}10), and the third any positive integer value (larger
10648 than zero). Macros and strings can have an unlimited number of arguments.
10649 Note that due to copy-in mode, use two backslashes on these in actual use
10650 to prevent interpolation until the macro is actually invoked.
10653 @Defreq {shift, [@Var{n}]}
10654 Shift the arguments 1@tie{}position, or as
10655 many positions as specified by its argument. After executing this
10656 request, argument@tie{}@var{i} becomes argument @math{@var{i}-@var{n}};
10657 arguments 1 to@tie{}@var{n} are no longer available. Shifting by
10658 negative amounts is currently undefined.
10660 The register @code{.$} is adjusted accordingly.
10663 @DefescList {\\$*, , , }
10664 @DefescListEnd {\\$@@, , , }
10665 In some cases it is convenient to use all of the arguments at once (for
10666 example, to pass the arguments along to another macro). The @code{\$*}
10667 escape concatenates all the arguments separated by spaces. A
10668 similar escape is @code{\$@@}, which concatenates all the
10669 arguments with each surrounded by double quotes, and separated by
10670 spaces. If not in compatibility mode, the input level of double quotes
10671 is preserved (see @ref{Request and Macro Arguments}).
10674 @Defesc {\\$0, , , }
10675 @cindex macro name register (@code{\$0})
10676 @cindex @code{als} request, and @code{\$0}
10677 The name used to invoke the current macro.
10678 The @code{als} request can make a macro have more than one name.
10683 . if \\n[error] \@{\
10684 . tm \\$0: Houston, we have a problem.
10689 .als foo generic-macro
10690 .als bar generic-macro
10694 @xref{Request and Macro Arguments}.
10697 @c =====================================================================
10699 @node Page Motions, Drawing Requests, Writing Macros, gtroff Reference
10700 @section Page Motions
10701 @cindex page motions
10702 @cindex motions, page
10704 @xref{Manipulating Spacing}, for a discussion of the main request for
10705 vertical motion, @code{sp}.
10707 @DefreqList {mk, [@Var{reg}]}
10708 @DefreqListEnd {rt, [@Var{dist}]}
10709 @cindex marking vertical page location (@code{mk})
10710 @cindex page location, vertical, marking (@code{mk})
10711 @cindex location, vertical, page, marking (@code{mk})
10712 @cindex vertical page location, marking (@code{mk})
10713 @cindex returning to marked vertical page location (@code{rt})
10714 @cindex page location, vertical, returning to marked (@code{rt})
10715 @cindex location, vertical, page, returning to marked (@code{rt})
10716 @cindex vertical page location, returning to marked (@code{rt})
10717 The request @code{mk} can be used to mark a location on a page, for
10718 movement to later. This request takes a register name as an argument
10719 in which to store the current page location. With no argument it
10720 stores the location in an internal register. The results of this can
10721 be used later by the @code{rt} or the @code{sp} request (or the
10724 The @code{rt} request returns @emph{upwards} to the location marked
10725 with the last @code{mk} request. If used with an argument, return to
10726 a position which distance from the top of the page is @var{dist} (no
10727 previous call to @code{mk} is necessary in this case). Default scaling
10728 indicator is @samp{v}.
10730 Here a primitive solution for a two-column macro.
10733 .nr column-length 1.5i
10735 .nr bottom-margin 1m
10742 . ll \\n[column-length]u
10743 . wh -\\n[bottom-margin]u 2c-trap
10750 . ie \\n[right-side] \@{\
10752 . po -(\\n[column-length]u + \\n[column-gap]u)
10754 . wh -\\n[bottom-margin]u
10757 . \" switch to right side
10759 . po +(\\n[column-length]u + \\n[column-gap]u)
10768 This is a small test which shows how the
10769 rt request works in combination with mk.
10772 Starting here, text is typeset in two columns.
10773 Note that this implementation isn't robust
10774 and thus not suited for a real two-column
10781 This is a small test which shows how the
10782 rt request works in combination with mk.
10784 Starting here, isn't robust
10785 text is typeset and thus not
10786 in two columns. suited for a
10787 Note that this real two-column
10788 implementation macro.
10792 The following escapes give fine control of movements about the page.
10794 @Defesc {\\v, ', e, '}
10795 @cindex vertical motion (@code{\v})
10796 @cindex motion, vertical (@code{\v})
10797 Move vertically, usually from the current location on the page (if no
10798 absolute position operator @samp{|} is used). The
10799 argument@tie{}@var{e} specifies the distance to move; positive is
10800 downwards and negative upwards. The default scaling indicator for this
10801 escape is @samp{v}. Beware, however, that @code{gtroff} continues text
10802 processing at the point where the motion ends, so you should always
10803 balance motions to avoid interference with text processing.
10805 @code{\v} doesn't trigger a trap. This can be quite useful; for example,
10806 consider a page bottom trap macro which prints a marker in the margin to
10807 indicate continuation of a footnote or something similar.
10810 There are some special-case escapes for vertical motion.
10812 @Defesc {\\r, , , }
10813 Move upwards@tie{}1@dmn{v}.
10816 @Defesc {\\u, , , }
10817 Move upwards@tie{}.5@dmn{v}.
10820 @Defesc {\\d, , , }
10821 Move down@tie{}.5@dmn{v}.
10824 @Defesc {\\h, ', e, '}
10825 @cindex inserting horizontal space (@code{\h})
10826 @cindex horizontal space (@code{\h})
10827 @cindex space, horizontal (@code{\h})
10828 @cindex horizontal motion (@code{\h})
10829 @cindex motion, horizontal (@code{\h})
10830 Move horizontally, usually from the current location (if no absolute
10831 position operator @samp{|} is used). The expression@tie{}@var{e}
10832 indicates how far to move: positive is rightwards and negative
10833 leftwards. The default scaling indicator for this escape is @samp{m}.
10835 This horizontal space is not discarded at the end of a line. To insert
10836 discardable space of a certain length use the @code{ss} request.
10839 There are a number of special-case escapes for horizontal motion.
10841 @Defesc {\\@key{SP}, , , }
10842 @cindex space, unbreakable
10843 @cindex unbreakable space
10844 An unbreakable and unpaddable (i.e.@: not expanded during filling)
10845 space. (Note: This is a backslash followed by a space.)
10848 @Defesc {\\~, , , }
10849 An unbreakable space that stretches like a normal inter-word space
10850 when a line is adjusted.
10853 @Defesc {\\|, , , }
10854 A 1/6@dmn{th} em space. Ignored for TTY output devices (rounded to
10858 @Defesc {\\^, , , }
10859 A 1/12@dmn{th} em space. Ignored for TTY output devices (rounded to
10863 @Defesc {\\0, , , }
10864 @cindex space, width of a digit (@code{\0})
10865 @cindex digit width space (@code{\0})
10866 A space the size of a digit.
10869 The following string sets the @TeX{} logo:
10872 .ds TeX T\h'-.1667m'\v'.224m'E\v'-.224m'\h'-.125m'X
10875 @DefescList {\\w, ', text, '}
10882 @DefregListEnd {skw}
10883 @cindex width escape (@code{\w})
10884 Return the width of the specified @var{text} in basic units.
10885 This allows horizontal movement based on the width of some
10886 arbitrary text (e.g.@: given as an argument to a macro).
10889 The length of the string `abc' is \w'abc'u.
10890 @result{} The length of the string `abc' is 72u.
10893 Font changes may occur in @var{text} which don't affect current
10896 After use, @code{\w} sets several registers:
10901 The highest and lowest point of the baseline, respectively, in @var{text}.
10905 Like the @code{st} and @code{sb} registers, but takes account of the
10906 heights and depths of glyphs. With other words, this gives the
10907 highest and lowest point of @var{text}. Values below the baseline are
10911 Defines the kinds of glyphs occurring in @var{text}:
10915 only short glyphs, no descenders or tall glyphs.
10918 at least one descender.
10921 at least one tall glyph.
10924 at least one each of a descender and a tall glyph.
10928 The amount of horizontal space (possibly negative) that should be added
10929 to the last glyph before a subscript.
10932 How far to right of the center of the last glyph in the @code{\w}
10933 argument, the center of an accent from a roman font should be placed
10938 @DefescList {\\k, , p, }
10939 @DefescItem {\\k, @lparen{}, ps, }
10940 @DefescListEnd {\\k, @lbrack{}, position, @rbrack}
10941 @cindex saving horizontal input line position (@code{\k})
10942 @cindex horizontal input line position, saving (@code{\k})
10943 @cindex input line position, horizontal, saving (@code{\k})
10944 @cindex position, horizontal input line, saving (@code{\k})
10945 @cindex line, input, horizontal position, saving (@code{\k})
10946 Store the current horizontal position in the @emph{input} line in
10947 number register with name @var{position} (one-character name@tie{}@var{p},
10948 two-character name @var{ps}). Use this, for example, to return to the
10949 beginning of a string for highlighting or other decoration.
10953 @cindex horizontal input line position register (@code{hp})
10954 @cindex input line, horizontal position, register (@code{hp})
10955 @cindex position, horizontal, in input line, register (@code{hp})
10956 @cindex line, input, horizontal position, register (@code{hp})
10957 The current horizontal position at the input line.
10961 @cindex horizontal output line position register (@code{.k})
10962 @cindex output line, horizontal position, register (@code{.k})
10963 @cindex position, horizontal, in output line, register (@code{.k})
10964 @cindex line, output, horizontal position, register (@code{.k})
10965 A read-only number register containing the current horizontal output
10966 position (relative to the current indentation).
10969 @Defesc {\\o, ', abc, '}
10970 @cindex overstriking glyphs (@code{\o})
10971 @cindex glyphs, overstriking (@code{\o})
10972 Overstrike glyphs @var{a}, @var{b}, @var{c}, @dots{}; the glyphs
10973 are centered, and the resulting spacing is the largest width of the
10977 @Defesc {\\z, , g, , }
10978 @cindex zero-width printing (@code{\z}, @code{\Z})
10979 @cindex printing, zero-width (@code{\z}, @code{\Z})
10980 Print glyph @var{g} with zero width, i.e., without spacing. Use
10981 this to overstrike glyphs left-aligned.
10984 @Defesc {\\Z, ', anything, '}
10985 @cindex zero-width printing (@code{\z}, @code{\Z})
10986 @cindex printing, zero-width (@code{\z}, @code{\Z})
10987 Print @var{anything}, then restore the horizontal and vertical position.
10988 The argument may not contain tabs or leaders.
10990 The following is an example of a strike-through macro:
10995 \Z@@\v'-.25m'\l'\\n[ww]u'@@\\$1
11000 an actual emergency!
11005 @c =====================================================================
11007 @node Drawing Requests, Traps, Page Motions, gtroff Reference
11008 @section Drawing Requests
11009 @cindex drawing requests
11010 @cindex requests for drawing
11012 @code{gtroff} provides a number of ways to draw lines and other figures
11013 on the page. Used in combination with the page motion commands (see
11014 @ref{Page Motions}, for more info), a wide variety of figures can be
11015 drawn. However, for complex drawings these operations can be quite
11016 cumbersome, and it may be wise to use graphic preprocessors like
11017 @code{gpic} or @code{ggrn}. @xref{gpic}, and @ref{ggrn}, for more
11020 All drawing is done via escapes.
11022 @DefescList {\\l, ', l, '}
11023 @DefescListEnd {\\l, ', lg, '}
11024 @cindex drawing horizontal lines (@code{\l})
11025 @cindex horizontal line, drawing (@code{\l})
11026 @cindex line, horizontal, drawing (@code{\l})
11027 Draw a line horizontally. @var{l} is the length of the line to be
11028 drawn. If it is positive, start the line at the current location and
11029 draw to the right; its end point is the new current location. Negative
11030 values are handled differently: The line starts at the current location
11031 and draws to the left, but the current location doesn't move.
11033 @var{l} can also be specified absolutely (i.e.@: with a leading
11034 @samp{|}) which draws back to the beginning of the input line.
11035 Default scaling indicator is @samp{m}.
11037 @cindex underscore glyph (@code{\[ru]})
11038 @cindex glyph, underscore (@code{\[ru]})
11039 @cindex line drawing glyph
11040 @cindex glyph, for line drawing
11041 The optional second parameter@tie{}@var{g} is a glyph to draw the line
11042 with. If this second argument is not specified, @code{gtroff} uses
11043 the underscore glyph, @code{\[ru]}.
11045 @cindex zero width space character (@code{\&})
11046 @cindex character, zero width space (@code{\&})
11047 @cindex space character, zero width (@code{\&})
11048 To separate the two arguments (to prevent @code{gtroff} from
11049 interpreting a drawing glyph as a scaling indicator if the glyph is
11050 represented by a single character) use @code{\&}.
11052 Here a small useful example:
11056 \[br]\\$*\[br]\l'|0\[rn]'\l'|0\[ul]'
11061 Note that this works by outputting a box rule (a vertical line), then
11062 the text given as an argument and then another box rule. Finally, the
11063 line drawing escapes both draw from the current location to the
11064 beginning of the @emph{input} line -- this works because the line
11065 length is negative, not moving the current point.
11068 @DefescList {\\L, ', l, '}
11069 @DefescListEnd {\\L, ', lg, '}
11070 @cindex drawing vertical lines (@code{\L})
11071 @cindex vertical line drawing (@code{\L})
11072 @cindex line, vertical, drawing (@code{\L})
11073 @cindex line drawing glyph
11074 @cindex glyph for line drawing
11075 @cindex box rule glyph (@code{\[br]})
11076 @cindex glyph, box rule (@code{\[br]})
11077 Draw vertical lines. Its parameters are
11078 similar to the @code{\l} escape, except that the default scaling
11079 indicator is @samp{v}. The movement is downwards for positive values,
11080 and upwards for negative values. The default glyph is the box rule
11081 glyph, @code{\[br]}. As with the vertical motion escapes, text
11082 processing blindly continues where the line ends.
11085 This is a \L'3v'test.
11089 Here the result, produced with @code{grotty}.
11099 @Defesc {\\D, ', command arg @dots{}, '}
11100 The @code{\D} escape provides a variety of drawing functions.
11101 Note that on character devices, only vertical and horizontal lines are
11102 supported within @code{grotty}; other devices may only support a subset
11103 of the available drawing functions.
11105 The default scaling indicator for all subcommands of @code{\D} is
11106 @samp{m} for horizontal distances and @samp{v} for vertical ones.
11107 Exceptions are @w{@code{\D'f @dots{}'}} and @w{@code{\D't @dots{}'}}
11108 which use @code{u} as the default, and @w{@code{\D'F@var{x} @dots{}'}}
11109 which arguments are treated similar to the @code{defcolor} request.
11112 @item \D'l @var{dx} @var{dy}'
11113 @cindex line, drawing (@w{@code{\D'l @dots{}'}})
11114 @cindex drawing a line (@w{@code{\D'l @dots{}'}})
11115 Draw a line from the current location to the relative point specified by
11116 (@var{dx},@var{dy}), where positive values mean down and right,
11117 respectively. The end point of the line is the new current location.
11119 The following example is a macro for creating a box around a text string;
11120 for simplicity, the box margin is taken as a fixed value, 0.2@dmn{m}.
11126 \h'-.2m'\v'(.2m - \\n[rsb]u)'\
11127 \D'l 0 -(\\n[rst]u - \\n[rsb]u + .4m)'\
11128 \D'l (\\n[@@wd]u + .4m) 0'\
11129 \D'l 0 (\\n[rst]u - \\n[rsb]u + .4m)'\
11130 \D'l -(\\n[@@wd]u + .4m) 0'\
11131 \h'.2m'\v'-(.2m - \\n[rsb]u)'\
11138 First, the width of the string is stored in register @code{@@wd}. Then,
11139 four lines are drawn to form a box, properly offset by the box margin.
11140 The registers @code{rst} and @code{rsb} are set by the @code{\w} escape,
11141 containing the largest height and depth of the whole string.
11143 @item \D'c @var{d}'
11144 @cindex circle, drawing (@w{@code{\D'c @dots{}'}})
11145 @cindex drawing a circle (@w{@code{\D'c @dots{}'}})
11146 Draw a circle with a diameter of@tie{}@var{d} with the leftmost point at the
11147 current position. After drawing, the current location is positioned at the
11148 rightmost point of the circle.
11150 @item \D'C @var{d}'
11151 @cindex circle, solid, drawing (@w{@code{\D'C @dots{}'}})
11152 @cindex drawing a solid circle (@w{@code{\D'C @dots{}'}})
11153 @cindex solid circle, drawing (@w{@code{\D'C @dots{}'}})
11154 Draw a solid circle with the same parameters and behaviour as an outlined
11155 circle. No outline is drawn.
11157 @item \D'e @var{x} @var{y}'
11158 @cindex drawing an ellipse (@w{@code{\D'e @dots{}'}})
11159 @cindex ellipse, drawing (@w{@code{\D'e @dots{}'}})
11160 Draw an ellipse with a horizontal diameter of @var{x} and a vertical
11161 diameter of @var{y} with the leftmost point at the current position.
11162 After drawing, the current location is positioned at the rightmost point of
11165 @item \D'E @var{x} @var{y}'
11166 @cindex ellipse, solid, drawing (@w{@code{\D'E @dots{}'}})
11167 @cindex drawing a solid ellipse (@w{@code{\D'E @dots{}'}})
11168 @cindex solid ellipse, drawing (@w{@code{\D'E @dots{}'}})
11169 Draw a solid ellipse with the same parameters and behaviour as an
11170 outlined ellipse. No outline is drawn.
11172 @item \D'a @var{dx1} @var{dy1} @var{dx2} @var{dy2}'
11173 @cindex arc, drawing (@w{@code{\D'a @dots{}'}})
11174 @cindex drawing an arc (@w{@code{\D'a @dots{}'}})
11175 Draw an arc clockwise from the current location through the two
11176 specified relative locations (@var{dx1},@var{dy1}) and
11177 (@var{dx2},@var{dy2}). The coordinates of the first point are relative
11178 to the current position, and the coordinates of the second point are
11179 relative to the first point. After drawing, the current position is moved
11180 to the final point of the arc.
11182 @item \D'~ @var{dx1} @var{dy1} @var{dx2} @var{dy2} @dots{}'
11183 @cindex drawing a spline (@w{@code{\D'~ @dots{}'}})
11184 @cindex spline, drawing (@w{@code{\D'~ @dots{}'}})
11185 Draw a spline from the current location to the relative point
11186 (@var{dx1},@var{dy1}) and then to (@var{dx2},@var{dy2}), and so on.
11187 The current position is moved to the terminal point of the drawn curve.
11189 @item \D'f @var{n}'
11190 @cindex gray shading (@w{@code{\D'f @dots{}'}})
11191 @cindex shading filled objects (@w{@code{\D'f @dots{}'}})
11192 Set the shade of gray to be used for filling solid objects to@tie{}@var{n};
11193 @var{n}@tie{}must be an integer between 0 and@tie{}1000, where 0
11194 corresponds solid white and 1000 to solid black, and values in between
11195 correspond to intermediate shades of gray. This applies only to solid
11196 circles, solid ellipses, and solid polygons. By default, a level of
11199 Despite of being silly, the current point is moved horizontally to the
11200 right by@tie{}@var{n}.
11202 @cindex @w{@code{\D'f @dots{}'}} and horizontal resolution
11203 Don't use this command! It has the serious drawback that it will be
11204 always rounded to the next integer multiple of the horizontal resolution
11205 (the value of the @code{hor} keyword in the @file{DESC} file). Use
11206 @code{\M} (@pxref{Colors}) or @w{@code{\D'Fg @dots{}'}} instead.
11208 @item \D'p @var{dx1} @var{dy1} @var{dx2} @var{dy2} @dots{}'
11209 @cindex drawing a polygon (@w{@code{\D'p @dots{}'}})
11210 @cindex polygon, drawing (@w{@code{\D'p @dots{}'}})
11211 Draw a polygon from the current location to the relative position
11212 (@var{dx1},@var{dy1}) and then to (@var{dx2},@var{dy2}) and so on.
11213 When the specified data points are exhausted, a line is drawn back
11214 to the starting point. The current position is changed by adding the
11215 sum of all arguments with odd index to the actual horizontal position and
11216 the even ones to the vertical position.
11218 @item \D'P @var{dx1} @var{dy1} @var{dx2} @var{dy2} @dots{}'
11219 @cindex polygon, solid, drawing (@w{@code{\D'P @dots{}'}})
11220 @cindex drawing a solid polygon (@w{@code{\D'P @dots{}'}})
11221 @cindex solid polygon, drawing (@w{@code{\D'P @dots{}'}})
11222 Draw a solid polygon with the same parameters and behaviour as an
11223 outlined polygon. No outline is drawn.
11225 Here a better variant of the box macro to fill the box with some color.
11226 Note that the box must be drawn before the text since colors in
11227 @code{gtroff} are not transparent; the filled polygon would hide the
11234 \h'-.2m'\v'(.2m - \\n[rsb]u)'\
11236 \D'P 0 -(\\n[rst]u - \\n[rsb]u + .4m) \
11237 (\\n[@@wd]u + .4m) 0 \
11238 0 (\\n[rst]u - \\n[rsb]u + .4m) \
11239 -(\\n[@@wd]u + .4m) 0'\
11240 \h'.2m'\v'-(.2m - \\n[rsb]u)'\
11247 @item \D't @var{n}'
11248 @cindex line thickness (@w{@code{\D't @dots{}'}})
11249 @cindex thickness of lines (@w{@code{\D't @dots{}'}})
11250 Set the current line thickness to @var{n}@tie{}machine units. A value of
11251 zero selects the smallest available line thickness. A negative value
11252 makes the line thickness proportional to the current point size (this is
11253 the default behaviour of @acronym{AT&T} @code{troff}).
11255 Despite of being silly, the current point is moved horizontally to the
11256 right by@tie{}@var{n}.
11258 @item \D'F@var{scheme} @var{color_components}'
11259 @cindex unnamed fill colors (@code{\D'F@dots{}'})
11260 @cindex fill colors, unnamed (@code{\D'F@dots{}'})
11261 @cindex colors, fill, unnamed (@code{\D'F@dots{}'})
11262 Change current fill color. @var{scheme} is a single letter denoting the
11263 color scheme: @samp{r} (rgb), @samp{c} (cmy), @samp{k} (cmyk), @samp{g}
11264 (gray), or @samp{d} (default color). The color components use exactly
11265 the same syntax as in the @code{defcolor} request (@pxref{Colors}); the
11266 command @code{\D'Fd'} doesn't take an argument.
11268 @emph{No} position changing!
11274 \D'Fg .3' \" same gray as \D'f 700'
11275 \D'Fr #0000ff' \" blue
11279 @xref{Graphics Commands}.
11281 @Defesc {\\b, ', string, '}
11282 @cindex pile, glyph (@code{\b})
11283 @cindex glyph pile (@code{\b})
11284 @cindex stacking glyphs (@code{\b})
11285 @dfn{Pile} a sequence of glyphs vertically, and center it vertically
11286 on the current line. Use it to build large brackets and braces.
11288 Here an example how to create a large opening brace:
11291 \b'\[lt]\[bv]\[lk]\[bv]\[lb]'
11294 @cindex @code{\b}, limitations
11295 @cindex limitations of @code{\b} escape
11296 The first glyph is on the top, the last glyph in @var{string} is
11297 at the bottom. Note that @code{gtroff} separates the glyphs
11298 vertically by 1@dmn{m}, and the whole object is centered 0.5@dmn{m}
11299 above the current baseline; the largest glyph width is used as the
11300 width for the whole object. This rather unflexible positioning
11301 algorithm doesn't work with @option{-Tdvi} since the bracket pieces vary
11302 in height for this device. Instead, use the @code{eqn} preprocessor.
11304 @xref{Manipulating Spacing}, how to adjust the vertical spacing with
11305 the @code{\x} escape.
11309 @c =====================================================================
11311 @node Traps, Diversions, Drawing Requests, gtroff Reference
11315 @dfn{Traps} are locations, which, when reached, call a specified
11316 macro. These traps can occur at a given location on the page, at a
11317 given location in the current diversion, at a blank line,
11318 after a certain number of input lines, or at the end of input.
11320 @cindex planting a trap
11321 @cindex trap, planting
11322 Setting a trap is also called @dfn{planting}.
11323 @cindex trap, springing
11324 @cindex springing a trap
11325 It is also said that a trap is @dfn{sprung} if the associated macro
11329 * Page Location Traps::
11330 * Diversion Traps::
11331 * Input Line Traps::
11332 * Blank Line Traps::
11333 * End-of-input Traps::
11336 @c ---------------------------------------------------------------------
11338 @node Page Location Traps, Diversion Traps, Traps, Traps
11339 @subsection Page Location Traps
11340 @cindex page location traps
11341 @cindex traps, page location
11343 @dfn{Page location traps} perform an action when @code{gtroff}
11344 reaches or passes a certain vertical location on the page. Page
11345 location traps have a variety of purposes, including:
11349 setting headers and footers
11352 setting body text in multiple columns
11358 @DefreqList {vpt, flag}
11359 @DefregListEnd {.vpt}
11360 @cindex enabling vertical position traps (@code{vpt})
11361 @cindex vertical position traps, enabling (@code{vpt})
11362 @cindex vertical position trap enable register (@code{.vpt})
11363 Enable vertical position traps if @var{flag} is non-zero, or disables
11364 them otherwise. Vertical position traps are traps set by the @code{wh}
11365 or @code{dt} requests. Traps set by the @code{it} request are not
11366 vertical position traps. The parameter that controls whether vertical
11367 position traps are enabled is global. Initially vertical position traps
11368 are enabled. The current setting of this is available in the
11369 @code{.vpt} read-only number register.
11371 Note that a page can't be ejected if @code{vpt} is set to zero.
11374 @Defreq {wh, dist [@Var{macro}]}
11375 Set a page location trap. Non-negative values for @var{dist} set
11376 the trap relative to the top of the page; negative values set
11377 the trap relative to the bottom of the page. Default scaling
11378 indicator is @samp{v}.
11380 @var{macro} is the name of the macro to execute when the
11381 trap is sprung. If @var{macro} is missing, remove the first trap
11382 (if any) at @var{dist}.
11384 @cindex page headers
11385 @cindex page footers
11388 The following is a simple example of how many macro packages
11389 set headers and footers.
11392 .de hd \" Page header
11398 .de fo \" Page footer
11404 .wh 0 hd \" trap at top of the page
11405 .wh -1i fo \" trap one inch from bottom
11408 A trap at or below the bottom of the page is ignored; it can be made
11409 active by either moving it up or increasing the page length so that the
11410 trap is on the page.
11412 It is possible to have more than one trap at the same location; to do so,
11413 the traps must be defined at different locations, then moved together with
11414 the @code{ch} request; otherwise the second trap would replace the first
11415 one. Earlier defined traps hide later defined traps if moved to the same
11416 position (the many empty lines caused by the @code{bp} request are omitted
11417 in the following example):
11450 @cindex distance to next trap register (@code{.t})
11451 @cindex trap, distance, register (@code{.t})
11452 A read-only number register holding the distance to the next trap.
11454 If there are no traps between the current position and the bottom of the
11455 page, it contains the distance to the page bottom. In a diversion, the
11456 distance to the page bottom is infinite (the returned value is the biggest
11457 integer which can be represented in @code{groff}) if there are no diversion
11461 @Defreq {ch, macro [@Var{dist}]}
11462 @cindex changing trap location (@code{ch})
11463 @cindex trap, changing location (@code{ch})
11464 Change the location of a trap.
11465 The first argument is the name of the macro to be invoked at
11466 the trap, and the second argument is the new location for the trap
11467 (note that the parameters are specified in opposite order as in the
11468 @code{wh} request). This is useful for building up footnotes in a
11469 diversion to allow more space at the bottom of the page for them.
11471 Default scaling indicator for @var{dist} is @samp{v}. If @var{dist}
11472 is missing, the trap is removed.
11478 ... (simplified) footnote example ...
11484 The read-only number register @code{.ne} contains the amount of space
11485 that was needed in the last @code{ne} request that caused a trap to be
11486 sprung. Useful in conjunction with the @code{.trunc} register.
11487 @xref{Page Control}, for more information.
11489 Since the @code{.ne} register is only set by traps it doesn't make
11490 much sense to use it outside of trap macros.
11494 @cindex @code{ne} request, and the @code{.trunc} register
11495 @cindex truncated vertical space register (@code{.trunc})
11496 A read-only register containing the amount of vertical space truncated
11497 by the most recently sprung vertical position trap, or, if the trap was
11498 sprung by an @code{ne} request, minus the amount of vertical motion
11499 produced by the @code{ne} request. In other words, at the point a trap
11500 is sprung, it represents the difference of what the vertical position
11501 would have been but for the trap, and what the vertical position
11504 Since the @code{.trunc} register is only set by traps it doesn't make
11505 much sense to use it outside of trap macros.
11509 @cindex @code{bp} request, and traps (@code{.pe})
11510 @cindex traps, sprung by @code{bp} request (@code{.pe})
11511 @cindex page ejecting register (@code{.pe})
11512 A read-only register which is set to@tie{}1 while a page is ejected with
11513 the @code{bp} request (or by the end of input).
11515 Outside of traps this register is always zero. In the following example,
11516 only the second call to@tie{}@code{x} is caused by @code{bp}.
11537 @cindex diversions, and traps
11538 @cindex traps, and diversions
11539 An important fact to consider while designing macros is that diversions and
11540 traps do not interact normally. For example, if a trap invokes a header
11541 macro (while outputting a diversion) which tries to change the font on the
11542 current page, the effect will not be visible before the diversion has
11543 completely been printed (except for input protected with @code{\!} or
11544 @code{\?}) since the data in the diversion is already formatted. In most
11545 cases, this is not the expected behaviour.
11547 @c ---------------------------------------------------------------------
11549 @node Diversion Traps, Input Line Traps, Page Location Traps, Traps
11550 @subsection Diversion Traps
11551 @cindex diversion traps
11552 @cindex traps, diversion
11554 @Defreq {dt, [@Var{dist} @Var{macro}]}
11555 @cindex @code{.t} register, and diversions
11556 @cindex setting diversion trap (@code{dt})
11557 @cindex diversion trap, setting (@code{dt})
11558 @cindex trap, diversion, setting (@code{dt})
11559 Set a trap @emph{within} a diversion.
11560 @var{dist} is the location of the trap
11561 (identical to the @code{wh} request; default scaling indicator is
11562 @samp{v}) and @var{macro} is the name of the macro to be invoked.
11563 If called without arguments, the diversion trap is removed.
11565 Note that there exists only a single diversion trap.
11567 The number register @code{.t} still works within diversions.
11568 @xref{Diversions}, for more information.
11571 @c ---------------------------------------------------------------------
11573 @node Input Line Traps, Blank Line Traps, Diversion Traps, Traps
11574 @subsection Input Line Traps
11575 @cindex input line traps
11576 @cindex traps, input line
11578 @DefreqList {it, n macro}
11579 @DefreqItem {itc, n macro}
11580 @cindex setting input line trap (@code{it})
11581 @cindex input line trap, setting (@code{it})
11582 @cindex trap, input line, setting (@code{it})
11583 Set an input line trap.
11584 @var{n}@tie{}is the number of lines of input which may be read before
11585 springing the trap, @var{macro} is the macro to be invoked.
11586 Request lines are not counted as input lines.
11588 For example, one possible use is to have a macro which prints the
11589 next @var{n}@tie{}lines in a bold font.
11602 @cindex input line traps and interrupted lines (@code{itc})
11603 @cindex interrupted lines and input line traps (@code{itc})
11604 @cindex traps, input line, and interrupted lines (@code{itc})
11605 @cindex lines, interrupted, and input line traps (@code{itc})
11606 The @code{itc} request is identical
11607 except that an interrupted text line (ending with @code{\c})
11608 is not counted as a separate line.
11610 Both requests are associated with the current environment
11611 (@pxref{Environments}); switching to another environment disables the
11612 current input trap, and going back reactivates it, restoring the number
11613 of already processed lines.
11616 @c ---------------------------------------------------------------------
11618 @node Blank Line Traps, End-of-input Traps, Input Line Traps, Traps
11619 @subsection Blank Line Traps
11620 @cindex blank line traps
11621 @cindex traps, blank line
11623 @Defreq {blm, macro}
11624 @cindex blank line macro (@code{blm})
11625 Set a blank line trap.
11626 @code{gtroff} executes @var{macro} when it encounters a blank line in
11630 @c ---------------------------------------------------------------------
11632 @node End-of-input Traps, , Blank Line Traps, Traps
11633 @subsection End-of-input Traps
11634 @cindex end-of-input traps
11635 @cindex traps, end-of-input
11637 @Defreq {em, macro}
11638 @cindex setting end-of-input trap (@code{em})
11639 @cindex end-of-input trap, setting (@code{em})
11640 @cindex trap, end-of-input, setting (@code{em})
11641 @cindex end-of-input macro (@code{em})
11642 @cindex macro, end-of-input (@code{em})
11643 Set a trap at the end of input. @var{macro} is executed after the
11644 last line of the input file has been processed.
11646 For example, if the document had to have a section at the bottom of the
11647 last page for someone to approve it, the @code{em} request could be
11653 . sp |(\\n[.t] - 6v)
11667 @c =====================================================================
11669 @node Diversions, Environments, Traps, gtroff Reference
11670 @section Diversions
11673 In @code{gtroff} it is possible to @dfn{divert} text into a named
11674 storage area. Due to the similarity to defining macros it is sometimes
11675 said to be stored in a macro. This is used for saving text for output
11676 at a later time, which is useful for keeping blocks of text on the same
11677 page, footnotes, tables of contents, and indices.
11679 @cindex top-level diversion
11680 @cindex diversion, top-level
11681 For orthogonality it is said that @code{gtroff} is in the @dfn{top-level
11682 diversion} if no diversion is active (i.e., the data is diverted to the
11685 @DefreqList {di, macro}
11686 @DefreqListEnd {da, macro}
11687 @cindex beginning diversion (@code{di})
11688 @cindex diversion, beginning (@code{di})
11689 @cindex ending diversion (@code{di})
11690 @cindex diversion, ending (@code{di})
11691 @cindex appending to a diversion (@code{da})
11692 @cindex diversion, appending (@code{da})
11693 Begin a diversion. Like the @code{de}
11694 request, it takes an argument of a macro name to divert subsequent text
11695 into. The @code{da} macro appends to an existing diversion.
11697 @code{di} or @code{da} without an argument ends the diversion.
11700 @DefreqList {box, macro}
11701 @DefreqListEnd {boxa, macro}
11702 Begin (or appends to) a diversion like the
11703 @code{di} and @code{da} requests.
11704 The difference is that @code{box} and @code{boxa}
11705 do not include a partially-filled line in the diversion.
11717 @result{} Before the box. After the box.
11719 @result{} In the box.
11726 Before the diversion.
11731 After the diversion.
11733 @result{} After the diversion.
11735 @result{} Before the diversion. In the diversion.
11738 @code{box} or @code{boxa} without an argument ends the diversion.
11742 @DefregListEnd {.d}
11743 @cindex @code{nl} register, and @code{.d}
11744 @cindex nested diversions
11745 @cindex diversion, nested
11746 @cindex diversion name register (@code{.z})
11747 @cindex vertical position in diversion register (@code{.d})
11748 @cindex position, vertical, in diversion, register (@code{.d})
11749 @cindex diversion, vertical position in, register (@code{.d})
11750 Diversions may be nested. The read-only number register @code{.z}
11751 contains the name of the current diversion (this is a string-valued
11752 register). The read-only number register @code{.d} contains the current
11753 vertical place in the diversion. If not in a diversion it is the same
11754 as register @code{nl}.
11758 @cindex high-water mark register (@code{.h})
11759 @cindex mark, high-water, register (@code{.h})
11760 @cindex position of lowest text line (@code{.h})
11761 @cindex text line, position of lowest (@code{.h})
11762 The @dfn{high-water mark} on the current page. It corresponds to the
11763 text baseline of the lowest line on the page. This is a read-only
11767 .tm .h==\n[.h], nl==\n[nl]
11768 @result{} .h==0, nl==-1
11772 .tm .h==\n[.h], nl==\n[nl]
11773 @result{} .h==40, nl==120
11776 @cindex @code{.h} register, difference to @code{nl}
11777 @cindex @code{nl} register, difference to @code{.h}
11779 As can be seen in the previous example, empty lines are not considered
11780 in the return value of the @code{.h} register.
11784 @DefregListEnd {dl}
11785 @cindex @code{dn} register, and @code{da} (@code{boxa})
11786 @cindex @code{dl} register, and @code{da} (@code{boxa})
11787 @cindex @code{da} request, and @code{dn} (@code{dl})
11788 @cindex @code{boxa} request, and @code{dn} (@code{dl})
11789 After completing a diversion, the read-write number registers @code{dn}
11790 and @code{dl} contain the vertical and horizontal size of the diversion.
11791 Note that only the just processed lines are counted: For the computation
11792 of @code{dn} and @code{dl}, the requests @code{da} and @code{boxa} are
11793 handled as if @code{di} and @code{box} had been used -- lines which have
11794 been already stored in a macro are not taken into account.
11797 .\" Center text both horizontally & vertically
11799 .\" Enclose macro definitions in .eo and .ec
11800 .\" to avoid the doubling of the backslash
11802 .\" macro .(c starts centering mode
11813 .\" macro .)c terminates centering mode
11818 . nr @@s (((\n[.t]u - \n[dn]u) / 2u) - 1v)
11830 .\" End of macro definitions, restore escape mechanism
11835 @DefescList {\\!, , , }
11836 @DefescListEnd {\\?, , anything, \\?}
11837 @cindex transparent output (@code{\!}, @code{\?})
11838 @cindex output, transparent (@code{\!}, @code{\?})
11839 Prevent requests, macros, and escapes from being
11840 interpreted when read into a diversion. Both escapes take the given text
11841 and @dfn{transparently} embed it into the diversion. This is useful for
11842 macros which shouldn't be invoked until the diverted text is actually
11845 The @code{\!} escape transparently embeds text up to
11846 and including the end of the line.
11847 The @code{\?} escape transparently embeds text until the next
11848 occurrence of the @code{\?} escape. Example:
11855 @var{anything} may not contain newlines; use @code{\!} to embed
11856 newlines in a diversion. The escape sequence @code{\?} is also
11857 recognized in copy mode and turned into a single internal code; it is
11858 this code that terminates @var{anything}. Thus the following example
11865 \?\\?\\\\?\\\\\\\\nx\\\\?\\?\?
11879 Both escapes read the data in copy mode.
11881 @cindex @code{\!}, in top-level diversion
11882 @cindex top-level diversion, and @code{\!}
11883 @cindex diversion, top-level, and @code{\!}
11884 If @code{\!} is used in the top-level diversion, its argument is
11885 directly embedded into the @code{gtroff} intermediate output. This can
11886 be used for example to control a postprocessor which processes the data
11887 before it is sent to the device driver.
11889 @cindex @code{\?}, in top-level diversion
11890 @cindex top-level diversion, and @code{\?}
11891 @cindex diversion, top-level, and @code{\?}
11892 The @code{\?} escape used in the top-level diversion produces no output
11893 at all; its argument is simply ignored.
11896 @cindex @code{\!}, and @code{output}
11897 @cindex @code{output} request, and @code{\!}
11898 @Defreq {output, string}
11899 Emit @var{string} directly to the @code{gtroff} intermediate output
11900 (subject to copy-mode interpretation); this is similar to @code{\!} used
11901 at the top level. An initial double quote in @var{string} is stripped off
11902 to allow initial blanks.
11904 This request can't be used before the first page has started -- if you get
11905 an error, simply insert @code{.br} before the @code{output} request.
11907 Without argument, @code{output} is ignored.
11909 Use with caution! It is normally only needed for mark-up used by a
11910 postprocessor which does something with the output before sending it to
11911 the output device, filtering out @var{string} again.
11914 @Defreq {asciify, div}
11915 @cindex unformatting diversions (@code{asciify})
11916 @cindex diversion, unformatting (@code{asciify})
11917 @cindex @code{trin} request, and @code{asciify}
11918 @dfn{Unformat} the diversion specified by @var{div}
11919 in such a way that @acronym{ASCII} characters, characters translated with
11920 the @code{trin} request, space characters, and some escape sequences that
11921 were formatted and diverted are treated like ordinary input
11922 characters when the diversion is reread. It can be also used for gross
11923 hacks; for example, the following sets register@tie{}@code{n} to@tie{}1.
11936 @xref{Copy-in Mode}.
11939 @Defreq {unformat, div}
11940 Like @code{asciify}, unformat the specified diversion.
11941 However, @code{unformat} only unformats spaces and tabs
11943 Unformatted tabs are treated as input tokens,
11944 and spaces are stretchable again.
11946 The vertical size of lines is not preserved; glyph information (font,
11947 font size, space width, etc.)@: is retained.
11951 @c =====================================================================
11953 @node Environments, Suppressing output, Diversions, gtroff Reference
11954 @section Environments
11955 @cindex environments
11957 It happens frequently that some text should be printed in a certain
11958 format regardless of what may be in effect at the time, for example, in
11959 a trap invoked macro to print headers and footers. To solve this
11960 @code{gtroff} processes text in @dfn{environments}. An
11961 environment contains most of the parameters that control text
11962 processing. It is possible to switch amongst these environments; by
11963 default @code{gtroff} processes text in environment@tie{}0. The
11964 following is the information kept in an environment.
11968 font parameters (size, family, style, glyph height and slant, space
11969 and sentence space size)
11972 page parameters (line length, title length, vertical spacing,
11973 line spacing, indentation, line numbering, centering, right-justifying,
11974 underlining, hyphenation data)
11977 fill and adjust mode
11980 tab stops, tab and leader characters, escape character,
11981 no-break and hyphen indicators, margin character data
11984 partially collected lines
11990 drawing and fill colours
11993 These environments may be given arbitrary names (see @ref{Identifiers},
11994 for more info). Old versions of @code{troff} only had environments
11995 named @samp{0}, @samp{1}, and @samp{2}.
11997 @DefreqList {ev, [@Var{env}]}
11998 @DefregListEnd {.ev}
11999 @cindex switching environments (@code{ev})
12000 @cindex environment, switching (@code{ev})
12001 @cindex environment number/name register (@code{.ev})
12002 Switch to another environment. The argument @var{env} is the name of
12003 the environment to switch to. With no argument, @code{gtroff} switches
12004 back to the previous environment. There is no limit on the number of
12005 named environments; they are created the first time that they are
12006 referenced. The @code{.ev} read-only register contains the name or
12007 number of the current environment. This is a string-valued register.
12009 Note that a call to @code{ev} (with argument) pushes the previously
12010 active environment onto a stack. If, say, environments @samp{foo},
12011 @samp{bar}, and @samp{zap} are called (in that order), the first
12012 @code{ev} request without parameter switches back to environment
12013 @samp{bar} (which is popped off the stack), and a second call
12014 switches back to environment @samp{foo}.
12016 Here is an example:
12029 \(dg Note the large, friendly letters.
12035 @cindex copying environment (@code{evc})
12036 @cindex environment, copying (@code{evc})
12037 Copy the environment @var{env} into the current environment.
12039 The following environment data is not copied:
12043 Partially filled lines.
12046 The status whether the previous line was interrupted.
12049 The number of lines still to center, or to right-justify, or to underline
12050 (with or without underlined spaces); they are set to zero.
12053 The status whether a temporary indent is active.
12056 Input traps and its associated data.
12059 Line numbering mode is disabled; it can be reactivated with
12063 The number of consecutive hyphenated lines (set to zero).
12070 @DefregListEnd {.csk}
12071 @cindex environment, dimensions of last glyph (@code{.w}, @code{.cht}, @code{.cdp}, @code{.csk})
12072 @cindex width, of last glyph (@code{.w})
12073 @cindex height, of last glyph (@code{.cht})
12074 @cindex depth, of last glyph (@code{.cdp})
12075 @cindex skew, of last glyph (@code{.csk})
12076 @cindex last glyph, dimensions (@code{.w}, @code{.cht}, @code{.cdp}, @code{.csk})
12077 @cindex glyph, last, dimensions (@code{.w}, @code{.cht}, @code{.cdp}, @code{.csk})
12078 The @code{\n[.w]} register contains the
12079 width of the last glyph added to the current environment.
12081 The @code{\n[.cht]} register contains the
12082 height of the last glyph added to the current environment.
12084 The @code{\n[.cdp]} register contains the
12085 depth of the last glyph added to the current environment.
12086 It is positive for glyphs extending below the baseline.
12088 The @code{\n[.csk]} register contains the
12089 @dfn{skew} (how far to the right of the glyph's center
12090 that @code{gtroff} should place an accent)
12091 of the last glyph added to the current environment.
12095 @cindex environment, previous line length (@code{.n})
12096 @cindex line length, previous (@code{.n})
12097 @cindex length of previous line (@code{.n})
12098 @cindex previous line length (@code{.n})
12099 The @code{\n[.n]} register contains the
12100 length of the previous output line in the current environment.
12104 @c =====================================================================
12106 @node Suppressing output, Colors, Environments, gtroff Reference
12107 @section Suppressing output
12109 @Defesc {\\O, , num, }
12110 @cindex suppressing output (@code{\O})
12111 @cindex output, suppressing (@code{\O})
12112 Disable or enable output depending on the value of @var{num}:
12116 Disable any glyphs from being emitted to the device driver, provided that
12117 the escape occurs at the outer level (see @code{\O[3]} and @code{\O[4]}).
12118 Motion is not suppressed so effectively @code{\O[0]} means @emph{pen up}.
12121 Enable output of glyphs, provided that the escape occurs at the outer
12129 @code{\O0} and @code{\O1} also reset the four registers @samp{opminx},
12130 @samp{opminy}, @samp{opmaxx}, and @samp{opmaxy} to @minus{}1.
12131 @xref{Register Index}. These four registers mark the top left and
12132 bottom right hand corners of a box which encompasses all written glyphs.
12134 For example the input text:
12137 Hello \O[0]world \O[1]this is a test.
12141 produces the following output:
12144 Hello this is a test.
12149 Provided that the escape occurs at the outer level, enable output of
12150 glyphs and also write out to @code{stderr} the page number and four
12151 registers encompassing the glyphs previously written since the last call
12155 Begin a nesting level. At start-up, @code{gtroff} is at outer level.
12158 End a nesting level.
12160 @item \O[5@var{P}@var{filename}]
12161 This escape is @code{grohtml} specific. Provided that this escape
12162 occurs at the outer nesting level write the @code{filename} to
12163 @code{stderr}. The position of the image, @var{P}, must be specified
12164 and must be one of @code{l}, @code{r}, @code{c}, or@tie{}@code{i} (left,
12165 right, centered, inline). @var{filename} will be associated with the
12166 production of the next inline image.
12170 @c =====================================================================
12172 @node Colors, I/O, Suppressing output, gtroff Reference
12176 @DefreqList {color, [@Var{n}]}
12177 @DefregListEnd {.color}
12178 If @var{n} is missing or non-zero, activate colors (this is the default);
12179 otherwise, turn it off.
12181 The read-only number register @code{.color} is@tie{}1 if colors are active,
12184 Internally, @code{color} sets a global flag; it does not produce a token.
12185 Similar to the @code{cp} request, you should use it at the beginning of
12186 your document to control color output.
12188 Colors can be also turned off with the @option{-c} command line option.
12191 @Defreq {defcolor, ident scheme color_components}
12192 Define color with name @var{ident}. @var{scheme} can be one of the
12193 following values: @code{rgb} (three components), @code{cmy} (three
12194 components), @code{cmyk} (four components), and @code{gray} or
12195 @code{grey} (one component).
12197 @cindex default color
12198 @cindex color, default
12199 Color components can be given either as a hexadecimal string or as
12200 positive decimal integers in the range 0--65535. A hexadecimal string
12201 contains all color components concatenated. It must start with either
12202 @code{#} or @code{##}; the former specifies hex values in the range
12203 0--255 (which are internally multiplied by@tie{}257), the latter in the
12204 range 0--65535. Examples: @code{#FFC0CB} (pink), @code{##ffff0000ffff}
12205 (magenta). The default color name @c{default} can't be redefined; its
12206 value is device-specific (usually black). It is possible that the
12207 default color for @code{\m} and @code{\M} is not identical.
12209 @cindex @code{f} unit, and colors
12210 @cindex unit, @code{f}, and colors
12211 A new scaling indicator@tie{}@code{f} has been introduced which multiplies
12212 its value by 65536; this makes it convenient to specify color components
12213 as fractions in the range 0 to@tie{}1 (1f equals 65536u). Example:
12216 .defcolor darkgreen rgb 0.1f 0.5f 0.2f
12219 Note that @code{f} is the default scaling indicator for the
12220 @code{defcolor} request, thus the above statement is equivalent to
12223 .defcolor darkgreen rgb 0.1 0.5 0.2
12227 @DefescList {\\m, , c, }
12228 @DefescItem {\\m, @lparen{}, co, }
12229 @DefescItem {\\m, @lbrack{}, color, @rbrack}
12230 @DefregListEnd {.m}
12231 Set drawing color. The following example shows how to turn the next four
12235 \m[red]these are in red\m[] and these words are in black.
12238 The escape @code{\m[]} returns to the previous color.
12240 @cindex drawing color name register (@code{.m})
12241 @cindex name, drawing color, register (@code{.m})
12242 @cindex color name, drawing, register (@code{.m})
12243 The name of the current drawing color is available in the read-only,
12244 string-valued number register @samp{.m}.
12246 The drawing color is associated with the current environment
12247 (@pxref{Environments}).
12249 Note that @code{\m} doesn't produce an input token in @code{gtroff}.
12250 As a consequence, it can be used in requests like @code{mc} (which
12251 expects a single character as an argument) to change the color on
12259 @DefescList {\\M, , c, }
12260 @DefescItem {\\M, @lparen{}, co, }
12261 @DefescItem {\\M, @lbrack{}, color, @rbrack}
12262 @DefregListEnd {.M}
12263 Set background color for filled objects drawn with the
12264 @code{\D'@dots{}'} commands.
12266 A red ellipse can be created with the following code:
12269 \M[red]\h'0.5i'\D'E 2i 1i'\M[]
12272 The escape @code{\M[]} returns to the previous fill color.
12274 @cindex background color name register (@code{.M})
12275 @cindex name, background color, register (@code{.M})
12276 @cindex color name, background, register (@code{.M})
12277 The name of the current background color is available in the read-only,
12278 string-valued number register @samp{.M}.
12280 The fill color is associated with the current environment
12281 (@pxref{Environments}).
12283 Note that @code{\M} doesn't produce an input token in @code{gtroff}.
12287 @c =====================================================================
12289 @node I/O, Postprocessor Access, Colors, gtroff Reference
12292 @cindex input and output requests
12293 @cindex requests for input and output
12294 @cindex output and input requests
12296 @code{gtroff} has several requests for including files:
12299 @cindex including a file (@code{so})
12300 @cindex file, inclusion (@code{so})
12301 Read in the specified @var{file} and
12302 includes it in place of the @code{so} request. This is quite useful for
12303 large documents, e.g.@: keeping each chapter in a separate file.
12304 @xref{gsoelim}, for more information.
12306 Since @code{gtroff} replaces the @code{so} request with the contents
12307 of @code{file}, it makes a difference whether the data is terminated with
12308 a newline or not: Assuming that file @file{xxx} contains the word
12309 @samp{foo} without a final newline, this
12318 yields @samp{This is foobar}.
12320 The search path for @var{file} can be controlled with the @option{-I} command
12324 @Defreq {pso, command}
12325 Read the standard output from the specified @var{command}
12326 and includes it in place of the @code{pso} request.
12329 @cindex mode, safer
12330 @cindex unsafe mode
12331 @cindex mode, unsafe
12332 This request causes an error if used in safer mode (which is the default).
12333 Use @code{groff}'s or @code{troff}'s @option{-U} option to activate unsafe
12336 The comment regarding a final newline for the @code{so} request is valid
12337 for @code{pso} also.
12340 @Defreq {mso, file}
12341 Identical to the @code{so} request except that @code{gtroff} searches for
12342 the specified @var{file} in the same directories as macro files for the
12343 the @option{-m} command line option. If the file name to be included
12344 has the form @file{@var{name}.tmac} and it isn't found, @code{mso} tries
12345 to include @file{tmac.@var{name}} and vice versa.
12348 @DefreqList {trf, file}
12349 @DefreqListEnd {cf, file}
12350 @cindex transparent output (@code{cf}, @code{trf})
12351 @cindex output, transparent (@code{cf}, @code{trf})
12352 Transparently output the contents of @var{file}. Each line is output
12353 as if it were preceded by @code{\!}; however, the lines are not subject
12354 to copy mode interpretation. If the file does not end with a newline,
12355 then a newline is added (@code{trf} only). For example, to define a
12356 macro@tie{}@code{x} containing the contents of file@tie{}@file{f}, use
12364 Both @code{trf} and @code{cf}, when used in a diversion,
12365 embeds an object in the diversion which, when reread, causes the
12366 contents of @var{file} to be transparently copied through to the
12367 output. In @acronym{UNIX} @code{troff}, the contents of @var{file}
12368 is immediately copied through to the output regardless of whether there
12369 is a current diversion; this behaviour is so anomalous that it must be
12372 @cindex @code{trf} request, and invalid characters
12373 @cindex characters, invalid for @code{trf} request
12374 @cindex invalid characters for @code{trf} request
12375 While @code{cf} copies the contents of @var{file} completely unprocessed,
12376 @code{trf} disallows characters such as NUL that are not valid
12377 @code{gtroff} input characters (@pxref{Identifiers}).
12379 Both requests cause a line break.
12382 @Defreq {nx, [@Var{file}]}
12383 @cindex processing next file (@code{nx})
12384 @cindex file, processing next (@code{nx})
12385 @cindex next file, processing (@code{nx})
12386 Force @code{gtroff} to continue processing of
12387 the file specified as an argument. If no argument is given, immediately
12388 jump to the end of file.
12391 @Defreq {rd, [@Var{prompt} [@Var{arg1} @Var{arg2} @dots{}]]}
12392 @cindex reading from standard input (@code{rd})
12393 @cindex standard input, reading from (@code{rd})
12394 @cindex input, standard, reading from (@code{rd})
12395 Read from standard input, and include what is read as though it
12396 were part of the input file. Text is read until a blank line
12399 If standard input is a TTY input device (keyboard), write @var{prompt}
12400 to standard error, followed by a colon (or send BEL for a beep if no
12401 argument is given).
12403 Arguments after @var{prompt} are available for the input. For example,
12410 with the input @w{@samp{This is \$2.}} prints
12417 @cindex form letters
12418 @cindex letters, form
12419 Using the @code{nx} and @code{rd} requests,
12420 it is easy to set up form letters. The form
12421 letter template is constructed like this, putting the following lines
12422 into a file called @file{repeat.let}:
12438 @cindex @code{ex} request, used with @code{nx} and @code{rd}
12440 When this is run, a file containing the following lines should be
12441 redirected in. Note that requests included in this file are executed
12442 as though they were part of the form letter. The last block of input
12443 is the @code{ex} request which tells @code{groff} to stop processing. If
12444 this was not there, @code{groff} would not know when to stop.
12448 708 NW 19th Av., #202
12455 San Diego, CA 92103
12463 Pipe the output of @code{gtroff} to the shell command(s)
12464 specified by @var{pipe}. This request must occur before
12465 @code{gtroff} has a chance to print anything.
12468 @cindex mode, safer
12469 @cindex unsafe mode
12470 @cindex mode, unsafe
12471 @code{pi} causes an error if used in safer mode (which is the default).
12472 Use @code{groff}'s or @code{troff}'s @option{-U} option to activate unsafe
12475 Multiple calls to @code{pi} are allowed, acting as a chain. For example,
12483 is the same as @w{@samp{.pi foo | bar}}.
12485 @cindex @code{groff}, and @code{pi} request
12486 @cindex @code{pi} request, and @code{groff}
12487 Note that the intermediate output format of @code{gtroff} is piped to
12488 the specified commands. Consequently, calling @code{groff} without the
12489 @option{-Z} option normally causes a fatal error.
12492 @DefreqList {sy, cmds}
12493 @DefregListEnd {systat}
12494 Execute the shell command(s) specified by @var{cmds}. The output is not
12495 saved anyplace, so it is up to the user to do so.
12498 @cindex mode, safer
12499 @cindex unsafe mode
12500 @cindex mode, unsafe
12501 This request causes an error if used in safer mode (which is the default).
12502 Use @code{groff}'s or @code{troff}'s @option{-U} option to activate unsafe
12505 For example, the following code fragment introduces the current time into a
12508 @cindex time, current
12509 @cindex current time
12512 .sy perl -e 'printf ".nr H %d\\n.nr M %d\\n.nr S %d\\n",\
12513 (localtime(time))[2,1,0]' > /tmp/x\n[$$]
12515 .sy rm /tmp/x\n[$$]
12520 Note that this works by having the @code{perl} script (run by @code{sy})
12521 print out the @code{nr} requests which set the number registers
12522 @code{H}, @code{M}, and @code{S}, and then reads those commands in with
12523 the @code{so} request.
12525 For most practical purposes, the number registers @code{seconds},
12526 @code{minutes}, and @code{hours} which are initialized at start-up of
12527 @code{gtroff} should be sufficient. Use the @code{af} request to get a
12534 \n[hours]:\n[minutes]:\n[seconds]
12537 @cindex @code{system()} return value register (@code{systat})
12538 The @code{systat} read-write number register contains the return value
12539 of the @code{system()} function executed by the last @code{sy} request.
12542 @DefreqList {open, stream file}
12543 @DefreqListEnd {opena, stream file}
12544 @cindex opening file (@code{open})
12545 @cindex file, opening (@code{open})
12546 @cindex appending to a file (@code{opena})
12547 @cindex file, appending to (@code{opena})
12548 Open the specified @var{file} for writing and
12549 associates the specified @var{stream} with it.
12551 The @code{opena} request is like @code{open}, but if the file exists,
12552 append to it instead of truncating it.
12555 @cindex mode, safer
12556 @cindex unsafe mode
12557 @cindex mode, unsafe
12558 Both @code{open} and @code{opena} cause an error if used in safer mode
12559 (which is the default). Use @code{groff}'s or @code{troff}'s @option{-U}
12560 option to activate unsafe mode.
12563 @DefreqList {write, stream data}
12564 @DefreqListEnd {writec, stream data}
12565 @cindex copy-in mode, and @code{write} requests
12566 @cindex mode, copy-in, and @code{write} requests
12567 @cindex writing to file (@code{write})
12568 @cindex file, writing to (@code{write})
12569 Write to the file associated with the specified @var{stream}.
12570 The stream must previously have
12571 been the subject of an open request. The remainder of the line is
12572 interpreted as the @code{ds} request reads its second argument: A
12573 leading @samp{"} is stripped, and it is read in copy-in mode.
12575 The @code{writec} request is like @code{write}, but only
12576 @code{write} appends a newline to the data.
12579 @Defreq {writem, stream xx}
12580 @cindex @code{asciify} request, and @code{writem}
12581 Write the contents of the macro or string @var{xx}
12582 to the file associated with the specified @var{stream}.
12584 @var{xx} is read in copy mode, i.e., already formatted elements are
12585 ignored. Consequently, diversions must be unformatted with the
12586 @code{asciify} request before calling @code{writem}. Usually, this
12587 means a loss of information.
12590 @Defreq {close, stream}
12591 @cindex closing file (@code{close})
12592 @cindex file, closing (@code{close})
12593 Close the specified @var{stream};
12594 the stream is no longer an acceptable argument to the
12595 @code{write} request.
12597 Here a simple macro to write an index entry.
12603 . write idx \\n[%] \\$*
12612 @DefescList {\\V, , e, }
12613 @DefescItem {\\V, @lparen{}, ev, }
12614 @DefescListEnd {\\V, @lbrack{}, env, @rbrack}
12615 Interpolate the contents of the specified environment variable
12616 @var{env} (one-character name@tie{}@var{e}, two-character name @var{ev})
12617 as returned by the function @code{getenv}. @code{\V} is interpreted
12622 @c =====================================================================
12624 @node Postprocessor Access, Miscellaneous, I/O, gtroff Reference
12625 @section Postprocessor Access
12626 @cindex postprocessor access
12627 @cindex access of postprocessor
12629 There are two escapes which give information directly to the
12630 postprocessor. This is particularly useful for embedding
12631 @sc{PostScript} into the final document.
12633 @Defesc {\\X, ', xxx, '}
12634 Embeds its argument into the @code{gtroff}
12635 output preceded with @w{@samp{x X}}.
12637 @cindex @code{\&}, in @code{\X}
12638 @cindex @code{\)}, in @code{\X}
12639 @cindex @code{\%}, in @code{\X}
12641 @cindex @code{\:}, in @code{\X}
12644 @cindex @code{\@r{<colon>}}, in @code{\X}
12646 The escapes @code{\&}, @code{\)}, @code{\%}, and @code{\:} are ignored
12647 within @code{\X}, @w{@samp{\ }} and @code{\~} are converted to single
12648 space characters. All other escapes (except @code{\\} which produces a
12649 backslash) cause an error.
12651 @kindex use_charnames_in_special
12652 @pindex DESC@r{, and @code{use_charnames_in_special}}
12653 @cindex @code{\X}, and special characters
12654 If the @samp{use_charnames_in_special} keyword is set in the @file{DESC}
12655 file, special characters no longer cause an error; the name @var{xx} is
12656 represented as @samp{\(@var{xx})} in the @w{@samp{x X}} output command.
12657 Additionally, the backslash is represented as @code{\\}.
12659 @samp{use_charnames_in_special} is currently used by @code{grohtml} only.
12662 @DefescList {\\Y, , n, }
12663 @DefescItem {\\Y, @lparen{}, nm, }
12664 @DefescListEnd {\\Y, @lbrack{}, name, @rbrack}
12665 This is approximately equivalent to @samp{\X'\*[@var{name}]'}
12666 (one-character name@tie{}@var{n}, two-character name @var{nm}).
12667 However, the contents of the string or macro @var{name} are not
12668 interpreted; also it is permitted for @var{name} to have been defined
12669 as a macro and thus contain newlines (it is not permitted for the
12670 argument to @code{\X} to contain newlines). The inclusion of
12671 newlines requires an extension to the @acronym{UNIX} @code{troff}
12672 output format, and confuses drivers that do not know about this
12673 extension (@pxref{Device Control Commands}).
12676 @xref{Output Devices}.
12679 @c =====================================================================
12681 @node Miscellaneous, Gtroff Internals, Postprocessor Access, gtroff Reference
12682 @section Miscellaneous
12684 This section documents parts of @code{gtroff} which cannot (yet) be
12685 categorized elsewhere in this manual.
12687 @Defreq {nm, [@Var{start} [@Var{inc} [@Var{space} [@Var{indent}]]]]}
12688 @cindex printing line numbers (@code{nm})
12689 @cindex line numbers, printing (@code{nm})
12690 @cindex numbers, line, printing (@code{nm})
12691 Print line numbers.
12692 @var{start} is the line number of the @emph{next}
12693 output line. @var{inc} indicates which line numbers are printed.
12694 For example, the value@tie{}5 means to emit only line numbers which
12695 are multiples of@tie{}5; this defaults to@tie{}1. @var{space} is the
12696 space to be left between the number and the text; this defaults to
12697 one digit space. The fourth argument is the indentation of the line
12698 numbers, defaulting to zero. Both @var{space} and @var{indent} are
12699 given as multiples of digit spaces; they can be negative also.
12700 Without any arguments, line numbers are turned off.
12702 @code{gtroff} reserves three digit spaces for the line number (which is
12703 printed right-justified) plus the amount given by @var{indent}; the
12704 output lines are concatenated to the line numbers, separated by
12705 @var{space}, and @emph{without} reducing the line length. Depending
12706 on the value of the horizontal page offset (as set with the
12707 @code{po} request), line numbers which are longer than the reserved
12708 space stick out to the left, or the whole line is moved to the right.
12710 Parameters corresponding to missing arguments are not changed; any
12711 non-digit argument (to be more precise, any argument starting with a
12712 character valid as a delimiter for identifiers) is also treated as
12715 If line numbering has been disabled with a call to @code{nm} without
12716 an argument, it can be reactivated with @samp{.nm +0}, using the
12717 previously active line numbering parameters.
12719 The parameters of @code{nm} are associated with the current environment
12720 (@pxref{Environments}). The current output line number is available
12721 in the number register @code{ln}.
12726 This test shows how line numbering works with groff.
12728 This test shows how line numbering works with groff.
12732 This test shows how line numbering works with groff.
12734 This test shows how line numbering works with groff.
12738 And here the result:
12741 This test shows how
12742 line numbering works
12743 999 with groff. This
12744 1000 test shows how line
12745 1001 numbering works with
12747 This test shows how
12750 This test shows how
12751 1005 line numbering
12756 @Defreq {nn, [@Var{skip}]}
12757 Temporarily turn off line numbering. The argument is the number
12758 of lines not to be numbered; this defaults to@tie{}1.
12761 @Defreq {mc, glyph [@Var{dist}]}
12762 @cindex margin glyph (@code{mc})
12763 @cindex glyph, for margins (@code{mc})
12764 Print a @dfn{margin character} to the right of the
12765 text.@footnote{@dfn{Margin character} is a misnomer since it is an
12766 output glyph.} The first argument is the glyph to be
12767 printed. The second argument is the distance away from the right
12768 margin. If missing, the previously set value is used; default is
12769 10@dmn{pt}). For text lines that are too long (that is, longer than
12770 the text length plus @var{dist}), the margin character is directly
12771 appended to the lines.
12773 With no arguments the margin character is turned off.
12774 If this occurs before a break, no margin character is printed.
12776 For compatibility with @acronym{AT&T} @code{troff}, a call to @code{mc}
12777 to set the margin character can't be undone immediately; at least one
12778 line gets a margin character. Thus
12797 @cindex @code{tl} request, and @code{mc}
12798 For empty lines and lines produced by the @code{tl} request no margin
12799 character is emitted.
12801 The margin character is associated with the current environment
12802 (@pxref{Environments}).
12806 This is quite useful for indicating text that has changed, and, in fact,
12807 there are programs available for doing this (they are called
12808 @code{nrchbar} and @code{changebar} and can be found in any
12809 @samp{comp.sources.unix} archive).
12814 This paragraph is highlighted with a margin
12817 Note that vertical space isn't marked.
12821 But we can fake it with `\&'.
12827 This paragraph is highlighted |
12828 with a margin character. |
12830 Note that vertical space isn't |
12833 But we can fake it with `\&'. |
12837 @DefreqList {psbb, filename}
12841 @DefregListEnd {ury}
12842 @cindex PostScript, bounding box
12843 @cindex bounding box
12844 Retrieve the bounding box of the PostScript image
12845 found in @var{filename}.
12846 The file must conform to
12847 Adobe's @dfn{Document Structuring Conventions} (DSC);
12848 the command searches for a @code{%%BoundingBox} comment
12849 and extracts the bounding box values into the number registers
12850 @code{llx}, @code{lly}, @code{urx}, and @code{ury}.
12851 If an error occurs (for example, @code{psbb} cannot find
12852 the @code{%%BoundingBox} comment),
12853 it sets the four number registers to zero.
12855 The search path for @var{filename} can be controlled with the @option{-I}
12856 command line option.
12860 @c =====================================================================
12862 @node Gtroff Internals, Debugging, Miscellaneous, gtroff Reference
12863 @section @code{gtroff} Internals
12865 @cindex input token
12866 @cindex token, input
12867 @cindex output node
12868 @cindex node, output
12869 @code{gtroff} processes input in three steps. One or more input
12870 characters are converted to an @dfn{input token}.@footnote{Except the
12871 escapes @code{\f}, @code{\F}, @code{\H}, @code{\m}, @code{\M}, @code{\R},
12872 @code{\s}, and @code{\S} which are processed immediately if not in
12873 copy-in mode.} Then, one or more input tokens are converted to an
12874 @dfn{output node}. Finally, output nodes are converted to the
12875 intermediate output language understood by all output devices.
12877 Actually, before step one happens, @code{gtroff} converts certain
12878 escape sequences into reserved input characters (not accessible by
12879 the user); such reserved characters are used for other internal
12880 processing also -- this is the very reason why not all characters
12881 are valid input. @xref{Identifiers}, for more on this topic.
12883 For example, the input string @samp{fi\[:u]} is converted into a
12884 character token @samp{f}, a character token @samp{i}, and a special
12885 token @samp{:u} (representing u@tie{}umlaut). Later on, the character
12886 tokens @samp{f} and @samp{i} are merged to a single output node
12887 representing the ligature glyph @samp{fi} (provided the current font
12888 has a glyph for this ligature); the same happens with @samp{:u}. All
12889 output glyph nodes are `processed' which means that they are invariably
12890 associated with a given font, font size, advance width, etc. During
12891 the formatting process, @code{gtroff} itself adds various nodes to
12892 control the data flow.
12894 Macros, diversions, and strings collect elements in two chained lists:
12895 a list of input tokens which have been passed unprocessed, and a list
12896 of output nodes. Consider the following the diversion.
12908 It contains these elements.
12910 @multitable {@i{vertical size node}} {token list} {element number}
12911 @item node list @tab token list @tab element number
12913 @item @i{line start node} @tab --- @tab 1
12914 @item @i{glyph node @code{a}} @tab --- @tab 2
12915 @item @i{word space node} @tab --- @tab 3
12916 @item --- @tab @code{b} @tab 4
12917 @item --- @tab @code{\n} @tab 5
12918 @item @i{glyph node @code{c}} @tab --- @tab 6
12919 @item @i{vertical size node} @tab --- @tab 7
12920 @item @i{vertical size node} @tab --- @tab 8
12921 @item --- @tab @code{\n} @tab 9
12924 @cindex @code{\v}, internal representation
12926 Elements 1, 7, and@tie{}8 are inserted by @code{gtroff}; the latter two
12927 (which are always present) specify the vertical extent of the last
12928 line, possibly modified by @code{\x}. The @code{br} request finishes
12929 the current partial line, inserting a newline input token which is
12930 subsequently converted to a space when the diversion is reread. Note
12931 that the word space node has a fixed width which isn't stretchable
12932 anymore. To convert horizontal space nodes back to input tokens, use
12933 the @code{unformat} request.
12935 Macros only contain elements in the token list (and the node list is
12936 empty); diversions and strings can contain elements in both lists.
12938 Note that the @code{chop} request simply reduces the number of elements in a
12939 macro, string, or diversion by one. Exceptions are @dfn{compatibility save}
12940 and @dfn{compatibility ignore} input tokens which are ignored. The
12941 @code{substring} request also ignores those input tokens.
12943 Some requests like @code{tr} or @code{cflags} work on glyph
12944 identifiers only; this means that the associated glyph can be changed
12945 without destroying this association. This can be very helpful for
12946 substituting glyphs. In the following example, we assume that
12947 glyph @samp{foo} isn't available by default, so we provide a
12948 substitution using the @code{fchar} request and map it to input
12949 character @samp{x}.
12957 Now let us assume that we install an additional special font
12958 @samp{bar} which has glyph @samp{foo}.
12966 Since glyphs defined with @code{fchar} are searched before glyphs
12967 in special fonts, we must call @code{rchar} to remove the definition
12968 of the fallback glyph. Anyway, the translation is still active;
12969 @samp{x} now maps to the real glyph @samp{foo}.
12972 @c =====================================================================
12974 @node Debugging, Implementation Differences, Gtroff Internals, gtroff Reference
12978 @code{gtroff} is not easy to debug, but there are some useful features
12979 and strategies for debugging.
12981 @Defreq {lf, line [@Var{filename}]}
12983 @cindex multi-file documents
12984 @cindex documents, multi-file
12985 @cindex setting input line number (@code{lf})
12986 @cindex input line number, setting (@code{lf})
12987 @cindex number, input line, setting (@code{lf})
12988 Change the line number and optionally the file name @code{gtroff} shall
12989 use for error and warning messages. @var{line} is the input line number
12990 of the @emph{next} line.
12992 Without argument, the request is ignored.
12994 This is a debugging aid for documents which are split into many files,
12995 then put together with @code{soelim} and other preprocessors. Usually,
12996 it isn't invoked manually.
12998 Note that other @code{troff} implementations (including the original
12999 @acronym{AT&T} version) handle @code{lf} differently. For them,
13000 @var{line} changes the line number of the @emph{current} line.
13003 @DefreqList {tm, string}
13004 @DefreqItem {tm1, string}
13005 @DefreqListEnd {tmc, string}
13006 @cindex printing to stderr (@code{tm}, @code{tm1}, @code{tmc})
13007 @cindex stderr, printing to (@code{tm}, @code{tm1}, @code{tmc})
13008 Send @var{string} to the standard error output;
13009 this is very useful for printing debugging messages among other things.
13011 @var{string} is read in copy mode.
13013 The @code{tm} request ignores leading spaces of @var{string}; @code{tm1}
13014 handles its argument similar to the @code{ds} request: a leading double
13015 quote in @var{string} is stripped to allow initial blanks.
13017 The @code{tmc} request is similar to @code{tm1} but does
13018 not append a newline (as is done in @code{tm} and @code{tm1}).
13021 @Defreq {ab, [@Var{string}]}
13022 @cindex aborting (@code{ab})
13023 Similar to the @code{tm} request, except that
13024 it causes @code{gtroff} to stop processing. With no argument it
13025 prints @samp{User Abort.} to standard error.
13029 @cindex @code{ex} request, use in debugging
13030 @cindex exiting (@code{ex})
13031 The @code{ex} request also causes @code{gtroff} to stop processing;
13032 see also @ref{I/O}.
13035 When doing something involved it is useful to leave the debugging
13036 statements in the code and have them turned on by a command line flag.
13039 .if \n(DB .tm debugging output
13043 To activate these statements say
13049 If it is known in advance that there will be many errors and no useful
13050 output, @code{gtroff} can be forced to suppress formatted output with
13051 the @option{-z} flag.
13054 @cindex dumping symbol table (@code{pm})
13055 @cindex symbol table, dumping (@code{pm})
13056 Print the entire symbol table on @code{stderr}. Names of all defined
13057 macros, strings, and diversions are print together with their size in
13058 bytes. Since @code{gtroff} sometimes adds nodes by itself, the
13059 returned size can be larger than expected.
13061 This request differs from @acronym{UNIX} @code{troff}: @code{gtroff}
13062 reports the sizes of diversions, ignores an additional argument to
13063 print only the total of the sizes, and the size isn't returned in
13064 blocks of 128 characters.
13068 @cindex dumping number registers (@code{pnr})
13069 @cindex number registers, dumping (@code{pnr})
13070 Print the names and contents of all
13071 currently defined number registers on @code{stderr}.
13075 @cindex dumping traps (@code{ptr})
13076 @cindex traps, dumping (@code{ptr})
13077 Print the names and positions of all traps
13078 (not including input line traps and diversion traps) on @code{stderr}.
13079 Empty slots in the page trap list are printed as well, because they can
13080 affect the priority of subsequently planted traps.
13084 @cindex flush output (@code{fl})
13085 @cindex output, flush (@code{fl})
13086 @cindex interactive use of @code{gtroff}
13087 @cindex @code{gtroff}, interactive use
13088 Instruct @code{gtroff} to flush its output immediately. The intent
13089 is for interactive use, but this behaviour is currently not
13090 implemented in @code{gtroff}. Contrary to @acronym{UNIX} @code{troff},
13091 TTY output is sent to a device driver also (@code{grotty}), making it
13092 non-trivial to communicate interactively.
13094 This request causes a line break.
13097 @Defreq {backtrace, }
13098 @cindex backtrace of input stack (@code{backtrace})
13099 @cindex input stack, backtrace (@code{backtrace})
13100 Print a backtrace of the input stack to the standard error stream.
13102 Consider the following in file @file{test}:
13116 On execution, @code{gtroff} prints the following:
13119 test:2: backtrace: macro `xxx'
13120 test:5: backtrace: macro `yyy'
13121 test:8: backtrace: file `test'
13124 The option @option{-b} of @code{gtroff} internally calls a variant of
13125 this request on each error and warning.
13129 @cindex input stack, setting limit
13130 Use the @code{slimit} number register
13131 to set the maximum number of objects on the input stack.
13132 If @code{slimit} is less than or equal to@tie{}0,
13133 there is no limit set.
13134 With no limit, a buggy recursive macro can exhaust virtual memory.
13136 The default value is 1000; this is a compile-time constant.
13139 @Defreq {warnscale, si}
13140 Set the scaling indicator used in warnings to @var{si}. Valid values for
13141 @var{si} are @samp{u}, @samp{i}, @samp{c}, @samp{p}, and @samp{P}. At
13142 startup, it is set to @samp{i}.
13145 @Defreq {spreadwarn, [@Var{limit}]}
13146 Make @code{gtroff} emit a warning if the additional space inserted for
13147 each space between words in an output line is larger or equal to
13148 @var{limit}. A negative value is changed to zero; no argument toggles the
13149 warning on and off without changing @var{limit}. The default scaling
13150 indicator is @samp{m}. At startup, @code{spreadwarn} is deactivated, and
13151 @var{limit} is set to 3@dmn{m}.
13160 will cause a warning if @code{gtroff} must add 0.2@dmn{m} or more for each
13161 interword space in a line.
13163 This request is active only if text is justified to both margins (using
13168 @code{gtroff} has command line options for printing out more warnings
13169 (@option{-w}) and for printing backtraces (@option{-b}) when a warning
13170 or an error occurs. The most verbose level of warnings is @option{-ww}.
13172 @DefreqList {warn, [@Var{flags}]}
13173 @DefregListEnd {.warn}
13174 @cindex level of warnings (@code{warn})
13175 @cindex warnings, level (@code{warn})
13176 Control the level of warnings checked for. The @var{flags} are the sum
13177 of the numbers associated with each warning that is to be enabled; all
13178 other warnings are disabled. The number associated with each warning is
13179 listed below. For example, @w{@code{.warn 0}} disables all warnings,
13180 and @w{@code{.warn 1}} disables all warnings except that about missing
13181 glyphs. If no argument is given, all warnings are enabled.
13183 The read-only number register @code{.warn} contains the current warning
13191 @c ---------------------------------------------------------------------
13193 @node Warnings, , Debugging, Debugging
13194 @subsection Warnings
13197 The warnings that can be given to @code{gtroff} are divided into the
13198 following categories. The name associated with each warning is used by
13199 the @option{-w} and @option{-W} options; the number is used by the
13200 @code{warn} request and by the @code{.warn} register.
13205 Non-existent glyphs.@footnote{@code{char} is a misnomer since it reports
13206 missing glyphs -- there aren't missing input characters, only invalid
13207 ones.} This is enabled by default.
13211 Invalid numeric expressions. This is enabled by default.
13212 @xref{Expressions}.
13218 In fill mode, lines which could not be broken so that their length was
13219 less than the line length. This is enabled by default.
13223 Missing or mismatched closing delimiters.
13227 @cindex @code{ie} request, and warnings
13228 @cindex @code{el} request, and warnings
13229 Use of the @code{el} request with no matching @code{ie} request.
13234 Meaningless scaling indicators.
13238 Out of range arguments.
13242 Dubious syntax in numeric expressions.
13246 @cindex @code{di} request, and warnings
13247 @cindex @code{da} request, and warnings
13248 Use of @code{di} or @code{da} without an argument when there is no
13253 @cindex @code{de}, @code{de1}, @code{dei} requests, and warnings
13254 @cindex @code{am}, @code{am1}, @code{ami} requests, and warnings
13255 @cindex @code{ds}, @code{ds1} requests, and warnings
13256 @cindex @code{as}, @code{as1} requests, and warnings
13257 @cindex @code{di} request, and warnings
13258 @cindex @code{da} request, and warnings
13259 @cindex @code{box}, @code{boxa} requests, and warnings
13260 @cindex @code{\*}, and warnings
13261 Use of undefined strings, macros and diversions. When an undefined
13262 string, macro, or diversion is used, that string is automatically
13263 defined as empty. So, in most cases, at most one warning is given
13268 @cindex @code{nr} request, and warnings
13269 @cindex @code{\R}, and warnings
13270 @cindex @code{\n}, and warnings
13271 Use of undefined number registers. When an undefined number register is
13272 used, that register is automatically defined to have a value of@tie{}0.
13273 So, in most cases, at most one warning is given for use of a particular
13278 @cindex @code{\t}, and warnings
13279 Use of a tab character where a number was expected.
13283 @cindex @code{\@}}, and warnings
13284 Use of @code{\@}} where a number was expected.
13288 Requests that are missing non-optional arguments.
13292 Invalid input characters.
13296 Unrecognized escape sequences. When an unrecognized escape sequence
13297 @code{\@var{X}} is encountered, the escape character is ignored, and
13298 @var{X} is printed.
13302 @cindex compatibility mode
13303 Missing space between a request or macro and its argument. This warning
13304 is given when an undefined name longer than two characters is
13305 encountered, and the first two characters of the name make a defined
13306 name. The request or macro is not invoked. When this warning is
13307 given, no macro is automatically defined. This is enabled by default.
13308 This warning never occurs in compatibility mode.
13312 Non-existent fonts. This is enabled by default.
13316 Invalid escapes in text ignored with the @code{ig} request. These are
13317 conditions that are errors when they do not occur in ignored text.
13321 Color related warnings.
13324 All warnings except @samp{di}, @samp{mac} and @samp{reg}. It is
13325 intended that this covers all warnings that are useful with traditional
13333 @c =====================================================================
13335 @node Implementation Differences, , Debugging, gtroff Reference
13336 @section Implementation Differences
13337 @cindex implementation differences
13338 @cindex differences in implementation
13339 @cindex incompatibilities with @acronym{AT&T} @code{troff}
13340 @cindex compatibility mode
13341 @cindex mode, compatibility
13343 GNU @code{troff} has a number of features which cause incompatibilities
13344 with documents written with old versions of @code{troff}.
13347 @cindex names, long
13348 Long names cause some incompatibilities. @acronym{UNIX} @code{troff}
13355 @cindex @code{\*}, incompatibilities with @acronym{AT&T} @code{troff}
13356 @cindex @code{\n}, incompatibilities with @acronym{AT&T} @code{troff}
13358 as defining a string @samp{ab} with contents @samp{cd}. Normally, GNU
13359 @code{troff} interprets this as a call of a macro named
13360 @code{dsabcd}. Also @acronym{UNIX} @code{troff} interprets
13361 @code{\*[} or @code{\n[} as references to a string or number register
13362 called @samp{[}. In GNU @code{troff}, however, this is normally
13363 interpreted as the start of a long name. In compatibility mode GNU
13364 @code{troff} interprets long names in the traditional way
13365 (which means that they are not recognized as names).
13367 @DefreqList {cp, [@Var{n}]}
13368 @DefreqItem {do, cmd}
13369 @DefregListEnd {.C}
13370 If @var{n} is missing or non-zero, turn on compatibility mode;
13371 otherwise, turn it off.
13373 The read-only number register @code{.C} is@tie{}1 if compatibility mode is
13374 on, 0@tie{}otherwise.
13376 Compatibility mode can be also turned on with the @option{-C} command line
13379 The @code{do} request turns off compatibility mode
13380 while executing its arguments as a @code{gtroff} command.
13387 executes the @code{fam} request when compatibility mode
13390 @code{gtroff} restores the previous compatibility setting
13391 before interpreting any files sourced by the @var{cmd}.
13394 @cindex input level in delimited arguments
13395 @cindex delimited arguments, incompatibilities with @acronym{AT&T} @code{troff}
13396 Two other features are controlled by @option{-C}. If not in
13397 compatibility mode, GNU @code{troff} preserves the input level in
13398 delimited arguments:
13406 In compatibility mode, the string @samp{72def'} is returned; without
13407 @option{-C} the resulting string is @samp{168} (assuming a TTY output
13410 @cindex @code{\f}, incompatibilities with @acronym{AT&T} @code{troff}
13411 @cindex @code{\H}, incompatibilities with @acronym{AT&T} @code{troff}
13412 @cindex @code{\s}, incompatibilities with @acronym{AT&T} @code{troff}
13413 @cindex @code{\S}, incompatibilities with @acronym{AT&T} @code{troff}
13414 Finally, the escapes @code{\f}, @code{\H}, @code{\m}, @code{\M},
13415 @code{\R}, @code{\s}, and @code{\S} are transparent for recognizing the
13416 beginning of a line only in compatibility mode (this is a rather obscure
13417 feature). For example, the code
13427 prints @samp{Hallo!} in bold face if in compatibility mode, and
13428 @samp{.xx} in bold face otherwise.
13430 @cindex @code{\A}, incompatibilities with @acronym{AT&T} @code{troff}
13431 @cindex @code{\|}, incompatibilities with @acronym{AT&T} @code{troff}
13432 @cindex @code{\^}, incompatibilities with @acronym{AT&T} @code{troff}
13433 @cindex @code{\&}, incompatibilities with @acronym{AT&T} @code{troff}
13434 @cindex @code{\@{}, incompatibilities with @acronym{AT&T} @code{troff}
13435 @cindex @code{\@}}, incompatibilities with @acronym{AT&T} @code{troff}
13436 @cindex @code{\@key{SP}}, incompatibilities with @acronym{AT&T} @code{troff}
13437 @cindex @code{\'}, incompatibilities with @acronym{AT&T} @code{troff}
13438 @cindex @code{\`}, incompatibilities with @acronym{AT&T} @code{troff}
13439 @cindex @code{\-}, incompatibilities with @acronym{AT&T} @code{troff}
13440 @cindex @code{\_}, incompatibilities with @acronym{AT&T} @code{troff}
13441 @cindex @code{\!}, incompatibilities with @acronym{AT&T} @code{troff}
13442 @cindex @code{\%}, incompatibilities with @acronym{AT&T} @code{troff}
13443 @cindex @code{\c}, incompatibilities with @acronym{AT&T} @code{troff}
13444 GNU @code{troff} does not allow the use of the escape sequences
13445 @code{\|}, @code{\^}, @code{\&}, @code{\@{}, @code{\@}},
13446 @code{\@key{SP}}, @code{\'}, @code{\`}, @code{\-}, @code{\_}, @code{\!},
13447 @code{\%}, and @code{\c} in names of strings, macros, diversions, number
13448 registers, fonts or environments; @acronym{UNIX} @code{troff} does. The
13449 @code{\A} escape sequence (@pxref{Identifiers}) may be helpful in
13450 avoiding use of these escape sequences in names.
13452 @cindex fractional point sizes
13453 @cindex fractional type sizes
13454 @cindex point sizes, fractional
13455 @cindex type sizes, fractional
13456 @cindex sizes, fractional
13457 @cindex @code{ps} request, incompatibilities with @acronym{AT&T} @code{troff}
13458 Fractional point sizes cause one noteworthy incompatibility. In
13459 @acronym{UNIX} @code{troff} the @code{ps} request ignores scale
13460 indicators and thus
13467 sets the point size to 10@tie{}points, whereas in GNU @code{troff} it
13468 sets the point size to 10@tie{}scaled points. @xref{Fractional Type
13469 Sizes}, for more information.
13471 @cindex @code{bd} request, incompatibilities with @acronym{AT&T} @code{troff}
13472 @cindex @code{cs} request, incompatibilities with @acronym{AT&T} @code{troff}
13473 @cindex @code{tr} request, incompatibilities with @acronym{AT&T} @code{troff}
13474 @cindex @code{fp} request, incompatibilities with @acronym{AT&T} @code{troff}
13475 @cindex input characters and output glyphs, compatibility with @acronym{AT&T} @code{troff}
13476 @cindex output glyphs, and input characters,compatibility with @acronym{AT&T} @code{troff}
13477 @cindex characters, input, and output glyphs, compatibility with @acronym{AT&T} @code{troff}
13478 @cindex glyphs, output, and input characters, compatibility with @acronym{AT&T} @code{troff}
13479 In GNU @code{troff} there is a fundamental difference between
13480 (unformatted) input characters and (formatted) output glyphs.
13481 Everything that affects how a glyph is output is stored
13482 with the glyph node; once a glyph node has been constructed it is
13483 unaffected by any subsequent requests that are executed, including
13484 @code{bd}, @code{cs}, @code{tkf}, @code{tr}, or @code{fp} requests.
13485 Normally glyphs are constructed from input characters at the
13486 moment immediately before the glyph is added to the current output
13487 line. Macros, diversions and strings are all, in fact, the same type of
13488 object; they contain lists of input characters and glyph nodes in
13489 any combination. A glyph node does not behave like an input
13490 character for the purposes of macro processing; it does not inherit any
13491 of the special properties that the input character from which it was
13492 constructed might have had. For example,
13502 @cindex printing backslash (@code{\\}, @code{\e}, @code{\E}, @code{\[rs]})
13503 @cindex backslash, printing (@code{\\}, @code{\e}, @code{\E}, @code{\[rs]})
13504 @cindex @code{\e}, incompatibilities with @acronym{AT&T} @code{troff}
13505 @cindex @code{\!}, incompatibilities with @acronym{AT&T} @code{troff}
13506 @cindex @code{\?}, incompatibilities with @acronym{AT&T} @code{troff}
13507 @cindex transparent output, incompatibilities with @acronym{AT&T} @code{troff}
13508 @cindex output, transparent, incompatibilities with @acronym{AT&T} @code{troff}
13510 prints @samp{\\} in GNU @code{troff}; each pair of input backslashes
13511 is turned into one output backslash and the resulting output backslashes
13512 are not interpreted as escape characters when they are reread.
13513 @acronym{UNIX} @code{troff} would interpret them as escape characters
13514 when they were reread and would end up printing one @samp{\}. The
13515 correct way to obtain a printable backslash is to use the @code{\e}
13516 escape sequence: This always prints a single instance of the current
13517 escape character, regardless of whether or not it is used in a
13518 diversion; it also works in both GNU @code{troff} and @acronym{UNIX}
13519 @code{troff}.@footnote{To be completely independent of the current
13520 escape character, use @code{\(rs} which represents a reverse solidus
13521 (backslash) glyph.} To store, for some reason, an escape sequence in a
13522 diversion that will be interpreted when the diversion is reread, either
13523 use the traditional @code{\!} transparent output facility, or, if this
13524 is unsuitable, the new @code{\?} escape sequence.
13526 @xref{Diversions}, and @ref{Gtroff Internals}, for more information.
13530 @c =====================================================================
13531 @c =====================================================================
13533 @node Preprocessors, Output Devices, gtroff Reference, Top
13534 @chapter Preprocessors
13535 @cindex preprocessors
13537 This chapter describes all preprocessors that come with @code{groff} or
13538 which are freely available.
13551 @c =====================================================================
13553 @node geqn, gtbl, Preprocessors, Preprocessors
13554 @section @code{geqn}
13555 @cindex @code{eqn}, the program
13556 @cindex @code{geqn}, the program
13564 @c ---------------------------------------------------------------------
13566 @node Invoking geqn, , geqn, geqn
13567 @subsection Invoking @code{geqn}
13568 @cindex invoking @code{geqn}
13569 @cindex @code{geqn}, invoking
13574 @c =====================================================================
13576 @node gtbl, gpic, geqn, Preprocessors
13577 @section @code{gtbl}
13578 @cindex @code{tbl}, the program
13579 @cindex @code{gtbl}, the program
13587 @c ---------------------------------------------------------------------
13589 @node Invoking gtbl, , gtbl, gtbl
13590 @subsection Invoking @code{gtbl}
13591 @cindex invoking @code{gtbl}
13592 @cindex @code{gtbl}, invoking
13597 @c =====================================================================
13599 @node gpic, ggrn, gtbl, Preprocessors
13600 @section @code{gpic}
13601 @cindex @code{pic}, the program
13602 @cindex @code{gpic}, the program
13610 @c ---------------------------------------------------------------------
13612 @node Invoking gpic, , gpic, gpic
13613 @subsection Invoking @code{gpic}
13614 @cindex invoking @code{gpic}
13615 @cindex @code{gpic}, invoking
13620 @c =====================================================================
13622 @node ggrn, grap, gpic, Preprocessors
13623 @section @code{ggrn}
13624 @cindex @code{grn}, the program
13625 @cindex @code{ggrn}, the program
13633 @c ---------------------------------------------------------------------
13635 @node Invoking ggrn, , ggrn, ggrn
13636 @subsection Invoking @code{ggrn}
13637 @cindex invoking @code{ggrn}
13638 @cindex @code{ggrn}, invoking
13643 @c =====================================================================
13645 @node grap, grefer, ggrn, Preprocessors
13646 @section @code{grap}
13647 @cindex @code{grap}, the program
13649 A free implementation of @code{grap}, written by Ted Faber,
13650 is available as an extra package from the following address:
13653 @uref{http://www.lunabase.org/~faber/Vault/software/grap/}
13657 @c =====================================================================
13659 @node grefer, gsoelim, grap, Preprocessors
13660 @section @code{grefer}
13661 @cindex @code{refer}, the program
13662 @cindex @code{grefer}, the program
13667 * Invoking grefer::
13670 @c ---------------------------------------------------------------------
13672 @node Invoking grefer, , grefer, grefer
13673 @subsection Invoking @code{grefer}
13674 @cindex invoking @code{grefer}
13675 @cindex @code{grefer}, invoking
13680 @c =====================================================================
13682 @node gsoelim, , grefer, Preprocessors
13683 @section @code{gsoelim}
13684 @cindex @code{soelim}, the program
13685 @cindex @code{gsoelim}, the program
13690 * Invoking gsoelim::
13693 @c ---------------------------------------------------------------------
13695 @node Invoking gsoelim, , gsoelim, gsoelim
13696 @subsection Invoking @code{gsoelim}
13697 @cindex invoking @code{gsoelim}
13698 @cindex @code{gsoelim}, invoking
13704 @c =====================================================================
13705 @c =====================================================================
13707 @node Output Devices, File formats, Preprocessors, Top
13708 @chapter Output Devices
13709 @cindex output devices
13710 @cindex devices for output
13715 * Special Characters::
13726 @c =====================================================================
13728 @node Special Characters, grotty, Output Devices, Output Devices
13729 @section Special Characters
13730 @cindex special characters
13731 @cindex characters, special
13738 @c =====================================================================
13740 @node grotty, grops, Special Characters, Output Devices
13741 @section @code{grotty}
13742 @cindex @code{grotty}, the program
13747 * Invoking grotty::
13750 @c ---------------------------------------------------------------------
13752 @node Invoking grotty, , grotty, grotty
13753 @subsection Invoking @code{grotty}
13754 @cindex invoking @code{grotty}
13755 @cindex @code{grotty}, invoking
13759 @c The following is no longer true; fix and extend it.
13762 @c @cindex Teletype
13763 @c @cindex ISO 6249 SGR
13764 @c @cindex terminal control sequences
13765 @c @cindex control sequences, for terminals
13766 @c For TTY output devices, underlining is done by emitting sequences of
13767 @c @samp{_} and @samp{\b} (the backspace character) before the actual
13768 @c character. Literally, this is printing an underline character, then
13769 @c moving back one character position, and printing the actual character
13770 @c at the same position as the underline character (similar to a
13771 @c typewriter). Usually, a modern terminal can't interpret this (and the
13772 @c original Teletype machines for which this sequence was appropriate are
13773 @c no longer in use). You need a pager program like @code{less} which
13774 @c translates this into ISO 6429 SGR sequences to control terminals.
13777 @c =====================================================================
13779 @node grops, grodvi, grotty, Output Devices
13780 @section @code{grops}
13781 @cindex @code{grops}, the program
13787 * Embedding PostScript::
13790 @c ---------------------------------------------------------------------
13792 @node Invoking grops, Embedding PostScript, grops, grops
13793 @subsection Invoking @code{grops}
13794 @cindex invoking @code{grops}
13795 @cindex @code{grops}, invoking
13799 @c ---------------------------------------------------------------------
13801 @node Embedding PostScript, , Invoking grops, grops
13802 @subsection Embedding @sc{PostScript}
13803 @cindex embedding PostScript
13804 @cindex PostScript, embedding
13809 @c =====================================================================
13811 @node grodvi, grolj4, grops, Output Devices
13812 @section @code{grodvi}
13813 @cindex @code{grodvi}, the program
13818 * Invoking grodvi::
13821 @c ---------------------------------------------------------------------
13823 @node Invoking grodvi, , grodvi, grodvi
13824 @subsection Invoking @code{grodvi}
13825 @cindex invoking @code{grodvi}
13826 @cindex @code{grodvi}, invoking
13831 @c =====================================================================
13833 @node grolj4, grolbp, grodvi, Output Devices
13834 @section @code{grolj4}
13835 @cindex @code{grolj4}, the program
13840 * Invoking grolj4::
13843 @c ---------------------------------------------------------------------
13845 @node Invoking grolj4, , grolj4, grolj4
13846 @subsection Invoking @code{grolj4}
13847 @cindex invoking @code{grolj4}
13848 @cindex @code{grolj4}, invoking
13853 @c =====================================================================
13855 @node grolbp, grohtml, grolj4, Output Devices
13856 @section @code{grolbp}
13857 @cindex @code{grolbp}, the program
13862 * Invoking grolbp::
13865 @c ---------------------------------------------------------------------
13867 @node Invoking grolbp, , grolbp, grolbp
13868 @subsection Invoking @code{grolbp}
13869 @cindex invoking @code{grolbp}
13870 @cindex @code{grolbp}, invoking
13875 @c =====================================================================
13877 @node grohtml, gxditview, grolbp, Output Devices
13878 @section @code{grohtml}
13879 @cindex @code{grohtml}, the program
13884 * Invoking grohtml::
13885 * grohtml specific registers and strings::
13888 @c ---------------------------------------------------------------------
13890 @node Invoking grohtml, grohtml specific registers and strings, grohtml, grohtml
13891 @subsection Invoking @code{grohtml}
13892 @cindex invoking @code{grohtml}
13893 @cindex @code{grohtml}, invoking
13897 @c ---------------------------------------------------------------------
13899 @node grohtml specific registers and strings, , Invoking grohtml, grohtml
13900 @subsection @code{grohtml} specific registers and strings
13901 @cindex registers specific to @code{grohtml}
13902 @cindex strings specific to @code{grohtml}
13903 @cindex @code{grohtml}, registers and strings
13905 @DefmpregList {ps4html, grohtml}
13906 @DefstrListEnd {www-image-template, grohtml}
13907 The registers @code{ps4html} and @code{www-image-template} are defined
13908 by the @code{pre-grohtml} preprocessor. @code{pre-grohtml} reads in
13909 the @code{troff} input, marks up the inline equations and passes the
13913 troff -Tps -rps4html=1 -dwww-image-template=@var{template}
13923 The PostScript device is used to create all the image files, and the
13924 register @code{ps4html} enables the macro sets to ignore floating
13925 keeps, footers, and headings.
13927 The register @code{www-image-template} is set to the user specified
13928 template name or the default name.
13932 @c =====================================================================
13934 @node gxditview, , grohtml, Output Devices
13935 @section @code{gxditview}
13936 @cindex @code{gxditview}, the program
13941 * Invoking gxditview::
13944 @c ---------------------------------------------------------------------
13946 @node Invoking gxditview, , gxditview, gxditview
13947 @subsection Invoking @code{gxditview}
13948 @cindex invoking @code{gxditview}
13949 @cindex @code{gxditview}, invoking
13956 @c =====================================================================
13957 @c =====================================================================
13959 @node File formats, Installation, Output Devices, Top
13960 @chapter File formats
13961 @cindex file formats
13962 @cindex formats, file
13964 All files read and written by @code{gtroff} are text files. The
13965 following two sections describe their format.
13973 @c =====================================================================
13975 @node gtroff Output, Font Files, File formats, File formats
13976 @section @code{gtroff} Output
13977 @cindex @code{gtroff}, output
13978 @cindex output, @code{gtroff}
13980 This section describes the intermediate output format of GNU
13981 @code{troff}. This output is produced by a run of @code{gtroff}
13982 before it is fed into a device postprocessor program.
13984 As @code{groff} is a wrapper program around @code{gtroff} that
13985 automatically calls a postprocessor, this output does not show up
13986 normally. This is why it is called @dfn{intermediate}.
13987 @code{groff} provides the option @option{-Z} to inhibit postprocessing,
13988 such that the produced intermediate output is sent to standard output
13989 just like calling @code{gtroff} manually.
13991 @cindex troff output
13992 @cindex output, troff
13993 @cindex intermediate output
13994 @cindex output, intermediate
13995 Here, the term @dfn{troff output} describes what is output by
13996 @code{gtroff}, while @dfn{intermediate output} refers to the language
13997 that is accepted by the parser that prepares this output for the
13998 postprocessors. This parser is smarter on whitespace and implements
13999 obsolete elements for compatibility, otherwise both formats are the
14000 same.@footnote{The parser and postprocessor for intermediate output
14001 can be found in the file@*
14002 @file{@var{groff-source-dir}/src/libs/libdriver/input.cpp}.}
14004 The main purpose of the intermediate output concept is to facilitate
14005 the development of postprocessors by providing a common programming
14006 interface for all devices. It has a language of its own that is
14007 completely different from the @code{gtroff} language. While the
14008 @code{gtroff} language is a high-level programming language for text
14009 processing, the intermediate output language is a kind of low-level
14010 assembler language by specifying all positions on the page for writing
14013 The intermediate output produced by @code{gtroff} is fairly readable,
14014 while output from @acronym{AT&T} @code{troff} is rather hard to
14015 understand because of strange habits that are still supported, but not
14016 used any longer by @code{gtroff}.
14019 * Language Concepts::
14020 * Command Reference::
14021 * Intermediate Output Examples::
14022 * Output Language Compatibility::
14025 @c ---------------------------------------------------------------------
14027 @node Language Concepts, Command Reference, gtroff Output, gtroff Output
14028 @subsection Language Concepts
14030 During the run of @code{gtroff}, the input data is cracked down to the
14031 information on what has to be printed at what position on the intended
14032 device. So the language of the intermediate output format can be quite
14033 small. Its only elements are commands with and without arguments.
14034 In this section, the term @dfn{command} always refers to the intermediate
14035 output language, and never to the @code{gtroff} language used for document
14036 formatting. There are commands for positioning and text writing, for drawing, and
14037 for device controlling.
14045 @node Separation, Argument Units, Language Concepts, Language Concepts
14046 @subsubsection Separation
14048 @acronym{AT&T} @code{troff} output has strange requirements on whitespace.
14049 The @code{gtroff} output parser, however, is smart about whitespace by
14050 making it maximally optional. The whitespace characters, i.e., the
14051 tab, space, and newline characters, always have a syntactical meaning.
14052 They are never printable because spacing within the output is always
14053 done by positioning commands.
14055 Any sequence of space or tab characters is treated as a single
14056 @dfn{syntactical space}. It separates commands and arguments, but is
14057 only required when there would occur a clashing between the command code
14058 and the arguments without the space. Most often, this happens when
14059 variable-length command names, arguments, argument lists, or command
14060 clusters meet. Commands and arguments with a known, fixed length need
14061 not be separated by syntactical space.
14063 A line break is a syntactical element, too. Every command argument can be
14064 followed by whitespace, a comment, or a newline character. Thus a
14065 @dfn{syntactical line break} is defined to consist of optional
14066 syntactical space that is optionally followed by a comment, and a
14069 The normal commands, those for positioning and text, consist of a
14070 single letter taking a fixed number of arguments. For historical reasons,
14071 the parser allows to stack such commands on the same line, but
14072 fortunately, in @code{gtroff}'s intermediate output, every command with
14073 at least one argument is followed by a line break, thus providing
14074 excellent readability.
14076 The other commands -- those for drawing and device controlling --
14077 have a more complicated structure; some recognize long command names,
14078 and some take a variable number of arguments. So all @samp{D} and
14079 @samp{x} commands were designed to request a syntactical line break
14080 after their last argument. Only one command, @w{@samp{x X}},
14081 has an argument that can stretch over several lines; all other
14082 commands must have all of their arguments on the same line as the
14083 command, i.e., the arguments may not be splitted by a line break.
14085 Empty lines (these are lines containing only space and/or a comment), can
14086 occur everywhere. They are just ignored.
14088 @node Argument Units, Document Parts, Separation, Language Concepts
14089 @subsubsection Argument Units
14091 Some commands take integer arguments that are assumed to represent
14092 values in a measurement unit, but the letter for the corresponding
14093 scale indicator is not written with the output command arguments.
14094 Most commands assume the scale indicator @samp{u}, the basic unit of
14095 the device, some use @samp{z}, the scaled point unit of the device,
14096 while others, such as the color commands, expect plain integers.
14098 Note that single characters can have the eighth bit set, as can the
14099 names of fonts and special characters. The names of characters and
14100 fonts can be of arbitrary length. A character that is to be printed
14101 will always be in the current font.
14103 A string argument is always terminated by the next whitespace
14104 character (space, tab, or newline); an embedded @samp{#} character is
14105 regarded as part of the argument, not as the beginning of a comment
14106 command. An integer argument is already terminated by the next
14107 non-digit character, which then is regarded as the first character of
14108 the next argument or command.
14110 @node Document Parts, , Argument Units, Language Concepts
14111 @subsubsection Document Parts
14113 A correct intermediate output document consists of two parts, the
14114 @dfn{prologue} and the @dfn{body}.
14116 The task of the prologue is to set the general device parameters
14117 using three exactly specified commands. @code{gtroff}'s prologue
14118 is guaranteed to consist of the following three lines (in that order):
14122 x res @var{n} @var{h} @var{v}
14127 with the arguments set as outlined in @ref{Device Control Commands}.
14128 Note that the parser for the intermediate output format is able to
14129 swallow additional whitespace and comments as well even in the
14132 The body is the main section for processing the document data.
14133 Syntactically, it is a sequence of any commands different from the
14134 ones used in the prologue. Processing is terminated as soon as the
14135 first @w{@samp{x stop}} command is encountered; the last line of any
14136 @code{gtroff} intermediate output always contains such a command.
14138 Semantically, the body is page oriented. A new page is started by a
14139 @samp{p} command. Positioning, writing, and drawing commands are
14140 always done within the current page, so they cannot occur before the
14141 first @samp{p} command. Absolute positioning (by the @samp{H} and
14142 @samp{V} commands) is done relative to the current page; all other
14143 positioning is done relative to the current location within this page.
14145 @c ---------------------------------------------------------------------
14147 @node Command Reference, Intermediate Output Examples, Language Concepts, gtroff Output
14148 @subsection Command Reference
14150 This section describes all intermediate output commands, both from
14151 @acronym{AT&T} @code{troff} as well as the @code{gtroff} extensions.
14154 * Comment Command::
14155 * Simple Commands::
14156 * Graphics Commands::
14157 * Device Control Commands::
14158 * Obsolete Command::
14161 @node Comment Command, Simple Commands, Command Reference, Command Reference
14162 @subsubsection Comment Command
14165 @item #@var{anything}@angles{end of line}
14166 A comment. Ignore any characters from the @samp{#} character up to
14167 the next newline character.
14169 This command is the only possibility for commenting in the intermediate
14170 output. Each comment can be preceded by arbitrary syntactical space;
14171 every command can be terminated by a comment.
14174 @node Simple Commands, Graphics Commands, Comment Command, Command Reference
14175 @subsubsection Simple Commands
14177 The commands in this subsection have a command code consisting of a
14178 single character, taking a fixed number of arguments. Most of them
14179 are commands for positioning and text writing. These commands are
14180 smart about whitespace. Optionally, syntactical space can be inserted
14181 before, after, and between the command letter and its arguments.
14182 All of these commands are stackable, i.e., they can be preceded by
14183 other simple commands or followed by arbitrary other commands on the
14184 same line. A separating syntactical space is only necessary when two
14185 integer arguments would clash or if the preceding argument ends with a
14190 .if (\n[@USE_ENV_STACK] == 1) \{\
14192 Open a new environment by copying the actual device configuration data
14193 to the environment stack.
14195 The current environment is setup by the device specification and
14196 manipulated by the setting commands.
14200 Close the actual environment (opened by a preceding
14202 and restore the previous environment from the environment
14203 stack as the actual device configuration data.
14205 \} \" endif @USE_ENV_STACK
14208 @item C @var{xxx}@angles{whitespace}
14209 Print a special character named @var{xxx}. The trailing
14210 syntactical space or line break is necessary to allow glyph names
14211 of arbitrary length. The glyph is printed at the current print
14212 position; the glyph's size is read from the font file. The print
14213 position is not changed.
14216 Print glyph@tie{}@var{g} at the current print position;@footnote{@samp{c}
14217 is actually a misnomer since it outputs a glyph.} the glyph's size is
14218 read from the font file. The print position is not changed.
14221 Set font to font number@tie{}@var{n} (a non-negative integer).
14224 Move right to the absolute vertical position@tie{}@var{n} (a
14225 non-negative integer in basic units @samp{u} relative to left edge
14229 Move @var{n} (a non-negative integer) basic units @samp{u} horizontally
14230 to the right. The original @acronym{UNIX} troff manual allows negative
14231 values for @var{n} also, but @code{gtroff} doesn't use this.
14233 @item m @var{color-scheme} @r{[}@var{component} @dots{}@r{]}
14234 Set the color for text (glyphs), line drawing, and the outline of
14235 graphic objects using different color schemes; the analoguous command
14236 for the filling color of graphic objects is @samp{DF}. The color
14237 components are specified as integer arguments between 0 and 65536.
14238 The number of color components and their meaning vary for the
14239 different color schemes. These commands are generated by
14240 @code{gtroff}'s escape sequence @code{\m}. No position changing.
14241 These commands are a @code{gtroff} extension.
14244 @item mc @var{cyan} @var{magenta} @var{yellow}
14245 Set color using the CMY color scheme, having the 3@tie{}color components
14246 @var{cyan}, @var{magenta}, and @var{yellow}.
14249 Set color to the default color value (black in most cases).
14250 No component arguments.
14252 @item mg @var{gray}
14253 Set color to the shade of gray given by the argument, an integer
14254 between 0 (black) and 65536 (white).
14256 @item mk @var{cyan} @var{magenta} @var{yellow} @var{black}
14257 Set color using the CMYK color scheme, having the 4@tie{}color components
14258 @var{cyan}, @var{magenta}, @var{yellow}, and @var{black}.
14260 @item mr @var{red} @var{green} @var{blue}
14261 Set color using the RGB color scheme, having the 3@tie{}color components
14262 @var{red}, @var{green}, and @var{blue}.
14266 Print glyph with index@tie{}@var{n} (a non-negative integer) of the
14267 current font. This command is a @code{gtroff} extension.
14269 @item n @var{b} @var{a}
14270 Inform the device about a line break, but no positioning is done by
14271 this command. In @acronym{AT&T} @code{troff}, the integer arguments
14272 @var{b} and@tie{}@var{a} informed about the space before and after the
14273 current line to make the intermediate output more human readable
14274 without performing any action. In @code{groff}, they are just ignored, but
14275 they must be provided for compatibility reasons.
14278 Begin a new page in the outprint. The page number is set
14279 to@tie{}@var{n}. This page is completely independent of pages formerly
14280 processed even if those have the same page number. The vertical
14281 position on the outprint is automatically set to@tie{}0. All
14282 positioning, writing, and drawing is always done relative to a page,
14283 so a @samp{p} command must be issued before any of these commands.
14286 Set point size to @var{n}@tie{}scaled points (this is unit @samp{z}).
14287 @acronym{AT&T} @code{troff} used the unit points (@samp{p}) instead.
14288 @xref{Output Language Compatibility}.
14290 @item t @var{xxx}@angles{whitespace}
14291 @itemx t @var{xxx} @var{dummy-arg}@angles{whitespace}
14292 Print a word, i.e., a sequence of characters @var{xxx} representing
14293 output glyphs which names are single characters, terminated by
14294 a space character or a line break; an optional second integer argument
14295 is ignored (this allows the formatter to generate an even number of
14296 arguments). The first glyph should be printed at the current
14297 position, the current horizontal position should then be increased by
14298 the width of the first glyph, and so on for each glyph.
14299 The widths of the glyphs are read from the font file, scaled for the
14300 current point size, and rounded to a multiple of the horizontal
14301 resolution. Special characters cannot be printed using this command
14302 (use the @samp{C} command for special characters). This command is a
14303 @code{gtroff} extension; it is only used for devices whose @file{DESC}
14304 file contains the @code{tcommand} keyword (@pxref{DESC File Format}).
14306 @item u @var{n} @var{xxx}@angles{whitespace}
14307 Print word with track kerning. This is the same as the @samp{t}
14308 command except that after printing each glyph, the current
14309 horizontal position is increased by the sum of the width of that
14310 glyph and@tie{}@var{n} (an integer in basic units @samp{u}).
14311 This command is a @code{gtroff} extension; it is only used for devices
14312 whose @file{DESC} file contains the @code{tcommand} keyword
14313 (@pxref{DESC File Format}).
14316 Move down to the absolute vertical position@tie{}@var{n} (a
14317 non-negative integer in basic units @samp{u}) relative to upper edge
14321 Move @var{n}@tie{}basic units @samp{u} down (@var{n} is a non-negative
14322 integer). The original @acronym{UNIX} troff manual allows negative
14323 values for @var{n} also, but @code{gtroff} doesn't use this.
14326 Informs about a paddable white space to increase readability.
14327 The spacing itself must be performed explicitly by a move command.
14330 @node Graphics Commands, Device Control Commands, Simple Commands, Command Reference
14331 @subsubsection Graphics Commands
14333 Each graphics or drawing command in the intermediate output starts
14334 with the letter @samp{D}, followed by one or two characters that
14335 specify a subcommand; this is followed by a fixed or variable number
14336 of integer arguments that are separated by a single space character.
14337 A @samp{D} command may not be followed by another command on the same line
14338 (apart from a comment), so each @samp{D} command is terminated by a
14339 syntactical line break.
14341 @code{gtroff} output follows the classical spacing rules (no space
14342 between command and subcommand, all arguments are preceded by a
14343 single space character), but the parser allows optional space between
14344 the command letters and makes the space before the first argument
14345 optional. As usual, each space can be any sequence of tab and space
14348 Some graphics commands can take a variable number of arguments.
14349 In this case, they are integers representing a size measured in basic
14350 units @samp{u}. The arguments called @var{h1}, @var{h2}, @dots{},
14351 @var{hn} stand for horizontal distances where positive means right,
14352 negative left. The arguments called @var{v1}, @var{v2}, @dots{},
14353 @var{vn} stand for vertical distances where positive means down,
14354 negative up. All these distances are offsets relative to the current
14357 Each graphics command directly corresponds to a similar @code{gtroff}
14358 @code{\D} escape sequence. @xref{Drawing Requests}.
14360 Unknown @samp{D} commands are assumed to be device-specific.
14361 Its arguments are parsed as strings; the whole information is then
14362 sent to the postprocessor.
14364 In the following command reference, the syntax element
14365 @angles{line break} means a syntactical line break as defined above.
14368 @item D~ @var{h1} @var{v1} @var{h2} @var{v2} @dots{} @var{hn} @var{vn}@angles{line break}
14369 Draw B-spline from current position to offset (@var{h1},@var{v1}),
14370 then to offset (@var{h2},@var{v2}), if given, etc.@: up to
14371 (@var{hn},@var{vn}). This command takes a variable number of argument
14372 pairs; the current position is moved to the terminal point of the drawn
14375 @item Da @var{h1} @var{v1} @var{h2} @var{v2}@angles{line break}
14376 Draw arc from current position to
14377 (@var{h1},@var{v1})@math{+}(@var{h2},@var{v2}) with center at
14378 (@var{h1},@var{v1}); then move the current position to the final point
14381 @item DC @var{d}@angles{line break}
14382 @itemx DC @var{d} @var{dummy-arg}@angles{line break}
14383 Draw a solid circle using the current fill color with
14384 diameter@tie{}@var{d} (integer in basic units @samp{u}) with leftmost
14385 point at the current position; then move the current position to the
14386 rightmost point of the circle. An optional second integer argument is
14387 ignored (this allows the formatter to generate an even number of
14388 arguments). This command is a @code{gtroff} extension.
14390 @item Dc @var{d}@angles{line break}
14391 Draw circle line with diameter@tie{}@var{d} (integer in basic units
14392 @samp{u}) with leftmost point at the current position; then move the
14393 current position to the rightmost point of the circle.
14395 @item DE @var{h} @var{v}@angles{line break}
14396 Draw a solid ellipse in the current fill color with a horizontal
14397 diameter of@tie{}@var{h} and a vertical diameter of@tie{}@var{v} (both
14398 integers in basic units @samp{u}) with the leftmost point at the
14399 current position; then move to the rightmost point of the ellipse.
14400 This command is a @code{gtroff} extension.
14402 @item De @var{h} @var{v}@angles{line break}
14403 Draw an outlined ellipse with a horizontal diameter of@tie{}@var{h}
14404 and a vertical diameter of@tie{}@var{v} (both integers in basic units
14405 @samp{u}) with the leftmost point at current position; then move to
14406 the rightmost point of the ellipse.
14408 @item DF @var{color-scheme} @r{[}@var{component} @dots{}@r{]}@angles{line break}
14409 Set fill color for solid drawing objects using different color
14410 schemes; the analoguous command for setting the color of text, line
14411 graphics, and the outline of graphic objects is @samp{m}.
14412 The color components are specified as integer arguments between 0 and
14413 65536. The number of color components and their meaning vary for the
14414 different color schemes. These commands are generated by @code{gtroff}'s
14415 escape sequences @w{@code{\D'F @dots{}'}} and @code{\M} (with no other
14416 corresponding graphics commands). No position changing. This command
14417 is a @code{gtroff} extension.
14420 @item DFc @var{cyan} @var{magenta} @var{yellow}@angles{line break}
14421 Set fill color for solid drawing objects using the CMY color scheme,
14422 having the 3@tie{}color components @var{cyan}, @var{magenta}, and
14425 @item DFd@angles{line break}
14426 Set fill color for solid drawing objects to the default fill color value
14427 (black in most cases). No component arguments.
14429 @item DFg @var{gray}@angles{line break}
14430 Set fill color for solid drawing objects to the shade of gray given by
14431 the argument, an integer between 0 (black) and 65536 (white).
14433 @item DFk @var{cyan} @var{magenta} @var{yellow} @var{black}@angles{line break}
14434 Set fill color for solid drawing objects using the CMYK color scheme,
14435 having the 4@tie{}color components @var{cyan}, @var{magenta}, @var{yellow},
14438 @item DFr @var{red} @var{green} @var{blue}@angles{line break}
14439 Set fill color for solid drawing objects using the RGB color scheme,
14440 having the 3@tie{}color components @var{red}, @var{green}, and @var{blue}.
14443 @item Df @var{n}@angles{line break}
14444 The argument@tie{}@var{n} must be an integer in the range @math{-32767}
14448 @item @math{0 @LE @var{n} @LE 1000}
14449 Set the color for filling solid drawing objects to a shade of gray,
14450 where 0 corresponds to solid white, 1000 (the default) to solid black,
14451 and values in between to intermediate shades of gray; this is
14452 obsoleted by command @samp{DFg}.
14454 @item @math{@var{n} < 0} or @math{@var{n} > 1000}
14455 Set the filling color to the color that is currently being used for
14456 the text and the outline, see command @samp{m}. For example, the
14465 sets all colors to blue.
14469 No position changing. This command is a @code{gtroff} extension.
14471 @item Dl @var{h} @var{v}@angles{line break}
14472 Draw line from current position to offset (@var{h},@var{v}) (integers
14473 in basic units @samp{u}); then set current position to the end of the
14476 @item Dp @var{h1} @var{v1} @var{h2} @var{v2} @dots{} @var{hn} @var{vn}@angles{line break}
14477 Draw a polygon line from current position to offset (@var{h1},@var{v1}),
14478 from there to offset (@var{h2},@var{v2}), etc.@: up to offset
14479 (@var{hn},@var{vn}), and from there back to the starting position.
14480 For historical reasons, the position is changed by adding the sum of
14481 all arguments with odd index to the actual horizontal position and the
14482 even ones to the vertical position. Although this doesn't make sense
14483 it is kept for compatibility.
14485 As the polygon is closed, the end of drawing is the starting point, so
14486 the position doesn't change.
14488 This command is a @code{gtroff} extension.
14490 @item Dp @var{h1} @var{v1} @var{h2} @var{v2} @dots{} @var{hn} @var{vn}@angles{line break}
14491 Draw a solid polygon in the current fill color rather than an outlined
14492 polygon, using the same arguments and positioning as the corresponding
14495 No position changing.
14497 This command is a @code{gtroff} extension.
14499 @item Dt @var{n}@angles{line break}
14500 Set the current line thickness to@tie{}@var{n} (an integer in basic
14501 units @samp{u}) if @math{@var{n}>0}; if @math{@var{n}=0} select the
14502 smallest available line thickness; if @math{@var{n}<0} set the line
14503 thickness proportional to the point size (this is the default before
14504 the first @samp{Dt} command was specified). For historical reasons,
14505 the horizontal position is changed by adding the argument to the actual
14506 horizontal position, while the vertical position is not changed.
14507 Although this doesn't make sense it is kept for compatibility.
14509 No position changing.
14511 This command is a @code{gtroff} extension.
14514 @node Device Control Commands, Obsolete Command, Graphics Commands, Command Reference
14515 @subsubsection Device Control Commands
14517 Each device control command starts with the letter @samp{x},
14518 followed by a space character (optional or arbitrary space or tab in
14519 @code{gtroff}) and a subcommand letter or word; each argument (if any)
14520 must be preceded by a syntactical space. All @samp{x} commands are
14521 terminated by a syntactical line break; no device control command can
14522 be followed by another command on the same line (except a comment).
14524 The subcommand is basically a single letter, but to increase
14525 readability, it can be written as a word, i.e., an arbitrary sequence
14526 of characters terminated by the next tab, space, or newline character.
14527 All characters of the subcommand word but the first are simply ignored.
14528 For example, @code{gtroff} outputs the initialization command
14529 @w{@samp{x i}} as @w{@samp{x init}} and the resolution command
14530 @w{@samp{x r}} as @w{@samp{x res}}.
14532 In the following, the syntax element @angles{line break} means a
14533 syntactical line break (@pxref{Separation}).
14536 @item xF @var{name}@angles{line break}
14537 The @samp{F} stands for @var{Filename}.
14539 Use @var{name} as the intended name for the current file in error
14540 reports. This is useful for remembering the original file name when
14541 @code{gtroff} uses an internal piping mechanism. The input file is
14542 not changed by this command. This command is a @code{gtroff} extension.
14544 @item xf @var{n} @var{s}@angles{line break}
14545 The @samp{f} stands for @var{font}.
14547 Mount font position@tie{}@var{n} (a non-negative integer) with font
14548 named@tie{}@var{s} (a text word). @xref{Font Positions}.
14550 @item xH @var{n}@angles{line break}
14551 The @samp{H} stands for @var{Height}.
14553 Set glyph height to@tie{}@var{n} (a positive integer in scaled
14554 points @samp{z}). @acronym{AT&T} @code{troff} uses the unit points
14555 (@samp{p}) instead. @xref{Output Language Compatibility}.
14557 @item xi@angles{line break}
14558 The @samp{i} stands for @var{init}.
14560 Initialize device. This is the third command of the prologue.
14562 @item xp@angles{line break}
14563 The @samp{p} stands for @var{pause}.
14565 Parsed but ignored. The original @acronym{UNIX} troff manual writes
14568 pause device, can be restarted
14571 @item xr @var{n} @var{h} @var{v}@angles{line break}
14572 The @samp{r} stands for @var{resolution}.
14574 Resolution is@tie{}@var{n}, while @var{h} is the minimal horizontal
14575 motion, and @var{v} the minimal vertical motion possible with this
14576 device; all arguments are positive integers in basic units @samp{u}
14577 per inch. This is the second command of the prologue.
14579 @item xS @var{n}@angles{line break}
14580 The @samp{S} stands for @var{Slant}.
14582 Set slant to@tie{}@var{n} (an integer in basic units @samp{u}).
14584 @item xs@angles{line break}
14585 The @samp{s} stands for @var{stop}.
14587 Terminates the processing of the current file; issued as the last
14588 command of any intermediate troff output.
14590 @item xt@angles{line break}
14591 The @samp{t} stands for @var{trailer}.
14593 Generate trailer information, if any. In @var{gtroff}, this is
14594 actually just ignored.
14596 @item xT @var{xxx}@angles{line break}
14597 The @samp{T} stands for @var{Typesetter}.
14599 Set name of device to word @var{xxx}, a sequence of characters ended
14600 by the next white space character. The possible device names coincide
14601 with those from the @code{groff} @option{-T} option. This is the first
14602 command of the prologue.
14604 @item xu @var{n}@angles{line break}
14605 The @samp{u} stands for @var{underline}.
14607 Configure underlining of spaces. If @var{n} is@tie{}1, start
14608 underlining of spaces; if @var{n} is@tie{}0, stop underlining of spaces.
14609 This is needed for the @code{cu} request in nroff mode and is ignored
14610 otherwise. This command is a @code{gtroff} extension.
14612 @item xX @var{anything}@angles{line break}
14613 The @samp{x} stands for @var{X-escape}.
14615 Send string @var{anything} uninterpreted to the device. If the line
14616 following this command starts with a @samp{+} character this line is
14617 interpreted as a continuation line in the following sense. The
14618 @samp{+} is ignored, but a newline character is sent instead to the
14619 device, the rest of the line is sent uninterpreted. The same applies
14620 to all following lines until the first character of a line is not a
14621 @samp{+} character. This command is generated by the @code{gtroff}
14622 escape sequence @code{\X}. The line-continuing feature is a
14623 @code{gtroff} extension.
14626 @node Obsolete Command, , Device Control Commands, Command Reference
14627 @subsubsection Obsolete Command
14628 In @acronym{AT&T} @code{troff} output, the writing of a single
14629 glyph is mostly done by a very strange command that combines a
14630 horizontal move and a single character giving the glyph name. It
14631 doesn't have a command code, but is represented by a 3-character
14632 argument consisting of exactly 2@tie{}digits and a character.
14635 @item @var{dd}@var{g}
14636 Move right @var{dd} (exactly two decimal digits) basic units @samp{u},
14637 then print glyph@tie{}@var{g} (represented as a single character).
14639 In @code{gtroff}, arbitrary syntactical space around and within this
14640 command is allowed to be added. Only when a preceding command on the
14641 same line ends with an argument of variable length a separating space
14642 is obligatory. In @acronym{AT&T} @code{troff}, large clusters of these
14643 and other commands are used, mostly without spaces; this made such output
14647 For modern high-resolution devices, this command does not make sense
14648 because the width of the glyphs can become much larger than two
14649 decimal digits. In @code{gtroff}, this is only used for the devices
14650 @code{X75}, @code{X75-12}, @code{X100}, and @code{X100-12}. For other
14651 devices, the commands @samp{t} and @samp{u} provide a better
14654 @c ---------------------------------------------------------------------
14656 @node Intermediate Output Examples, Output Language Compatibility, Command Reference, gtroff Output
14657 @subsection Intermediate Output Examples
14659 This section presents the intermediate output generated from the same
14660 input for three different devices. The input is the sentence
14661 @samp{hell world} fed into @code{gtroff} on the command line.
14664 @item High-resolution device @code{ps}
14666 This is the standard output of @code{gtroff} if no @option{-T} option
14671 shell> echo "hell world" | groff -Z -T ps
14697 This output can be fed into @code{grops} to get its representation as
14700 @item Low-resolution device @code{latin1}
14702 This is similar to the high-resolution device except that the
14703 positioning is done at a minor scale. Some comments (lines starting
14704 with @samp{#}) were added for clarification; they were not generated
14709 shell> echo "hell world" | groff -Z -T latin1
14722 # initial positioning on the page
14725 # write text `hell'
14727 # inform about space, and issue a horizontal jump
14729 # write text `world'
14731 # announce line break, but do nothing because ...
14734 # ... the end of the document has been reached
14742 This output can be fed into @code{grotty} to get a formatted text
14745 @item @acronym{AT&T} @code{troff} output
14746 Since a computer monitor has a very low resolution compared to modern
14747 printers the intermediate output for the X@tie{}Window devices can use
14748 the jump-and-write command with its 2-digit displacements.
14752 shell> echo "hell world" | groff -Z -T X100
14764 # write text with jump-and-write commands
14765 ch07e07l03lw06w11o07r05l03dh7
14775 This output can be fed into @code{xditview} or @code{gxditview}
14776 for displaying in@tie{}X.
14778 Due to the obsolete jump-and-write command, the text clusters in the
14779 @acronym{AT&T} @code{troff} output are almost unreadable.
14782 @c ---------------------------------------------------------------------
14784 @node Output Language Compatibility, , Intermediate Output Examples, gtroff Output
14785 @subsection Output Language Compatibility
14787 The intermediate output language of @acronym{AT&T} @code{troff}
14788 was first documented in the @acronym{UNIX} troff manual, with later
14789 additions documented in @cite{A Typesetter-indenpendent TROFF},
14790 written by Brian Kernighan.
14792 The @code{gtroff} intermediate output format is compatible with this
14793 specification except for the following features.
14797 The classical quasi device independence is not yet implemented.
14800 The old hardware was very different from what we use today. So the
14801 @code{groff} devices are also fundamentally different from the ones in
14802 @acronym{AT&T} @code{troff}. For example, the @acronym{AT&T}
14803 PostScript device is called @code{post} and has a resolution of only
14804 720 units per inch, suitable for printers 20 years ago, while
14805 @code{groff}'s @code{ps} device has a resolution of
14806 72000 units per inch. Maybe, by implementing some rescaling
14807 mechanism similar to the classical quasi device independence,
14808 @code{groff} could emulate @acronym{AT&T}'s @code{post} device.
14811 The B-spline command @samp{D~} is correctly handled by the
14812 intermediate output parser, but the drawing routines aren't
14813 implemented in some of the postprocessor programs.
14816 The argument of the commands @samp{s} and @w{@samp{x H}} has the
14817 implicit unit scaled point @samp{z} in @code{gtroff}, while
14818 @acronym{AT&T} @code{troff} has point (@samp{p}). This isn't an
14819 incompatibility but a compatible extension, for both units coincide
14820 for all devices without a @code{sizescale} parameter in the @file{DESC}
14821 file, including all postprocessors from @acronym{AT&T} and
14822 @code{groff}'s text devices. The few @code{groff} devices with
14823 a @code{sizescale} parameter either do not exist for @acronym{AT&T}
14824 @code{troff}, have a different name, or seem to have a different
14825 resolution. So conflicts are very unlikely.
14828 The position changing after the commands @samp{Dp}, @samp{DP}, and
14829 @samp{Dt} is illogical, but as old versions of @code{gtroff} used this
14830 feature it is kept for compatibility reasons.
14833 Temporarily, there existed some confusion on the positioning after the
14834 @samp{D} commands that are groff extensions. This has been clarified
14835 by establishing the classical rule for all @code{groff} drawing commands:
14839 The position after a graphic object has been drawn is at its end;
14840 for circles and ellipses, the `end' is at the right side.
14843 From this, the positionings specified for the drawing commands above
14844 follow quite naturally.
14851 @c =====================================================================
14853 @node Font Files, , gtroff Output, File formats
14854 @section Font Files
14856 @cindex files, font
14858 The @code{gtroff} font format is roughly a superset of the
14859 @code{ditroff} font format (as used in later versions of @acronym{AT&T}
14860 @code{troff} and its descendants). Unlike the @code{ditroff} font
14861 format, there is no associated binary format; all files are text
14862 files.@footnote{Plan@tie{}9 @code{troff} has also abandoned the binary
14863 format.} The font files for device @var{name} are stored in a directory
14864 @file{dev@var{name}}. There are two types of file: a device description
14865 file called @file{DESC} and for each font@tie{}@var{f} a font file
14866 called@tie{}@file{@var{f}}.
14869 * DESC File Format::
14870 * Font File Format::
14873 @c ---------------------------------------------------------------------
14875 @node DESC File Format, Font File Format, Font Files, Font Files
14876 @subsection @file{DESC} File Format
14877 @cindex @file{DESC} file, format
14878 @cindex font description file, format
14879 @cindex format of font description file
14880 @pindex DESC@r{ file format}
14882 The @file{DESC} file can contain the following types of line. Except
14883 for the @code{charset} keyword which must comes last (if at all), the
14884 order of the lines is not important.
14889 @cindex device resolution
14890 @cindex resolution, device
14891 There are @var{n}@tie{}machine units per inch.
14895 @cindex horizontal resolution
14896 @cindex resolution, horizontal
14897 The horizontal resolution is @var{n}@tie{}machine units. All horizontal
14898 quantities are rounded to be multiples of this value.
14902 @cindex vertical resolution
14903 @cindex resolution, vertical
14904 The vertical resolution is @var{n}@tie{}machine units. All vertical
14905 quantities are rounded to be multiples of this value.
14907 @item sizescale @var{n}
14909 The scale factor for point sizes. By default this has a value of@tie{}1.
14910 One scaled point is equal to one point/@var{n}. The arguments to the
14911 @code{unitwidth} and @code{sizes} commands are given in scaled points.
14912 @xref{Fractional Type Sizes}, for more information.
14914 @item unitwidth @var{n}
14916 Quantities in the font files are given in machine units for fonts whose
14917 point size is @var{n}@tie{}scaled points.
14919 @item prepro @var{program}
14921 Call @var{program} as a preprocessor. Currently, this keyword is used
14922 by @code{groff} with option @option{-Thtml} only.
14924 @item postpro @var{program}
14926 Call @var{program} as a postprocessor. For example, the line
14933 in the file @file{devdvi/DESC} makes @code{groff} call @code{grodvi}
14934 if option @option{-Tdvi} is given (and @option{-Z} isn't used).
14938 This means that the postprocessor can handle the @samp{t} and @samp{u}
14939 intermediate output commands.
14941 @item sizes @var{s1} @var{s2} @dots{} @var{sn} 0
14943 This means that the device has fonts at @var{s1}, @var{s2}, @dots{}
14944 @var{sn} scaled points. The list of sizes must be terminated by@tie{}0
14945 (this is digit zero). Each @var{si} can also be a range of sizes
14946 @var{m}-@var{n}. The list can extend over more than one line.
14948 @item styles @var{S1} @var{S2} @dots{} @var{Sm}
14950 The first @var{m}@tie{}font positions are associated with styles
14951 @var{S1} @dots{} @var{Sm}.
14953 @item fonts @var{n} @var{F1} @var{F2} @var{F3} @dots{} @var{Fn}
14955 Fonts @var{F1} @dots{} @var{Fn} are mounted in the font positions
14956 @var{m}+1, @dots{}, @var{m}+@var{n} where @var{m} is the number of
14957 styles. This command may extend over more than one line. A font name
14958 of@tie{}0 means no font is mounted on the corresponding font position.
14960 @item family @var{fam}
14962 The default font family is @var{fam}.
14964 @item use_charnames_in_special
14965 @kindex use_charnames_in_special
14966 This command indicates that @code{gtroff} should encode special
14967 characters inside special commands. Currently, this is only used
14968 by the @acronym{HTML} output device. @xref{Postprocessor Access}.
14970 @item papersize @var{string} @dots{}
14972 Select a paper size. Valid values for @var{string} are the ISO paper
14973 types @code{A0}-@code{A7}, @code{B0}-@code{B7}, @code{C0}-@code{C7},
14974 @code{D0}-@code{D7}, @code{DL}, and the US paper types @code{letter},
14975 @code{legal}, @code{tabloid}, @code{ledger}, @code{statement},
14976 @code{executive}, @code{com10}, and @code{monarch}. Case is not significant
14977 for @var{string} if it holds predefined paper types. Alternatively,
14978 @var{string} can be a file name (e.g.@: @file{/etc/papersize}); if the file
14979 can be opened, @code{groff} reads the first line and tests for the above
14980 paper sizes. Finally, @var{string} can be a custom paper size in the format
14981 @code{@var{length},@var{width}} (no spaces before and after the comma).
14982 Both @var{length} and @var{width} must have a unit appended; valid values
14983 are @samp{i} for inches, @samp{C} for centimeters, @samp{p} for points, and
14984 @samp{P} for picas. Example: @code{12c,235p}. An argument which starts
14985 with a digit is always treated as a custom paper format. @code{papersize}
14986 sets both the vertical and horizontal dimension of the output medium.
14988 More than one argument can be specified; @code{groff} scans from left to
14989 right and uses the first valid paper specification.
14991 @item pass_filenames
14992 @kindex pass_filenames
14993 Tell @code{gtroff} to emit the name of the source file currently
14994 being processed. This is achieved by the intermediate output command
14995 @samp{F}. Currently, this is only used by the @acronym{HTML} output
14998 @item print @var{program}
15000 Use @var{program} as a spooler program for printing. If omitted,
15001 the @option{-l} and @option{-L} options of @code{groff} are ignored.
15005 This line and everything following in the file are ignored. It is
15006 allowed for the sake of backwards compatibility.
15009 The @code{res}, @code{unitwidth}, @code{fonts}, and @code{sizes} lines
15010 are mandatory. Other commands are ignored by @code{gtroff} but may be
15011 used by postprocessors to store arbitrary information about the device
15012 in the @file{DESC} file.
15016 @kindex biggestfont
15017 Here a list of obsolete keywords which are recognized by @code{groff}
15018 but completely ignored: @code{spare1}, @code{spare2},
15019 @code{biggestfont}.
15021 @c ---------------------------------------------------------------------
15023 @node Font File Format, , DESC File Format, Font Files
15024 @subsection Font File Format
15025 @cindex font file, format
15026 @cindex font description file, format
15027 @cindex format of font files
15028 @cindex format of font description files
15030 A @dfn{font file}, also (and probably better) called a @dfn{font
15031 description file}, has two sections. The first section is a sequence
15032 of lines each containing a sequence of blank delimited words; the first
15033 word in the line is a key, and subsequent words give a value for that
15039 The name of the font is@tie{}@var{f}.
15041 @item spacewidth @var{n}
15043 The normal width of a space is@tie{}@var{n}.
15045 @item slant @var{n}
15047 The glyphs of the font have a slant of @var{n}@tie{}degrees.
15048 (Positive means forward.)
15050 @item ligatures @var{lig1} @var{lig2} @dots{} @var{lign} [0]
15052 Glyphs @var{lig1}, @var{lig2}, @dots{}, @var{lign} are ligatures;
15053 possible ligatures are @samp{ff}, @samp{fi}, @samp{fl}, @samp{ffi} and
15054 @samp{ffl}. For backwards compatibility, the list of ligatures may be
15055 terminated with a@tie{}0. The list of ligatures may not extend over more
15059 @cindex special fonts
15061 The font is @dfn{special}; this means that when a glyph is requested
15062 that is not present in the current font, it is searched for in any
15063 special fonts that are mounted.
15066 Other commands are ignored by @code{gtroff} but may be used by
15067 postprocessors to store arbitrary information about the font in the font
15070 @cindex comments in font files
15071 @cindex font files, comments
15073 The first section can contain comments which start with the @samp{#}
15074 character and extend to the end of a line.
15076 The second section contains one or two subsections. It must contain a
15077 @code{charset} subsection and it may also contain a @code{kernpairs}
15078 subsection. These subsections can appear in any order. Each
15079 subsection starts with a word on a line by itself.
15082 The word @code{charset} starts the character set
15083 subsection.@footnote{This keyword is misnamed since it starts a list
15084 of ordered glyphs, not characters.} The @code{charset} line is
15085 followed by a sequence of lines. Each line gives information for one
15086 glyph. A line comprises a number of fields separated by blanks or
15087 tabs. The format is
15090 @var{name} @var{metrics} @var{type} @var{code}
15091 [@var{entity-name}] [@code{--} @var{comment}]
15094 @cindex 8-bit input
15095 @cindex input, 8-bit
15096 @cindex accessing unnamed glyphs with @code{\N}
15097 @cindex unnamed glyphs, accessing with @code{\N}
15098 @cindex characters, unnamed, accessing with @code{\N}
15099 @cindex glyphs, unnamed, accessing with @code{\N}
15102 @var{name} identifies the glyph name@footnote{The distinction between
15103 input, characters, and output, glyphs, is not clearly separated in the
15104 terminology of @code{groff}; for example, the @code{char} request
15105 should be called @code{glyph} since it defines an output entity.}:
15106 If @var{name} is a single character@tie{}@var{c} then it corresponds
15107 to the @code{gtroff} input character@tie{}@var{c}; if it is of the form
15108 @samp{\@var{c}} where @var{c} is a single character, then it
15109 corresponds to the special character @code{\[@var{c}]}; otherwise it
15110 corresponds to the special character @samp{\[@var{name}]}. If it
15111 is exactly two characters @var{xx} it can be entered as
15112 @samp{\(@var{xx}}. Note that single-letter special characters can't
15113 be accessed as @samp{\@var{c}}; the only exception is @samp{\-} which
15114 is identical to @code{\[-]}.
15116 @code{gtroff} supports 8-bit input characters; however some utilities
15117 have difficulties with eight-bit characters. For this reason, there is
15118 a convention that the entity name @samp{char@var{n}} is equivalent to
15119 the single input character whose code is@tie{}@var{n}. For example,
15120 @samp{char163} would be equivalent to the character with code@tie{}163
15121 which is the pounds sterling sign in the ISO@tie{}@w{Latin-1} character set.
15122 You shouldn't use @samp{char@var{n}} entities in font description files
15123 since they are related to input, not output. Otherwise, you get
15124 hard-coded connections between input and output encoding which
15125 prevents use of different (input) character sets.
15127 The name @samp{---} is special and indicates that the glyph is
15128 unnamed; such glyphs can only be used by means of the @code{\N}
15129 escape sequence in @code{gtroff}.
15131 The @var{type} field gives the glyph type:
15135 the glyph has a descender, for example, @samp{p};
15138 the glyph has an ascender, for example, @samp{b};
15141 the glyph has both an ascender and a descender, for example, @samp{(}.
15144 The @var{code} field gives the code which the postprocessor uses to
15145 print the glyph. The glyph can also be input to @code{gtroff}
15146 using this code by means of the @code{\N} escape sequence. @var{code}
15147 can be any integer. If it starts with @samp{0} it is interpreted as
15148 octal; if it starts with @samp{0x} or @samp{0X} it is interpreted as
15149 hexadecimal. Note, however, that the @code{\N} escape sequence only
15150 accepts a decimal integer.
15152 The @var{entity-name} field gives an @acronym{ASCII} string
15153 identifying the glyph which the postprocessor uses to print the
15154 @code{gtroff} glyph @var{name}. This field is optional and has been
15155 introduced so that the @acronym{HTML} device driver can encode its
15156 character set. For example, the glyph @samp{\[Po]} is
15157 represented as @samp{£} in @acronym{HTML} 4.0.
15159 Anything on the line after the @var{entity-name} field resp.@: after
15160 @samp{--} will be ignored.
15162 The @var{metrics} field has the form:
15166 @var{width}[@code{,}@var{height}[@code{,}@var{depth}[@code{,}@var{italic-correction}
15167 [@code{,}@var{left-italic-correction}[@code{,}@var{subscript-correction}]]]]]
15172 There must not be any spaces between these subfields (it has been split
15173 here into two lines for better legibility only). Missing subfields are
15174 assumed to be@tie{}0. The subfields are all decimal integers. Since
15175 there is no associated binary format, these values are not required to
15176 fit into a variable of type @samp{char} as they are in @code{ditroff}.
15177 The @var{width} subfield gives the width of the glyph. The @var{height}
15178 subfield gives the height of the glyph (upwards is positive); if a
15179 glyph does not extend above the baseline, it should be given a zero
15180 height, rather than a negative height. The @var{depth} subfield gives
15181 the depth of the glyph, that is, the distance from the baseline to the
15182 lowest point below the baseline to which the glyph extends (downwards is
15183 positive); if a glyph does not extend below the baseline, it should be
15184 given a zero depth, rather than a negative depth. The
15185 @var{italic-correction} subfield gives the amount of space that should
15186 be added after the glyph when it is immediately to be followed by a
15187 glyph from a roman font. The @var{left-italic-correction} subfield
15188 gives the amount of space that should be added before the glyph when it
15189 is immediately to be preceded by a glyph from a roman font. The
15190 @var{subscript-correction} gives the amount of space that should be
15191 added after a glyph before adding a subscript. This should be less
15192 than the italic correction.
15194 A line in the @code{charset} section can also have the format
15201 This indicates that @var{name} is just another name for the glyph
15202 mentioned in the preceding line.
15205 The word @code{kernpairs} starts the kernpairs section. This contains a
15206 sequence of lines of the form:
15209 @var{c1} @var{c2} @var{n}
15213 This means that when glyph @var{c1} appears next to glyph @var{c2}
15214 the space between them should be increased by@tie{}@var{n}. Most
15215 entries in the kernpairs section have a negative value for@tie{}@var{n}.
15219 @c =====================================================================
15220 @c =====================================================================
15222 @node Installation, Copying This Manual, File formats, Top
15223 @chapter Installation
15224 @cindex installation
15230 @c =====================================================================
15231 @c =====================================================================
15233 @node Copying This Manual, Request Index, Installation, Top
15234 @appendix Copying This Manual
15237 * GNU Free Documentation License:: License for copying this manual.
15244 @c =====================================================================
15245 @c =====================================================================
15247 @node Request Index, Escape Index, Copying This Manual, Top
15248 @appendix Request Index
15250 Requests appear without the leading control character (normally either
15251 @samp{.} or @samp{'}).
15257 @c =====================================================================
15258 @c =====================================================================
15260 @node Escape Index, Operator Index, Request Index, Top
15261 @appendix Escape Index
15263 Any escape sequence @code{\@var{X}} with @var{X} not in the list below
15264 emits a warning, printing glyph @var{X}.
15270 @c =====================================================================
15271 @c =====================================================================
15273 @node Operator Index, Register Index, Escape Index, Top
15274 @appendix Operator Index
15280 @c =====================================================================
15281 @c =====================================================================
15283 @node Register Index, Macro Index, Operator Index, Top
15284 @appendix Register Index
15286 The macro package or program a specific register belongs to is appended in
15289 A register name@tie{}@code{x} consisting of exactly one character can be
15290 accessed as @samp{\nx}. A register name @code{xx} consisting of exactly
15291 two characters can be accessed as @samp{\n(xx}. Register names @code{xxx}
15292 of any length can be accessed as @samp{\n[xxx]}.
15298 @c =====================================================================
15299 @c =====================================================================
15301 @node Macro Index, String Index, Register Index, Top
15302 @appendix Macro Index
15304 The macro package a specific macro belongs to is appended in brackets.
15305 They appear without the leading control character (normally @samp{.}).
15311 @c =====================================================================
15312 @c =====================================================================
15314 @node String Index, Glyph Name Index, Macro Index, Top
15315 @appendix String Index
15317 The macro package or program a specific string belongs to is appended in
15320 A string name@tie{}@code{x} consisting of exactly one character can be
15321 accessed as @samp{\*x}. A string name @code{xx} consisting of exactly
15322 two characters can be accessed as @samp{\*(xx}. String names @code{xxx}
15323 of any length can be accessed as @samp{\*[xxx]}.
15330 @c =====================================================================
15331 @c =====================================================================
15333 @node Glyph Name Index, Font File Keyword Index, String Index, Top
15334 @appendix Glyph Name Index
15336 A glyph name @code{xx} consisting of exactly two characters can be
15337 accessed as @samp{\(xx}. Glyph names @code{xxx} of any length can be
15338 accessed as @samp{\[xxx]}.
15344 @c =====================================================================
15345 @c =====================================================================
15347 @node Font File Keyword Index, Program and File Index, Glyph Name Index, Top
15348 @appendix Font File Keyword Index
15354 @c =====================================================================
15355 @c =====================================================================
15357 @node Program and File Index, Concept Index, Font File Keyword Index, Top
15358 @appendix Program and File Index
15364 @c =====================================================================
15365 @c =====================================================================
15367 @node Concept Index, , Program and File Index, Top
15368 @appendix Concept Index