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.
5913 @cindex vertical resolution register (@code{.V})
5914 @cindex resolution, vertical, register (@code{.V})
5916 Vertical resolution in basic units.
5919 @cindex seconds, current time (@code{seconds})
5920 @cindex time, current, seconds (@code{seconds})
5921 @cindex current time, seconds (@code{seconds})
5923 The number of seconds after the minute, normally in the range@tie{}0
5924 to@tie{}59, but can be up to@tie{}61 to allow for leap seconds. Initialized
5925 at start-up of @code{gtroff}.
5928 @cindex minutes, current time (@code{minutes})
5929 @cindex time, current, minutes (@code{minutes})
5930 @cindex current time, minutes (@code{minutes})
5932 The number of minutes after the hour, in the range@tie{}0 to@tie{}59.
5933 Initialized at start-up of @code{gtroff}.
5936 @cindex hours, current time (@code{hours})
5937 @cindex time, current, hours (@code{hours})
5938 @cindex current time, hours (@code{hours})
5940 The number of hours past midnight, in the range@tie{}0 to@tie{}23.
5941 Initialized at start-up of @code{gtroff}.
5944 @cindex day of the week register (@code{dw})
5945 @cindex date, day of the week register (@code{dw})
5947 Day of the week (1-7).
5950 @cindex day of the month register (@code{dy})
5951 @cindex date, day of the month register (@code{dy})
5953 Day of the month (1-31).
5956 @cindex month of the year register (@code{mo})
5957 @cindex date, month of the year register (@code{mo})
5959 Current month (1-12).
5962 @cindex date, year register (@code{year}, @code{yr})
5963 @cindex year, current, register (@code{year}, @code{yr})
5969 The current year minus@tie{}1900. Unfortunately, the documentation of
5970 @acronym{UNIX} Version@tie{}7's @code{troff} had a year@tie{}2000 bug: It
5971 incorrectly claimed that @code{yr} contains the last two digits of the
5972 year. That claim has never been true of either @acronym{AT&T}
5973 @code{troff} or GNU @code{troff}. Old @code{troff} input that looks
5977 '\" The following line stopped working after 1999
5978 This document was formatted in 19\n(yr.
5982 can be corrected as follows:
5985 This document was formatted in \n[year].
5989 or, to be portable to older @code{troff} versions, as follows:
5993 This document was formatted in \n(y4.
6000 @cindex input line number register (@code{.c}, @code{c.})
6001 @cindex line number, input, register (@code{.c}, @code{c.})
6002 The current @emph{input} line number. Register @samp{.c} is read-only,
6003 whereas @samp{c.} (a @code{gtroff} extension) is writable also,
6004 affecting both @samp{.c} and @samp{c.}.
6008 @cindex output line number register (@code{ln})
6009 @cindex line number, output, register (@code{ln})
6010 The current @emph{output} line number after a call to the @code{nm}
6011 request to activate line numbering.
6013 @xref{Miscellaneous}, for more information about line numbering.
6017 @cindex major version number register (@code{.x})
6018 @cindex version number, major, register (@code{.x})
6019 The major version number. For example, if the version number
6020 is 1.03 then @code{.x} contains@tie{}@samp{1}.
6024 @cindex minor version number register (@code{.y})
6025 @cindex version number, minor, register (@code{.y})
6026 The minor version number. For example, if the version number
6027 is 1.03 then @code{.y} contains@tie{}@samp{03}.
6031 @cindex revision number register (@code{.Y})
6032 The revision number of @code{groff}.
6036 @cindex process ID of @code{gtroff} register (@code{$$})
6037 @cindex @code{gtroff}, process ID register (@code{$$})
6038 The process ID of @code{gtroff}.
6042 @cindex @code{gtroff}, identification register (@code{.g})
6043 @cindex GNU-specific register (@code{.g})
6044 Always@tie{}1. Macros should use this to determine whether they are
6045 running under GNU @code{troff}.
6049 @cindex @acronym{ASCII} approximation output register (@code{.A})
6050 If the command line option @option{-a} is used to produce an
6051 @acronym{ASCII} approximation of the output, this is set to@tie{}1, zero
6052 otherwise. @xref{Groff Options}.
6056 This register is set to@tie{}1 (and to@tie{}0 otherwise) if the current
6057 page is actually being printed, i.e., if the @option{-o} option is being
6058 used to only print selected pages. @xref{Groff Options}, for more
6063 If @code{gtroff} is called with the @option{-T} command line option, the
6064 number register @code{.T} is set to@tie{}1, and zero otherwise.
6065 @xref{Groff Options}.
6069 @cindex output device name string register (@code{.T})
6070 A single read-write string register which contains the current output
6071 device (for example, @samp{latin1} or @samp{ps}). This is the only
6072 string register defined by @code{gtroff}.
6076 @c =====================================================================
6078 @node Manipulating Filling and Adjusting, Manipulating Hyphenation, Registers, gtroff Reference
6079 @section Manipulating Filling and Adjusting
6080 @cindex manipulating filling and adjusting
6081 @cindex filling and adjusting, manipulating
6082 @cindex adjusting and filling, manipulating
6083 @cindex justifying text
6084 @cindex text, justifying
6088 @cindex @code{bp} request, causing implicit linebreak
6089 @cindex @code{ce} request, causing implicit linebreak
6090 @cindex @code{cf} request, causing implicit linebreak
6091 @cindex @code{fi} request, causing implicit linebreak
6092 @cindex @code{fl} request, causing implicit linebreak
6093 @cindex @code{in} request, causing implicit linebreak
6094 @cindex @code{nf} request, causing implicit linebreak
6095 @cindex @code{rj} request, causing implicit linebreak
6096 @cindex @code{sp} request, causing implicit linebreak
6097 @cindex @code{ti} request, causing implicit linebreak
6098 @cindex @code{trf} request, causing implicit linebreak
6099 Various ways of causing @dfn{breaks} were given in @ref{Implicit Line
6100 Breaks}. The @code{br} request likewise causes a break. Several
6101 other requests also cause breaks, but implicitly. These are
6102 @code{bp}, @code{ce}, @code{cf}, @code{fi}, @code{fl}, @code{in},
6103 @code{nf}, @code{rj}, @code{sp}, @code{ti}, and @code{trf}.
6106 Break the current line, i.e., the input collected so far is emitted
6109 If the no-break control character is used, @code{gtroff} suppresses
6120 Initially, @code{gtroff} fills and adjusts text to both margins.
6121 Filling can be disabled via the @code{nf} request and re-enabled with
6122 the @code{fi} request.
6126 @cindex fill mode (@code{fi})
6127 @cindex mode, fill (@code{fi})
6128 Activate fill mode (which is the default). This request implicitly
6129 enables adjusting; it also inserts a break in the text currently being
6130 filled. The read-only number register @code{.u} is set to@tie{}1.
6132 The fill mode status is associated with the current environment
6133 (@pxref{Environments}).
6135 See @ref{Line Control}, for interaction with the @code{\c} escape.
6139 @cindex no-fill mode (@code{nf})
6140 @cindex mode, no-fill (@code{nf})
6141 Activate no-fill mode. Input lines are output as-is, retaining line
6142 breaks and ignoring the current line length. This command implicitly
6143 disables adjusting; it also causes a break. The number register
6144 @code{.u} is set to@tie{}0.
6146 The fill mode status is associated with the current environment
6147 (@pxref{Environments}).
6149 See @ref{Line Control}, for interaction with the @code{\c} escape.
6152 @DefreqList {ad, [@Var{mode}]}
6156 Activation and deactivation of adjusting is done implicitly with
6157 calls to the @code{fi} or @code{nf} requests.
6159 @var{mode} can have one of the following values:
6163 @cindex ragged-right
6164 Adjust text to the left margin. This produces what is traditionally
6165 called ragged-right text.
6169 Adjust text to the right margin, producing ragged-left text.
6172 @cindex centered text
6173 @cindex @code{ce} request, difference to @samp{.ad@tie{}c}
6174 Center filled text. This is different to the @code{ce} request which
6175 only centers text without filling.
6179 Justify to both margins. This is the default used by @code{gtroff}.
6182 Finally, @var{mode} can be the numeric argument returned by the @code{.j}
6185 With no argument, @code{gtroff} adjusts lines in the same way it did
6186 before adjusting was deactivated (with a call to @code{na}, for
6198 .ad \" back to centering
6200 .ad \n[ad] \" back to right justifying
6203 @cindex adjustment mode register (@code{.j})
6204 The current adjustment mode is available in the read-only number
6205 register @code{.j}; it can be stored and subsequently used to set
6208 The adjustment mode status is associated with the current environment
6209 (@pxref{Environments}).
6213 Disable adjusting. This request won't change the current adjustment
6214 mode: A subsequent call to @code{ad} uses the previous adjustment
6217 The adjustment mode status is associated with the current environment
6218 (@pxref{Environments}).
6222 @DefescListEnd {\\p, , , }
6223 Adjust the current line and cause a break.
6225 In most cases this produces very ugly results since @code{gtroff}
6226 doesn't have a sophisticated paragraph building algorithm (as @TeX{}
6227 have, for example); instead, @code{gtroff} fills and adjusts a paragraph
6231 This is an uninteresting sentence.
6232 This is an uninteresting sentence.\p
6233 This is an uninteresting sentence.
6240 This is an uninteresting sentence. This is an
6241 uninteresting sentence.
6242 This is an uninteresting sentence.
6246 @DefreqList {ss, word_space_size [@Var{sentence_space_size}]}
6248 @DefregListEnd {.sss}
6249 @cindex word space size register (@code{.ss})
6250 @cindex size of word space register (@code{.ss})
6251 @cindex space between words register (@code{.ss})
6252 @cindex sentence space size register (@code{.sss})
6253 @cindex size of sentence space register (@code{.sss})
6254 @cindex space between sentences register (@code{.sss})
6255 Change the size of a space between words. It takes its units as one
6256 twelfth of the space width parameter for the current font.
6257 Initially both the @var{word_space_size} and @var{sentence_space_size}
6258 are@tie{}12. In fill mode, the values specify the minimum distance.
6262 If two arguments are given to the @code{ss} request, the second
6263 argument sets the sentence space size. If the second argument is not
6264 given, sentence space size is set to @var{word_space_size}. The
6265 sentence space size is used in two circumstances: If the end of a
6266 sentence occurs at the end of a line in fill mode, then both an
6267 inter-word space and a sentence space are added; if two spaces follow
6268 the end of a sentence in the middle of a line, then the second space
6269 is a sentence space. If a second argument is never given to the
6270 @code{ss} request, the behaviour of @acronym{UNIX} @code{troff} is the
6271 same as that exhibited by GNU @code{troff}. In GNU @code{troff}, as
6272 in @acronym{UNIX} @code{troff}, a sentence should always be followed
6273 by either a newline or two spaces.
6275 The read-only number registers @code{.ss} and @code{.sss} hold the
6276 values of the parameters set by the first and second arguments of the
6279 The word space and sentence space values are associated with the current
6280 environment (@pxref{Environments}).
6282 Contrary to @acronym{AT&T} @code{troff}, this request is @emph{not}
6283 ignored if a TTY output device is used; the given values are then
6284 rounded down to a multiple of@tie{}12 (@pxref{Implementation Differences}).
6286 The request is ignored if there is no parameter.
6288 @cindex discardable horizontal space
6289 @cindex space, discardable, horizontal
6290 @cindex horizontal discardable space
6291 Another useful application of the @code{ss} request is to insert
6292 discardable horizontal space, i.e., space which is discarded at a line
6293 break. For example, paragraph-style footnotes could be separated this
6298 1.\ This is the first footnote.\c
6302 2.\ This is the second footnote.
6309 1. This is the first footnote. 2. This
6310 is the second footnote.
6314 Note that the @code{\h} escape produces unbreakable space.
6317 @DefreqList {ce, [@Var{nnn}]}
6318 @DefregListEnd {.ce}
6319 @cindex centering lines (@code{ce})
6320 @cindex lines, centering (@code{ce})
6321 Center text. While the @w{@samp{.ad c}} request also centers text,
6322 it fills the text as well. @code{ce} does not fill the
6323 text it affects. This request causes a break. The number of lines
6324 still to be centered is associated with the current environment
6325 (@pxref{Environments}).
6327 The following example demonstrates the differences.
6333 This is a small text fragment which shows the differences
6334 between the `.ce' and the `.ad c' request.
6338 This is a small text fragment which shows the differences
6339 between the `.ce' and the `.ad c' request.
6343 And here the result:
6346 This is a small text fragment which
6347 shows the differences
6348 between the `.ce' and the `.ad c' request.
6350 This is a small text fragment which
6351 shows the differences between the `.ce'
6352 and the `.ad c' request.
6355 With no arguments, @code{ce} centers the next line of text. @var{nnn}
6356 specifies the number of lines to be centered. If the argument is zero
6357 or negative, centering is disabled.
6359 The basic length for centering text is the line length (as set with the
6360 @code{ll} request) minus the indentation (as set with the @code{in}
6361 request). Temporary indentation is ignored.
6363 As can be seen in the previous example, it is a common idiom to turn
6364 on centering for a large number of lines, and to turn off centering
6365 after text to be centered. This is useful for any request which takes
6366 a number of lines as an argument.
6368 The @code{.ce} read-only number register contains the number of lines
6369 remaining to be centered, as set by the @code{ce} request.
6372 @DefreqList {rj, [@Var{nnn}]}
6373 @DefregListEnd {.rj}
6374 @cindex justifying text (@code{rj})
6375 @cindex text, justifying (@code{rj})
6376 @cindex right-justifying (@code{rj})
6377 Justify unfilled text to the right margin. Arguments are identical to
6378 the @code{ce} request. The @code{.rj} read-only number register is
6379 the number of lines to be right-justified as set by the @code{rj}
6380 request. This request causes a break. The number of lines still to be
6381 right-justified is associated with the current environment
6382 (@pxref{Environments}).
6386 @c =====================================================================
6388 @node Manipulating Hyphenation, Manipulating Spacing, Manipulating Filling and Adjusting, gtroff Reference
6389 @section Manipulating Hyphenation
6390 @cindex manipulating hyphenation
6391 @cindex hyphenation, manipulating
6393 As discussed in @ref{Hyphenation}, @code{gtroff} hyphenates words.
6394 There are a number of ways to influence hyphenation.
6396 @DefreqList {hy, [@Var{mode}]}
6397 @DefregListEnd {.hy}
6398 Enable hyphenation. The request has an optional numeric argument,
6399 @var{mode}, to restrict hyphenation if necessary:
6403 The default argument if @var{mode} is omitted. Hyphenate without
6404 restrictions. This is also the start-up value of @code{gtroff}.
6407 Do not hyphenate the last word on a page or column.
6410 Do not hyphenate the last two characters of a word.
6413 Do not hyphenate the first two characters of a word.
6416 Values in the previous table are additive. For example, the
6417 value@tie{}12 causes @code{gtroff} to neither hyphenate the last
6418 two nor the first two characters of a word.
6420 @cindex hyphenation restrictions register (@code{.hy})
6421 The current hyphenation restrictions can be found in the read-only
6422 number register @samp{.hy}.
6424 The hyphenation mode is associated with the current environment
6425 (@pxref{Environments}).
6429 Disable hyphenation (i.e., set the hyphenation mode to zero). Note
6430 that the hyphenation mode of the last call to @code{hy} is not
6433 The hyphenation mode is associated with the current environment
6434 (@pxref{Environments}).
6437 @DefreqList {hlm, [@Var{nnn}]}
6439 @DefregListEnd {.hlc}
6440 @cindex explicit hyphen (@code{\%})
6441 @cindex hyphen, explicit (@code{\%})
6442 @cindex consecutive hyphenated lines (@code{hlm})
6443 @cindex lines, consecutive hyphenated (@code{hlm})
6444 @cindex hyphenated lines, consecutive (@code{hlm})
6445 Set the maximum number of consecutive hyphenated lines to @var{nnn}.
6446 If this number is negative, there is no maximum. The default value
6447 is@tie{}@minus{}1 if @var{nnn} is omitted. This value is associated
6448 with the current environment (@pxref{Environments}). Only lines
6449 output from a given environment count towards the maximum associated
6450 with that environment. Hyphens resulting from @code{\%} are counted;
6451 explicit hyphens are not.
6453 The current setting of @code{hlm} is available in the @code{.hlm}
6454 read-only number register. Also the number of immediately preceding
6455 consecutive hyphenated lines are available in the read-only number
6456 register @samp{.hlc}.
6459 @Defreq {hw, word1 word2 @dots{}}
6460 Define how @var{word1}, @var{word2}, etc.@: are to be hyphenated. The
6461 words must be given with hyphens at the hyphenation points. For
6469 Besides the space character, any character whose hyphenation code value
6470 is zero can be used to separate the arguments of @code{hw} (see the
6471 documentation for the @code{hcode} request below for more information).
6472 In addition, this request can be used more than once.
6474 Hyphenation exceptions specified with the @code{hw} request are
6475 associated with the current hyphenation language; it causes an error
6476 if there is no current hyphenation language.
6478 This request is ignored if there is no parameter.
6480 In old versions of @code{troff} there was a limited amount of space to
6481 store such information; fortunately, with @code{gtroff}, this is no
6482 longer a restriction.
6485 @DefescList {\\%, , , }
6486 @deffnx Escape @t{\:}
6491 @esindex \@r{<colon>}
6493 @cindex hyphenation character (@code{\%})
6494 @cindex character, hyphenation (@code{\%})
6495 @cindex disabling hyphenation (@code{\%})
6496 @cindex hyphenation, disabling (@code{\%})
6497 To tell @code{gtroff} how to hyphenate words on the fly, use the
6498 @code{\%} escape, also known as the @dfn{hyphenation character}.
6499 Preceding a word with this character prevents it from being
6500 hyphenated; putting it inside a word indicates to @code{gtroff} that
6501 the word may be hyphenated at that point. Note that this mechanism
6502 only affects that one occurrence of the word; to change the
6503 hyphenation of a word for the entire document, use the @code{hw}
6506 The @code{\:} escape inserts a zero-width break point
6507 (that is, the word breaks but without adding a hyphen).
6510 ... check the /var/log/\:httpd/\:access_log file ...
6513 @cindex @code{\X}, followed by @code{\%}
6514 @cindex @code{\Y}, followed by @code{\%}
6515 @cindex @code{\%}, following @code{\X} or @code{\Y}
6516 Note that @code{\X} and @code{\Y} start a word, that is, the @code{\%}
6517 escape in (say) @w{@samp{\X'...'\%foobar}} and
6518 @w{@samp{\Y'...'\%foobar}} no longer prevents hyphenation but inserts
6519 a hyphenation point at the beginning of @samp{foobar}; most likely
6520 this isn't what you want to do.
6523 @Defreq {hc, [@Var{char}]}
6524 Change the hyphenation character to @var{char}. This character then
6525 works the same as the @code{\%} escape, and thus, no longer appears in
6526 the output. Without an argument, @code{hc} resets the hyphenation
6527 character to be @code{\%} (the default) only.
6529 The hyphenation character is associated with the current environment
6530 (@pxref{Environments}).
6533 @DefreqList {hpf, pattern_file}
6534 @DefreqItem {hpfa, pattern_file}
6535 @DefreqListEnd {hpfcode, a b [c d @dots{}]}
6536 @cindex hyphenation patterns (@code{hpf})
6537 @cindex patterns for hyphenation (@code{hpf})
6538 Read in a file of hyphenation patterns. This file is searched for in
6539 the same way as @file{@var{name}.tmac} (or @file{tmac.@var{name}}) is
6540 searched for if the @option{-m@var{name}} option is specified.
6542 It should have the same format as (simple) @TeX{} patterns files.
6543 More specifically, the following scanning rules are implemented.
6547 A percent sign starts a comment (up to the end of the line)
6548 even if preceded by a backslash.
6551 No support for `digraphs' like @code{\$}.
6554 @code{^^@var{xx}} (@var{x} is 0-9 or a-f) and @code{^^@var{x}} (character
6555 code of @var{x} in the range 0-127) are recognized; other use of @code{^}
6562 @code{hpf} checks for the expression @code{\patterns@{@dots{}@}}
6563 (possibly with whitespace before and after the braces).
6564 Everything between the braces is taken as hyphenation patterns.
6565 Consequently, @code{@{} and @code{@}} are not allowed in patterns.
6568 Similarly, @code{\hyphenation@{@dots{}@}} gives a list of hyphenation
6572 @code{\endinput} is recognized also.
6575 For backwards compatibility, if @code{\patterns} is missing,
6576 the whole file is treated as a list of hyphenation patterns
6577 (only recognizing the @code{%} character as the start of a comment).
6580 If no @code{hpf} request is specified (either in the document or in a
6581 macro package), @code{gtroff} won't hyphenate at all.
6583 The @code{hpfa} request appends a file of patterns to the current list.
6585 The @code{hpfcode} request defines mapping values for character codes in
6586 hyphenation patterns. @code{hpf} or @code{hpfa} then apply the mapping
6587 (after reading the patterns) before replacing or appending them to
6588 the current list of patterns. Its arguments are pairs of character codes
6589 -- integers from 0 to@tie{}255. The request maps character code@tie{}@var{a}
6590 to code@tie{}@var{b}, code@tie{}@var{c} to code@tie{}@var{d}, and so on. You
6591 can use character codes which would be invalid otherwise.
6597 The set of hyphenation patterns is associated with the current language
6598 set by the @code{hla} request. The @code{hpf} request is usually
6599 invoked by the @file{troffrc} or @file{troffrc-end} file; by default,
6600 @file{troffrc} loads hyphenation patterns and exceptions for American
6601 English (in files @file{hyphen.us} and @file{hyphenex.us}).
6603 A second call to @code{hpf} (for the same language) will replace the
6604 hyphenation patterns with the new ones.
6606 Invoking @code{hpf} causes an error if there is no current hyphenation
6610 @Defreq {hcode, c1 code1 c2 code2 @dots{}}
6611 @cindex hyphenation code (@code{hcode})
6612 @cindex code, hyphenation (@code{hcode})
6613 Set the hyphenation code of character @var{c1} to @var{code1}, that of
6614 @var{c2} to @var{code2}, etc. A hyphenation code must be a single
6615 input character (not a special character) other than a digit or a
6616 space. Initially each lower-case letter (@samp{a}-@samp{z}) has its
6617 hyphenation code set to itself, and each upper-case letter
6618 (@samp{A}-@samp{Z}) has a hyphenation code which is the lower-case
6621 This request is ignored if it has no parameter.
6624 @DefreqList {hym, [@Var{length}]}
6625 @DefregListEnd {.hym}
6626 @cindex hyphenation margin (@code{hym})
6627 @cindex margin for hyphenation (@code{hym})
6628 @cindex @code{ad} request, and hyphenation margin
6629 Set the (right) hyphenation margin to @var{length}. If the current
6630 adjustment mode is not @samp{b} or @samp{n}, the line is not
6631 hyphenated if it is shorter than @var{length}. Without an argument,
6632 the hyphenation margin is reset to its default value, which is@tie{}0.
6633 The default scaling indicator for this request is @samp{m}. The
6634 hyphenation margin is associated with the current environment
6635 (@pxref{Environments}).
6637 A negative argument resets the hyphenation margin to zero, emitting
6638 a warning of type @samp{range}.
6640 @cindex hyphenation margin register (@code{.hym})
6641 The current hyphenation margin is available in the @code{.hym} read-only
6645 @DefreqList {hys, [@Var{hyphenation_space}]}
6646 @DefregListEnd {.hys}
6647 @cindex hyphenation space (@code{hys})
6648 @cindex @code{ad} request, and hyphenation space
6649 Set the hyphenation space to @var{hyphenation_space}. If the current
6650 adjustment mode is @samp{b} or @samp{n}, don't hyphenate the line
6651 if it can be justified by adding no more than @var{hyphenation_space}
6652 extra space to each word space. Without argument, the hyphenation
6653 space is set to its default value, which is@tie{}0. The default
6654 scaling indicator for this request is @samp{m}. The hyphenation
6655 space is associated with the current environment
6656 (@pxref{Environments}).
6658 A negative argument resets the hyphenation space to zero, emitting a
6659 warning of type @samp{range}.
6661 @cindex hyphenation space register (@code{.hys})
6662 The current hyphenation space is available in the @code{.hys} read-only
6666 @Defreq {shc, [@Var{glyph}]}
6667 @cindex soft hyphen character, setting (@code{shc})
6668 @cindex character, soft hyphen, setting (@code{shc})
6669 @cindex glyph, soft hyphen (@code{hy})
6670 @cindex soft hyphen glyph (@code{hy})
6671 @cindex @code{char} request, and soft hyphen character
6672 @cindex @code{tr} request, and soft hyphen character
6673 Set the @dfn{soft hyphen character} to @var{glyph}.@footnote{@dfn{Soft
6674 hyphen character} is a misnomer since it is an output glyph.} If the
6675 argument is omitted, the soft hyphen character is set to the default
6676 glyph @code{\(hy} (this is the start-up value of @code{gtroff} also).
6677 The soft hyphen character is the glyph that is inserted when a word is
6678 hyphenated at a line break. If the soft hyphen character does not
6679 exist in the font of the character immediately preceding a potential
6680 break point, then the line is not broken at that point. Neither
6681 definitions (specified with the @code{char} request) nor translations
6682 (specified with the @code{tr} request) are considered when finding the
6683 soft hyphen character.
6686 @DefreqList {hla, language}
6687 @DefregListEnd {.hla}
6688 @cindex @code{hpf} request, and hyphenation language
6689 @cindex @code{hw} request, and hyphenation language
6692 Set the current hyphenation language to the string @var{language}.
6693 Hyphenation exceptions specified with the @code{hw} request and
6694 hyphenation patterns specified with the @code{hpf} and @code{hpfa}
6695 requests are both associated with the current hyphenation language.
6696 The @code{hla} request is usually invoked by the @file{troffrc} or the
6697 @file{troffrc-end} files; @file{troffrc} sets the default language to
6700 @cindex hyphenation language register (@code{.hla})
6701 The current hyphenation language is available as a string in the
6702 read-only number register @samp{.hla}.
6705 .ds curr_language \n[.hla]
6712 @c =====================================================================
6714 @node Manipulating Spacing, Tabs and Fields, Manipulating Hyphenation, gtroff Reference
6715 @section Manipulating Spacing
6716 @cindex manipulating spacing
6717 @cindex spacing, manipulating
6719 @Defreq {sp, [@Var{distance}]}
6720 Space downwards @var{distance}. With no argument it advances
6721 1@tie{}line. A negative argument causes @code{gtroff} to move up the page
6722 the specified distance. If the argument is preceded by a @samp{|}
6723 then @code{gtroff} moves that distance from the top of the page. This
6724 request causes a line break. The default scaling indicator is @samp{v}.
6726 If a vertical trap is sprung during execution of @code{sp}, the amount of
6727 vertical space after the trap is discarded. For example, this
6755 @cindex @code{sp} request, and traps
6756 @cindex discarded space in traps
6757 @cindex space, discarded, in traps
6758 @cindex traps, and discarded space
6759 The amount of discarded space is available in the number register
6762 To protect @code{sp} against vertical traps, use the @code{vpt} request:
6771 @DefreqList {ls, [@Var{nnn}]}
6773 @cindex double-spacing (@code{ls})
6774 Output @w{@var{nnn}@minus{}1} blank lines after each line of text.
6775 With no argument, @code{gtroff} uses the previous value before the
6776 last @code{ls} call.
6779 .ls 2 \" This causes double-spaced output
6780 .ls 3 \" This causes triple-spaced output
6781 .ls \" Again double-spaced
6784 The line spacing is associated with the current environment
6785 (@pxref{Environments}).
6787 @cindex line spacing register (@code{.L})
6788 The read-only number register @code{.L} contains the current line
6792 @xref{Changing Type Sizes}, for the requests @code{vs} and @code{pvs}
6793 as alternatives to @code{ls}.
6795 @DefescList {\\x, ', spacing, '}
6797 Sometimes, extra vertical spacing is only needed occasionally, e.g.@:
6798 to allow space for a tall construct (like an equation). The @code{\x}
6799 escape does this. The escape is given a numerical argument, usually
6800 enclosed in quotes (like @samp{\x'3p'}); the default scaling indicator
6801 is @samp{v}. If this number is positive extra vertical space is
6802 inserted below the current line. A negative number adds space above.
6803 If this escape is used multiple times on the same line, the maximum of
6806 @xref{Escapes}, for details on parameter delimiting characters.
6808 @cindex extra post-vertical line space register (@code{.a})
6809 The @code{.a} read-only number register contains the most recent
6810 (nonnegative) extra vertical line space.
6812 Using @code{\x} can be necessary in combination with the @code{\b}
6813 escape, as the following example shows.
6816 This is a test with the \[rs]b escape.
6818 This is a test with the \[rs]b escape.
6820 This is a test with \b'xyz'\x'-1m'\x'1m'.
6822 This is a test with the \[rs]b escape.
6824 This is a test with the \[rs]b escape.
6831 This is a test with the \b escape.
6832 This is a test with the \b escape.
6834 This is a test with y.
6836 This is a test with the \b escape.
6837 This is a test with the \b escape.
6843 @DefregListEnd {.ns}
6844 @cindex @code{sp} request, and no-space mode
6845 @cindex no-space mode (@code{ns})
6846 @cindex mode, no-space (@code{ns})
6847 @cindex blank lines, disabling
6848 @cindex lines, blank, disabling
6849 Enable @dfn{no-space mode}. In this mode, spacing (either via
6850 @code{sp} or via blank lines) is disabled. The @code{bp} request to
6851 advance to the next page is also disabled, except if it is accompanied
6852 by a page number (see @ref{Page Control}, for more information). This
6853 mode ends when actual text is output or the @code{rs} request is
6854 encountered which ends no-space mode. The read-only number register
6855 @code{.ns} is set to@tie{}1 as long as no-space mode is active.
6857 This request is useful for macros that conditionally
6858 insert vertical space before the text starts
6859 (for example, a paragraph macro could insert some space
6860 except when it is the first paragraph after a section header).
6864 @c =====================================================================
6866 @node Tabs and Fields, Character Translations, Manipulating Spacing, gtroff Reference
6867 @section Tabs and Fields
6868 @cindex tabs, and fields
6869 @cindex fields, and tabs
6871 @cindex @acronym{EBCDIC} encoding of a tab
6872 A tab character (@acronym{ASCII} char@tie{}9, @acronym{EBCDIC}
6873 char@tie{}5) causes a horizontal movement to the next tab stop (much
6874 like it did on a typewriter).
6877 @cindex tab character, non-interpreted (@code{\t})
6878 @cindex character, tab, non-interpreted (@code{\t})
6879 This escape is a non-interpreted tab character. In copy mode
6880 (@pxref{Copy-in Mode}), @code{\t} is the same as a real tab character.
6883 @DefreqList {ta, [@Var{n1} @Var{n2} @dots{} @Var{nn} @t{T} @Var{r1} @Var{r2} @dots{} @Var{rn}]}
6884 @DefregListEnd {.tabs}
6885 Change tab stop positions. This request takes a series of tab
6886 specifiers as arguments (optionally divided into two groups with the
6887 letter @samp{T}) which indicate where each tab stop is to be
6888 (overriding any previous settings).
6890 Tab stops can be specified absolutely, i.e., as the distance from the
6891 left margin. For example, the following sets 6@tie{}tab stops every
6895 .ta 1i 2i 3i 4i 5i 6i
6898 Tab stops can also be specified using a leading @samp{+}
6899 which means that the specified tab stop is set relative to
6900 the previous tab stop. For example, the following is equivalent to the
6904 .ta 1i +1i +1i +1i +1i +1i
6907 @code{gtroff} supports an extended syntax to specify repeat values after
6908 the @samp{T} mark (these values are always taken as relative) -- this is
6909 the usual way to specify tabs set at equal intervals. The following is,
6910 yet again, the same as the previous examples. It does even more since
6911 it defines an infinite number of tab stops separated by one inch.
6917 Now we are ready to interpret the full syntax given at the beginning:
6918 Set tabs at positions @var{n1}, @var{n2}, @dots{}, @var{nn} and then set
6919 tabs at @var{nn}+@var{r1}, @var{nn}+@var{r2}, @dots{}, @var{nn}+@var{rn}
6920 and then at @var{nn}+@var{rn}+@var{r1}, @var{nn}+@var{rn}+@var{r2},
6921 @dots{}, @var{nn}+@var{rn}+@var{rn}, and so on.
6923 Example: @samp{4c +6c T 3c 5c 2c} is equivalent to @samp{4c 10c 13c 18c
6924 20c 23c 28c 30c @dots{}}.
6926 The material in each tab column (i.e., the column between two tab stops)
6927 may be justified to the right or left or centered in the column. This
6928 is specified by appending @samp{R}, @samp{L}, or @samp{C} to the tab
6929 specifier. The default justification is @samp{L}. Example:
6939 The default unit of the @code{ta} request is @samp{m}.
6942 A tab stop is converted into a non-breakable horizontal movement which
6943 can be neither stretched nor squeezed. For example,
6952 creates a single line which is a bit longer than 10@tie{}inches (a string
6953 is used to show exactly where the tab characters are). Now consider the
6963 @code{gtroff} first converts the tab stops of the line into unbreakable
6964 horizontal movements, then splits the line after the second @samp{b}
6965 (assuming a sufficiently short line length). Usually, this isn't what
6969 Superfluous tabs (i.e., tab characters which do not correspond to a tab
6970 stop) are ignored except the first one which delimits the characters
6971 belonging to the last tab stop for right-justifying or centering.
6972 Consider the following example
6976 .ds ZZ foo\tbar\tfoobar
6977 .ds ZZZ foo\tbar\tfoo\tbar
6988 which produces the following output:
6997 The first line right-justifies the second `foo' relative to the tab
6998 stop. The second line right-justifies `foobar'. The third line finally
6999 right-justifies only `foo' because of the additional tab character which
7000 marks the end of the string belonging to the last defined tab stop.
7003 Tab stops are associated with the current environment
7004 (@pxref{Environments}).
7007 Calling @code{ta} without an argument removes all tab stops.
7010 @cindex tab stops, for TTY output devices
7011 The start-up value of @code{gtroff} is @w{@samp{T 0.8i}}.
7014 @cindex tab settings register (@code{.tabs})
7015 The read-only number register @code{.tabs} contains a string
7016 representation of the current tab settings suitable for use as an
7017 argument to the @code{ta} request.
7020 .ds tab-string \n[.tabs]
7025 @cindex @code{.S} register, Plan@tie{}9 alias for @code{.tabs}
7026 @cindex @code{.tabs} register, Plan@tie{}9 alias (@code{.S})
7027 The @code{troff} version of the Plan@tie{}9 operating system uses
7028 register @code{.S} for the same purpose.
7031 @Defreq {tc, [@Var{fill-glyph}]}
7032 @cindex tab repetition character (@code{tc})
7033 @cindex character, tab repetition (@code{tc})
7034 @cindex glyph, tab repetition (@code{tc})
7035 Normally @code{gtroff} fills the space to the next tab stop with
7036 whitespace. This can be changed with the @code{tc} request. With no
7037 argument @code{gtroff} reverts to using whitespace, which is the
7038 default. The value of this @dfn{tab repetition character} is
7039 associated with the current environment
7040 (@pxref{Environments}).@footnote{@dfn{Tab repetition character} is a
7041 misnomer since it is an output glyph.}
7044 @DefreqList {linetabs, n}
7045 @DefregListEnd {.linetabs}
7046 @cindex tab, line-tabs mode
7047 @cindex line-tabs mode
7048 @cindex mode, line-tabs
7049 If @var{n} is missing or not zero, enable @dfn{line-tabs} mode,
7050 or disable it otherwise (the default).
7051 In line-tabs mode, @code{gtroff} computes tab distances
7052 relative to the (current) output line instead of the input line.
7054 For example, the following code:
7067 in normal mode, results in the output
7074 in line-tabs mode, the same code outputs
7080 Line-tabs mode is associated with the current environment.
7081 The read-only register @code{.linetabs} is set to@tie{}1 if in line-tabs
7082 mode, and 0 in normal mode.
7090 @c ---------------------------------------------------------------------
7092 @node Leaders, Fields, Tabs and Fields, Tabs and Fields
7096 Sometimes it may may be desirable to use the @code{tc} request to fill a
7097 particular tab stop with a given glyph (for example dots in a table
7098 of contents), but also normal tab stops on the rest of the line. For
7099 this @code{gtroff} provides an alternate tab mechanism, called
7100 @dfn{leaders} which does just that.
7102 @cindex leader character
7103 A leader character (character code@tie{}1) behaves similarly to a tab
7104 character: It moves to the next tab stop. The only difference is that
7105 for this movement, the fill glyph defaults to a period character and
7109 @cindex leader character, non-interpreted (@code{\a})
7110 @cindex character, leader, non-interpreted (@code{\a})
7111 This escape is a non-interpreted leader character. In copy mode
7112 (@pxref{Copy-in Mode}), @code{\a} is the same as a real leader
7116 @Defreq {lc, [@Var{fill-glyph}]}
7117 @cindex leader repetition character (@code{lc})
7118 @cindex character, leader repetition (@code{lc})
7119 @cindex glyph, leader repetition (@code{lc})
7120 Declare the @dfn{leader repetition character}.@footnote{@dfn{Leader
7121 repetition character} is a misnomer since it is an output glyph.}
7122 Without an argument, leaders act the same as tabs (i.e., using
7123 whitespace for filling). @code{gtroff}'s start-up value is a dot
7124 (@samp{.}). The value of the leader repetition character is
7125 associated with the current environment (@pxref{Environments}).
7128 @cindex table of contents
7129 @cindex contents, table of
7130 For a table of contents, to name an example, tab stops may be defined so
7131 that the section number is one tab stop, the title is the second with
7132 the remaining space being filled with a line of dots, and then the page
7133 number slightly separated from the dots.
7136 .ds entry 1.1\tFoo\a\t12
7146 1.1 Foo.......................................... 12
7149 @c ---------------------------------------------------------------------
7151 @node Fields, , Leaders, Tabs and Fields
7155 @cindex field delimiting character (@code{fc})
7156 @cindex delimiting character, for fields (@code{fc})
7157 @cindex character, field delimiting (@code{fc})
7158 @cindex field padding character (@code{fc})
7159 @cindex padding character, for fields (@code{fc})
7160 @cindex character, field padding (@code{fc})
7161 @dfn{Fields} are a more general way of laying out tabular data. A field
7162 is defined as the data between a pair of @dfn{delimiting characters}.
7163 It contains substrings which are separated by @dfn{padding characters}.
7164 The width of a field is the distance on the @emph{input} line from the
7165 position where the field starts to the next tab stop. A padding
7166 character inserts stretchable space similar to @TeX{}'s @code{\hss}
7167 command (thus it can even be negative) to make the sum of all substring
7168 lengths plus the stretchable space equal to the field width. If more
7169 than one padding character is inserted, the available space is evenly
7170 distributed among them.
7172 @Defreq {fc, [@Var{delim-char} [@Var{padding-char}]]}
7173 Define a delimiting and a padding character for fields. If the latter
7174 is missing, the padding character defaults to a space character. If
7175 there is no argument at all, the field mechanism is disabled (which is
7176 the default). Note that contrary to e.g.@: the tab repetition
7177 character, delimiting and padding characters are @emph{not} associated
7178 to the current environment (@pxref{Environments}).
7191 and here the result:
7200 @c =====================================================================
7202 @node Character Translations, Troff and Nroff Mode, Tabs and Fields, gtroff Reference
7203 @section Character Translations
7204 @cindex character translations
7205 @cindex translations of characters
7207 @cindex control character, changing (@code{cc})
7208 @cindex character, control, changing (@code{cc})
7209 @cindex no-break control character, changing (@code{c2})
7210 @cindex character, no-break control, changing (@code{c2})
7211 @cindex control character, no-break, changing (@code{c2})
7212 The control character (@samp{.}) and the no-break control character
7213 (@samp{'}) can be changed with the @code{cc} and @code{c2} requests,
7216 @Defreq {cc, [@Var{c}]}
7217 Set the control character to@tie{}@var{c}. With no argument the default
7218 control character @samp{.} is restored. The value of the control
7219 character is associated with the current environment
7220 (@pxref{Environments}).
7223 @Defreq {c2, [@Var{c}]}
7224 Set the no-break control character to@tie{}@var{c}. With no argument the
7225 default control character @samp{'} is restored. The value of the
7226 no-break control character is associated with the current environment
7227 (@pxref{Environments}).
7231 @cindex disabling @code{\} (@code{eo})
7232 @cindex @code{\}, disabling (@code{eo})
7233 Disable the escape mechanism completely. After executing this
7234 request, the backslash character @samp{\} no longer starts an escape
7237 This request can be very helpful in writing macros since it is not
7238 necessary then to double the escape character. Here an example:
7241 .\" This is a simplified version of the
7242 .\" .BR request from the man macro package
7246 . while (\n[.$] >= 2) \@{\
7247 . as result \fB\$1\fR\$2
7250 . if \n[.$] .as result \fB\$1
7258 @Defreq {ec, [@Var{c}]}
7259 @cindex escape character, changing (@code{ec})
7260 @cindex character, escape, changing (@code{ec})
7261 Set the escape character to@tie{}@var{c}. With no argument the default
7262 escape character @samp{\} is restored. It can be also used to
7263 re-enable the escape mechanism after an @code{eo} request.
7265 Note that changing the escape character globally will likely break
7266 macro packages since @code{gtroff} has no mechanism to `intern' macros,
7267 i.e., to convert a macro definition into an internal form which is
7268 independent of its representation (@TeX{} has this mechanism).
7269 If a macro is called, it is executed literally.
7273 @DefreqListEnd {ecr, }
7274 The @code{ecs} request saves the current escape character
7275 in an internal register.
7276 Use this request in combination with the @code{ec} request to
7277 temporarily change the escape character.
7279 The @code{ecr} request restores the escape character
7280 saved with @code{ecs}.
7281 Without a previous call to @code{ecs}, this request
7282 sets the escape character to @code{\}.
7285 @DefescList {\\\\, , , }
7286 @DefescItem {\\e, , , }
7287 @DefescListEnd {\\E, , , }
7288 Print the current escape character (which is the backslash character
7289 @samp{\} by default).
7291 @code{\\} is a `delayed' backslash; more precisely, it is the default
7292 escape character followed by a backslash, which no longer has special
7293 meaning due to the leading escape character. It is @emph{not} an escape
7294 sequence in the usual sense! In any unknown escape sequence
7295 @code{\@var{X}} the escape character is ignored and @var{X} is printed.
7296 But if @var{X} is equal to the current escape character, no warning is
7299 As a consequence, only at top-level or in a diversion a backslash glyph is
7300 printed; in copy-in mode, it expands to a single backslash which then
7301 combines with the following character to an escape sequence.
7303 The @code{\E} escape differs from @code{\e} by printing an escape
7304 character that is not interpreted in copy mode.
7305 Use this to define strings with escapes that work
7306 when used in copy mode (for example, as a macro argument).
7307 The following example defines strings to begin and end
7311 .ds @{ \v'-.3m'\s'\En[.s]*60/100'
7315 Another example to demonstrate the differences between the various escape
7316 sequences, using a strange escape character, @samp{-}.
7328 The result is surprising for most users, expecting @samp{1} since
7329 @samp{foo} is a valid identifier. What has happened? As mentioned
7330 above, the leading escape character makes the following character
7331 ordinary. Written with the default escape character the sequence
7332 @samp{--} becomes @samp{\-} -- this is the minus sign.
7334 If the escape character followed by itself is a valid escape sequence,
7335 only @code{\E} yields the expected result:
7348 Similar to @code{\\}, the sequence @code{\.} isn't a real escape sequence.
7349 As before, a warning message is suppressed if the escape character is
7350 followed by a dot, and the dot itself is printed.
7367 The first backslash is consumed while the macro is read, and the second
7368 is swallowed while exexuting macro @code{foo}.
7371 A @dfn{translation} is a mapping of an input character to an output
7372 glyph. The mapping occurs at output time, i.e., the input character
7373 gets assigned the metric information of the mapped output character
7374 right before input tokens are converted to nodes (@pxref{Gtroff
7375 Internals}, for more on this process).
7377 @DefreqList {tr, @Var{a}@Var{b}@Var{c}@Var{d}@dots{}}
7378 @DefreqListEnd {trin, @Var{a}@Var{b}@Var{c}@Var{d}@dots{}}
7379 Translate character @var{a} to glyph@tie{}@var{b}, character @var{c} to
7380 glyph@tie{}@var{d}, etc. If there is an odd number of arguments, the
7381 last one is translated to an unstretchable space (@w{@samp{\ }}).
7383 The @code{trin} request is identical to @code{tr},
7384 but when you unformat a diversion with @code{asciify}
7385 it ignores the translation.
7386 @xref{Diversions}, for details about the @code{asciify} request.
7392 @cindex @code{\(}, and translations
7393 @cindex @code{\[}, and translations
7394 @cindex @code{\'}, and translations
7395 @cindex @code{\`}, and translations
7396 @cindex @code{\-}, and translations
7397 @cindex @code{\_}, and translations
7398 @cindex @code{\C}, and translations
7399 @cindex @code{\N}, and translations
7400 @cindex @code{char} request, and translations
7401 @cindex special characters
7402 @cindex character, special
7403 @cindex numbered glyph (@code{\N})
7404 @cindex glyph, numbered (@code{\N})
7405 Special characters (@code{\(@var{xx}}, @code{\[@var{xxx}]},
7406 @code{\C'@var{xxx}'}, @code{\'}, @code{\`}, @code{\-}, @code{\_}),
7407 glyphs defined with the @code{char} request, and numbered glyphs
7408 (@code{\N'@var{xxx}'}) can be translated also.
7411 @cindex @code{\e}, and translations
7412 The @code{\e} escape can be translated also.
7415 @cindex @code{\%}, and translations
7416 @cindex @code{\~}, and translations
7417 Characters can be mapped onto the @code{\%} and @code{\~} escapes (but
7418 @code{\%} and @code{\~} can't be mapped onto another glyph).
7421 @cindex backspace character, and translations
7422 @cindex character, backspace, and translations
7423 @cindex leader character, and translations
7424 @cindex character, leader, and translations
7425 @cindex newline character, and translations
7426 @cindex character, newline, and translations
7427 @cindex tab character, and translations
7428 @cindex character, tab, and translations
7429 @cindex @code{\a}, and translations
7430 @cindex @code{\t}, and translations
7431 The following characters can't be translated: space (with one exception,
7432 see below), backspace, newline, leader (and @code{\a}), tab (and
7436 @cindex @code{shc} request, and translations
7437 Translations are not considered for finding the soft hyphen character
7438 set with the @code{shc} request.
7441 @cindex @code{\&}, and translations
7442 The pair @samp{@var{c}\&} (this is an arbitrary character@tie{}@var{c}
7443 followed by the zero width space character) maps this character to nothing.
7452 It is even possible to map the space character to nothing:
7461 As shown in the example, the space character can't be the first
7462 character/glyph pair as an argument of @code{tr}. Additionally, it is
7463 not possible to map the space character to any other glyph; requests
7464 like @w{@samp{.tr aa x}} undo @w{@samp{.tr aa \&}} instead.
7466 If justification is active, lines are justified in spite of the
7467 `empty' space character (but there is no minimal distance, i.e.@: the
7468 space character, between words).
7471 After an output glyph has been constructed (this happens at the
7472 moment immediately before the glyph is appended to an output
7473 glyph list, either by direct output, in a macro, diversion, or
7474 string), it is no longer affected by @code{tr}.
7477 Translating character to glyphs where one of them or both are
7478 undefined is possible also; @code{tr} does not check whether the
7479 entities in its argument do exist.
7481 @xref{Gtroff Internals}.
7484 @code{troff} no longer has a hard-coded dependency on @w{Latin-1};
7485 all @code{char@var{XXX}} entities have been removed from the font
7486 description files. This has a notable consequence which shows up in
7487 warnings like @code{can't find character with input code @var{XXX}}
7488 if the @code{tr} request isn't handled properly.
7490 Consider the following translation:
7497 This maps input character @code{@'e} onto glyph @code{@'E}, which is
7498 identical to glyph @code{char201}. But this glyph intentionally
7499 doesn't exist! Instead, @code{\[char201]} is treated as an input
7500 character entity and is by default mapped onto @code{\['E]}, and
7501 @code{gtroff} doesn't handle translations of translations.
7503 The right way to write the above translation is
7510 With other words, the first argument of @code{tr} should be an input
7511 character or entity, and the second one a glyph entity.
7514 Without an argument, the @code{tr} request is ignored.
7518 @Defreq {trnt, @Var{a}@Var{b}@Var{c}@Var{d}@dots{}}
7519 @cindex @code{\!}, and @code{trnt}
7520 @code{trnt} is the same as the @code{tr} request except that the
7521 translations do not apply to text that is transparently throughput
7522 into a diversion with @code{\!}. @xref{Diversions}, for more
7536 prints @samp{b} to the standard error stream; if @code{trnt} is used
7537 instead of @code{tr} it prints @samp{a}.
7541 @c =====================================================================
7543 @node Troff and Nroff Mode, Line Layout, Character Translations, gtroff Reference
7544 @section Troff and Nroff Mode
7550 Originally, @code{nroff} and @code{troff} were two separate programs,
7551 the former for TTY output, the latter for everything else. With GNU
7552 @code{troff}, both programs are merged into one executable, sending
7553 its output to a device driver (@code{grotty} for TTY devices,
7554 @code{grops} for @sc{PostScript}, etc.) which interprets the
7555 intermediate output of @code{gtroff}. For @acronym{UNIX} @code{troff}
7556 it makes sense to talk about @dfn{Nroff mode} and @dfn{Troff mode}
7557 since the differences are hardcoded. For GNU @code{troff}, this
7558 distinction is not appropriate because @code{gtroff} simply takes the
7559 information given in the font files for a particular device without
7560 handling requests specially if a TTY output device is used.
7562 Usually, a macro package can be used with all output devices.
7563 Nevertheless, it is sometimes necessary to make a distinction between
7564 TTY and non-TTY devices: @code{gtroff} provides two built-in
7565 conditions @samp{n} and @samp{t} for the @code{if}, @code{ie}, and
7566 @code{while} requests to decide whether @code{gtroff} shall behave
7567 like @code{nroff} or like @code{troff}.
7572 Make the @samp{t} built-in condition true (and the @samp{n} built-in
7573 condition false) for @code{if}, @code{ie}, and @code{while}
7574 conditional requests. This is the default if @code{gtroff}
7575 (@emph{not} @code{groff}) is started with the @option{-R} switch to
7576 avoid loading of the start-up files @file{troffrc} and
7577 @file{troffrc-end}. Without @option{-R}, @code{gtroff} stays in troff
7578 mode if the output device is not a TTY (e.g.@: `ps').
7583 Make the @samp{n} built-in condition true (and the @samp{t} built-in
7584 condition false) for @code{if}, @code{ie}, and @code{while}
7585 conditional requests. This is the default if @code{gtroff} uses a TTY
7586 output device; the code for switching to nroff mode is in the file
7587 @file{tty.tmac} which is loaded by the start-up file @code{troffrc}.
7590 @xref{Conditionals and Loops}, for more details on built-in
7594 @c =====================================================================
7596 @node Line Layout, Line Control, Troff and Nroff Mode, gtroff Reference
7597 @section Line Layout
7599 @cindex layout, line
7601 @cindex dimensions, line
7602 @cindex line dimensions
7603 The following drawing shows the dimensions which @code{gtroff} uses for
7604 placing a line of output onto the page. They are labeled with the
7605 request which manipulates each dimension.
7609 |<-----------ll------------>|
7610 +----+----+----------------------+----+
7612 +----+----+----------------------+----+
7614 |<--------paper width---------------->|
7618 These dimensions are:
7622 @cindex left margin (@code{po})
7623 @cindex margin, left (@code{po})
7624 @cindex page offset (@code{po})
7625 @cindex offset, page (@code{po})
7626 @dfn{Page offset} -- this is the leftmost position of text on the final
7627 output, defining the @dfn{left margin}.
7630 @cindex indentation (@code{in})
7631 @cindex line indentation (@code{in})
7632 @dfn{Indentation} -- this is the distance from the left margin where
7636 @cindex line length (@code{ll})
7637 @cindex length of line (@code{ll})
7638 @dfn{Line length} -- this is the distance from the left margin to right
7642 A simple demonstration:
7646 This is text without indentation.
7647 The line length has been set to 3\~inch.
7650 Now the left and right margins are both increased.
7653 Calling .in and .ll without parameters restore
7654 the previous values.
7660 This is text without indenta-
7661 tion. The line length has
7666 Calling .in and .ll without
7667 parameters restore the previ-
7671 @DefreqList {po, [@Var{offset}]}
7672 @DefreqItem {po, @t{+}@Var{offset}}
7673 @DefreqItem {po, @t{-}@Var{offset}}
7676 Set horizontal page offset to @var{offset} (or increment or decrement
7677 the current value by @var{offset}). Note that this request does not
7678 cause a break, so changing the page offset in the middle of text being
7679 filled may not yield the expected result. The initial value is
7680 1@dmn{i}. For TTY output devices, it is set to 0 in the startup file
7681 @file{troffrc}; the default scaling indicator is @samp{m} (and
7682 not @samp{v} as incorrectly documented in the original
7683 @acronym{UNIX} troff manual).
7685 The current page offset can be found in the read-only number register
7688 If @code{po} is called without an argument, the page offset is reset to
7689 the previous value before the last call to @code{po}.
7704 @DefreqList {in, [@Var{indent}]}
7705 @DefreqItem {in, @t{+}@Var{indent}}
7706 @DefreqItem {in, @t{-}@Var{indent}}
7708 Set indentation to @var{indent} (or increment or decrement the
7709 current value by @var{indent}). This request causes a break.
7710 Initially, there is no indentation.
7712 If @code{in} is called without an argument, the indentation is reset to
7713 the previous value before the last call to @code{in}. The default
7714 scaling indicator is @samp{m}.
7716 The indentation is associated with the current environment
7717 (@pxref{Environments}).
7719 If a negative indentation value is specified (which is not allowed),
7720 @code{gtroff} emits a warning of type @samp{range} and sets the
7721 indentation to zero.
7723 The effect of @code{in} is delayed until a partially collected line (if
7724 it exists) is output. A temporary indent value is reset to zero also.
7726 The current indentation (as set by @code{in}) can be found in the
7727 read-only number register @samp{.i}.
7730 @DefreqList {ti, offset}
7731 @DefreqItem {ti, @t{+}@Var{offset}}
7732 @DefreqItem {ti, @t{-}@Var{offset}}
7733 @DefregListEnd {.in}
7734 Temporarily indent the next output line by @var{offset}. If an
7735 increment or decrement value is specified, adjust the temporary
7736 indentation relative to the value set by the @code{in} request.
7738 This request causes a break; its value is associated with the current
7739 environment (@pxref{Environments}). The default scaling indicator
7740 is @samp{m}. A call of @code{ti} without an argument is ignored.
7742 If the total indentation value is negative (which is not allowed),
7743 @code{gtroff} emits a warning of type @samp{range} and sets the
7744 temporary indentation to zero. `Total indentation' is either
7745 @var{offset} if specified as an absolute value, or the temporary plus
7746 normal indentation, if @var{offset} is given as a relative value.
7748 The effect of @code{ti} is delayed until a partially collected line (if
7749 it exists) is output.
7751 The read-only number register @code{.in} is the indentation that applies
7752 to the current output line.
7754 The difference between @code{.i} and @code{.in} is that the latter takes
7755 into account whether a partially collected line still uses the old
7756 indentation value or a temporary indentation value is active.
7759 @DefreqList {ll, [@Var{length}]}
7760 @DefreqItem {ll, @t{+}@Var{length}}
7761 @DefreqItem {ll, @t{-}@Var{length}}
7763 @DefregListEnd {.ll}
7764 Set the line length to @var{length} (or increment or decrement the
7765 current value by @var{length}). Initially, the line length is set to
7766 6.5@dmn{i}. The effect of @code{ll} is delayed until a partially
7767 collected line (if it exists) is output. The default scaling
7768 indicator is @samp{m}.
7770 If @code{ll} is called without an argument, the line length is reset to
7771 the previous value before the last call to @code{ll}. If a negative
7772 line length is specified (which is not allowed), @code{gtroff} emits a
7773 warning of type @samp{range} and sets the line length to zero.
7775 The line length is associated with the current environment
7776 (@pxref{Environments}).
7778 @cindex line length register (@code{.l})
7779 The current line length (as set by @code{ll}) can be found in the
7780 read-only number register @samp{.l}. The read-only number register
7781 @code{.ll} is the line length that applies to the current output line.
7783 Similar to @code{.i} and @code{.in}, the difference between @code{.l}
7784 and @code{.ll} is that the latter takes into account whether a partially
7785 collected line still uses the old line length value.
7789 @c =====================================================================
7791 @node Line Control, Page Layout, Line Layout, gtroff Reference
7792 @section Line Control
7793 @cindex line control
7794 @cindex control, line
7796 It is important to understand how @code{gtroff} handles input and output
7799 Many escapes use positioning relative to the input line. For example,
7803 This is a \h'|1.2i'test.
7818 The main usage of this feature is to define macros which act exactly
7819 at the place where called.
7822 .\" A simple macro to underline a word
7824 . nop \\$1\l'|0\[ul]'
7829 In the above example, @samp{|0} specifies a negative distance from the
7830 current position (at the end of the just emitted argument @code{\$1}) back
7831 to the beginning of the input line. Thus, the @samp{\l} escape draws a
7832 line from right to left.
7834 @cindex input line continuation (@code{\})
7835 @cindex line, input, continuation (@code{\})
7836 @cindex continuation, input line (@code{\})
7837 @cindex output line, continuation (@code{\c})
7838 @cindex line, output, continuation (@code{\c})
7839 @cindex continuation, output line (@code{\c})
7840 @cindex interrupted line
7841 @cindex line, interrupted
7842 @code{gtroff} makes a difference between input and output line
7843 continuation; the latter is also called @dfn{interrupting} a line.
7845 @DefescList {\\@key{RET}, , ,}
7846 @DefescItem {\\c, , ,}
7847 @DefregListEnd{.int}
7848 Continue a line. @code{\@key{RET}} (this is a backslash at the end
7849 of a line immediately followed by a newline) works on the input level,
7850 suppressing the effects of the following newline in the input.
7855 @result{} This is a .test
7858 The @samp{|} operator is also affected.
7860 @cindex @code{\R}, after @code{\c}
7861 @code{\c} works on the output level. Anything after this escape on the
7862 same line is ignored, except @code{\R} which works as usual. Anything
7863 before @code{\c} on the same line will be appended to the current partial
7864 output line. The next non-command line after an interrupted line counts
7865 as a new input line.
7867 The visual results depend on whether no-fill mode is active.
7871 @cindex @code{\c}, and no-fill mode
7872 @cindex no-fill mode, and @code{\c}
7873 @cindex mode, no-fill, and @code{\c}
7874 If no-fill mode is active (using the @code{nf} request), the next input
7875 text line after @code{\c} will be handled as a continuation of the same
7882 @result{} This is a test.
7886 @cindex @code{\c}, and fill mode
7887 @cindex fill mode, and @code{\c}
7888 @cindex mode, fill, and @code{\c}
7889 If fill mode is active (using the @code{fi} request), a word interrupted
7890 with @code{\c} will be continued with the text on the next input text line,
7891 without an intervening space.
7896 @result{} This is a test.
7900 Note that an intervening control line which causes a break is stronger
7901 than @code{\c}, flushing out the current partial line in the usual way.
7903 @cindex interrupted line register (@code{.int})
7904 The @code{.int} register contains a positive value
7905 if the last output line was interrupted with @code{\c}; this is
7906 associated with the current environment (@pxref{Environments}).
7909 @c =====================================================================
7911 @node Page Layout, Page Control, Line Control, gtroff Reference
7912 @section Page Layout
7914 @cindex layout, page
7916 @code{gtroff} provides some very primitive operations for controlling
7919 @DefreqList {pl, [@Var{length}]}
7920 @DefreqItem {pl, @t{+}@Var{length}}
7921 @DefreqItem {pl, @t{-}@Var{length}}
7923 @cindex page length (@code{pl})
7924 @cindex length of page (@code{pl})
7925 Set the @dfn{page length} to @var{length} (or increment or decrement
7926 the current value by @var{length}). This is the length of the
7927 physical output page. The default scaling indicator is @samp{v}.
7929 @cindex page length register (@code{.p})
7930 The current setting can be found in the read-only number register
7935 @cindex bottom margin
7936 @cindex margin, bottom
7937 Note that this only specifies the size of the page, not the top and
7938 bottom margins. Those are not set by @code{gtroff} directly.
7939 @xref{Traps}, for further information on how to do this.
7941 Negative @code{pl} values are possible also, but not very useful: No
7942 trap is sprung, and each line is output on a single page (thus
7943 suppressing all vertical spacing).
7945 If no argument or an invalid argument is given, @code{pl} sets the page
7946 length to 11@dmn{i}.
7952 @code{gtroff} provides several operations which help in setting up top
7953 and bottom titles (or headers and footers).
7955 @Defreq {tl, @t{'}@Var{left}@t{'}@Var{center}@t{'}@Var{right}@t{'}}
7956 @cindex title line (@code{tl})
7957 @cindex three-part title (@code{tl})
7958 @cindex page number character (@code{%})
7959 Print a @dfn{title line}. It consists of three parts: a left
7960 justified portion, a centered portion, and a right justified portion.
7961 The argument separator @samp{'} can be replaced with any character not
7962 occurring in the title line. The @samp{%} character is replaced with
7963 the current page number. This character can be changed with the
7964 @code{pc} request (see below).
7966 Without argument, @code{tl} is ignored.
7972 A title line is not restricted to the top or bottom of a page.
7975 @code{tl} prints the title line immediately, ignoring a partially filled
7976 line (which stays untouched).
7979 It is not an error to omit closing delimiters. For example,
7980 @w{@samp{.tl /foo}} is equivalent to @w{@samp{.tl /foo///}}: It prints a
7981 title line with the left justified word @samp{foo}; the centered and
7982 right justfied parts are empty.
7985 @code{tl} accepts the same parameter delimiting characters as the
7986 @code{\A} escape; see @ref{Escapes}.
7990 @DefreqList {lt, [@Var{length}]}
7991 @DefreqItem {lt, @t{+}@Var{length}}
7992 @DefreqItem {lt, @t{-}@Var{length}}
7993 @DefregListEnd {.lt}
7994 @cindex length of title line (@code{lt})
7995 @cindex title line, length (@code{lt})
7996 @cindex title line length register (@code{.lt})
7997 The title line is printed using its own line length, which is
7998 specified (or incremented or decremented) with the @code{lt} request.
7999 Initially, the title line length is set to 6.5@dmn{i}. If a negative
8000 line length is specified (which is not allowed), @code{gtroff} emits a
8001 warning of type @samp{range} and sets the title line length to zero.
8002 The default scaling indicator is @samp{m}. If @code{lt} is called
8003 without an argument, the title length is reset to the previous value
8004 before the last call to @code{lt}.
8006 The current setting of this is available in the @code{.lt} read-only
8007 number register; it is associated with the current environment
8008 (@pxref{Environments}).
8011 @DefreqList {pn, page}
8012 @DefreqItem {pn, @t{+}@Var{page}}
8013 @DefreqItem {pn, @t{-}@Var{page}}
8014 @DefregListEnd {.pn}
8015 @cindex page number (@code{pn})
8016 @cindex number, page (@code{pn})
8017 Change (increase or decrease) the page number of the @emph{next} page.
8018 The only argument is the page number; the request is ignored without a
8021 The read-only number register @code{.pn} contains the number of the next
8022 page: either the value set by a @code{pn} request, or the number of the
8023 current page plus@tie{}1.
8026 @Defreq {pc, [@Var{char}]}
8027 @cindex changing the page number character (@code{pc})
8028 @cindex page number character, changing (@code{pc})
8030 Change the page number character (used by the @code{tl} request) to a
8031 different character. With no argument, this mechanism is disabled.
8032 Note that this doesn't affect the number register@tie{}@code{%}.
8038 @c =====================================================================
8040 @node Page Control, Fonts and Symbols, Page Layout, gtroff Reference
8041 @section Page Control
8042 @cindex page control
8043 @cindex control, page
8045 @DefreqList {bp, [@Var{page}]}
8046 @DefreqItem {bp, @t{+}@Var{page}}
8047 @DefreqItem {bp, @t{-}@Var{page}}
8049 @cindex new page (@code{bp})
8050 @cindex page, new (@code{bp})
8051 Stop processing the current page and move to the next page. This
8052 request causes a break. It can also take an argument to set
8053 (increase, decrease) the page number of the next page (which actually
8054 becomes the current page after @code{bp} has finished). The
8055 difference between @code{bp} and @code{pn} is that @code{pn} does not
8056 cause a break or actually eject a page. @xref{Page Layout}.
8059 .de newpage \" define macro
8061 'sp .5i \" vertical space
8062 .tl 'left top'center top'right top' \" title
8063 'sp .3i \" vertical space
8067 @cindex @code{bp} request, and top-level diversion
8068 @cindex top-level diversion, and @code{bp}
8069 @cindex diversion, top-level, and @code{bp}
8070 @code{bp} has no effect if not called within the top-level diversion
8071 (@pxref{Diversions}).
8073 @cindex page number register (@code{%})
8074 @cindex current page number (@code{%})
8075 The read-write register@tie{}@code{%} holds the current page number.
8077 The number register @code{.pe} is set to@tie{}1 while @code{bp} is
8078 active. @xref{Page Location Traps}.
8081 @Defreq {ne, [@Var{space}]}
8082 @cindex orphan lines, preventing with @code{ne}
8083 @cindex conditional page break (@code{ne})
8084 @cindex page break, conditional (@code{ne})
8085 It is often necessary to force a certain amount of space before a new
8086 page occurs. This is most useful to make sure that there is not a
8087 single @dfn{orphan} line left at the bottom of a page. The @code{ne}
8088 request ensures that there is a certain distance, specified by the
8089 first argument, before the next page is triggered (see @ref{Traps},
8090 for further information). The default scaling indicator for @code{ne}
8091 is @samp{v}; the default value of @var{space} is@tie{}1@dmn{v} if no
8094 For example, to make sure that no fewer than 2@tie{}lines get orphaned,
8095 do the following before each paragraph:
8102 @code{ne} will then automatically cause a page break if there is space
8106 @DefreqList {sv, [@Var{space}]}
8107 @DefreqListEnd {os, }
8108 @cindex @code{ne} request, comparison with @code{sv}
8109 @code{sv} is similar to the @code{ne} request; it reserves the
8110 specified amount of vertical space. If the desired amount of space
8111 exists before the next trap (or the bottom page boundary if no trap is
8112 set), the space is output immediately (ignoring a partially filled line
8113 which stays untouched). If there is not enough space, it is stored for
8114 later output via the @code{os} request. The default value is@tie{}1@dmn{v}
8115 if no argument is given; the default scaling indicator is @samp{v}.
8117 @cindex @code{sv} request, and no-space mode
8118 @cindex @code{os} request, and no-space mode
8119 Both @code{sv} and @code{os} ignore no-space mode. While the @code{sv}
8120 request allows negative values for @var{space}, @code{os} will ignore
8125 @cindex current vertical position (@code{nl})
8126 @cindex vertical position, current (@code{nl})
8127 @cindex position, vertical, current (@code{nl})
8128 This register contains the current vertical position. If the vertical
8129 position is zero and the top of page transition hasn't happened yet,
8130 @code{nl} is set to negative value. @code{gtroff} itself does this at
8131 the very beginning of a document before anything has been printed, but
8132 the main usage is to plant a header trap on a page if this page has
8135 Consider the following:
8167 Without resetting @code{nl} to a negative value, the just planted trap
8168 would be active beginning with the @emph{next} page, not the current
8171 @xref{Diversions}, for a comparison with the @code{.h} and @code{.d}
8175 @c =====================================================================
8177 @node Fonts and Symbols, Sizes, Page Control, gtroff Reference
8178 @section Fonts and Symbols
8181 @code{gtroff} can switch fonts at any point in the text.
8183 The basic set of fonts is @samp{R}, @samp{I}, @samp{B}, and @samp{BI}.
8184 These are Times Roman, Italic, Bold, and Bold Italic. For non-TTY
8185 devices, there is also at least one symbol font which contains various
8186 special symbols (Greek, mathematics).
8194 * Artificial Fonts::
8195 * Ligatures and Kerning::
8198 @c ---------------------------------------------------------------------
8200 @node Changing Fonts, Font Families, Fonts and Symbols, Fonts and Symbols
8201 @subsection Changing Fonts
8204 @DefreqList {ft, [@Var{font}]}
8205 @DefescItem {\\f, , f, }
8206 @DefescItem {\\f, @lparen{}, fn, }
8207 @DefescListEnd {\\f, @lbrack{}, font, @rbrack}
8208 @cindex changing fonts (@code{ft}, @code{\f})
8209 @cindex fonts, changing (@code{ft}, @code{\f})
8210 @cindex @code{sty} request, and changing fonts
8211 @cindex @code{fam} request, and changing fonts
8212 @cindex @code{\F}, and changing fonts
8216 The @code{ft} request and the @code{\f} escape change the current font
8217 to @var{font} (one-character name@tie{}@var{f}, two-character name
8220 If @var{font} is a style name (as set with the @code{sty} request or
8221 with the @code{styles} command in the @file{DESC} file), use it within
8222 the current font family (as set with the @code{fam} request, @code{\F}
8223 escape, or with the @code{family} command in the @file{DESC} file).
8225 @cindex previous font (@code{ft}, @code{\f[]}, @code{\fP})
8226 @cindex font, previous (@code{ft}, @code{\f[]}, @code{\fP})
8227 With no argument or using @samp{P} as an argument, @code{.ft} switches
8228 to the previous font. Use @code{\f[]} to do this with the escape. The
8229 old syntax forms @code{\fP} or @code{\f[P]} are also supported.
8231 Fonts are generally specified as upper-case strings, which are usually
8232 1@tie{}to 4 characters representing an abbreviation or acronym of the
8233 font name. This is no limitation, just a convention.
8235 The example below produces two identical lines.
8244 eggs, bacon, \fBspam\fP and sausage.
8247 Note that @code{\f} doesn't produce an input token in @code{gtroff}.
8248 As a consequence, it can be used in requests like @code{mc} (which
8249 expects a single character as an argument) to change the font on
8256 @xref{Font Positions}, for an alternative syntax.
8259 @Defreq {ftr, f [@Var{g}]}
8260 @cindex @code{ft} request, and font translations
8261 @cindex @code{ul} request, and font translations
8262 @cindex @code{bd} request, and font translations
8263 @cindex @code{\f}, and font translations
8264 @cindex @code{cs} request, and font translations
8265 @cindex @code{tkf} request, and font translations
8266 @cindex @code{special} request, and font translations
8267 @cindex @code{fspecial} request, and font translations
8268 @cindex @code{fp} request, and font translations
8269 @cindex @code{sty} request, and font translations
8270 Translate font@tie{}@var{f} to font@tie{}@var{g}. Whenever a font
8271 named@tie{}@var{f} is referred to in a @code{\f} escape sequence, or in the
8272 @code{ft}, @code{ul}, @code{bd}, @code{cs}, @code{tkf},
8273 @code{special}, @code{fspecial}, @code{fp}, or @code{sty} requests,
8274 font@tie{}@var{g} is used. If @var{g} is missing or equal to@tie{}@var{f}
8275 the translation is undone.
8278 @c ---------------------------------------------------------------------
8280 @node Font Families, Font Positions, Changing Fonts, Fonts and Symbols
8281 @subsection Font Families
8282 @cindex font families
8283 @cindex families, font
8285 @cindex styles, font
8287 Due to the variety of fonts available, @code{gtroff} has added the
8288 concept of @dfn{font families} and @dfn{font styles}. The fonts are
8289 specified as the concatenation of the font family and style. Specifying
8290 a font without the family part causes @code{gtroff} to use that style of
8293 @cindex PostScript fonts
8294 @cindex fonts, PostScript
8295 Currently, fonts for the devices @option{-Tps}, @option{-Tdvi}, and
8296 @option{-Tlbp} are set up to this mechanism.
8297 By default, @code{gtroff} uses the Times family with the four styles
8298 @samp{R}, @samp{I}, @samp{B}, and @samp{BI}.
8300 This way, it is possible to use the basic four fonts and to select a
8301 different font family on the command line (@pxref{Groff Options}).
8303 @DefreqList {fam, [@Var{family}]}
8305 @DefescItem {\\F, , f, }
8306 @DefescItem {\\F, @lparen{}, fm, }
8307 @DefescItem {\\F, @lbrack{}, family, @rbrack}
8308 @DefregListEnd {.fn}
8309 @cindex changing font family (@code{fam}, @code{\F})
8310 @cindex font family, changing (@code{fam}, @code{\F})
8311 Switch font family to @var{family} (one-character name@tie{}@var{f},
8312 two-character name @var{fm}). If no argument is given, switch
8313 back to the previous font family. Use @code{\F[]} to do this with the
8314 escape. Note that @code{\FP} doesn't work; it selects font family
8317 The value at start-up is @samp{T}.
8318 The current font family is available in the read-only number register
8319 @samp{.fam} (this is a string-valued register); it is associated with
8320 the current environment.
8324 .fam H \" helvetica family
8325 spam, \" used font is family H + style R = HR
8326 .ft B \" family H + style B = font HB
8328 .fam T \" times family
8329 spam, \" used font is family T + style B = TB
8330 .ft AR \" font AR (not a style)
8332 .ft R \" family T + style R = font TR
8336 Note that @code{\F} doesn't produce an input token in @code{gtroff}.
8337 As a consequence, it can be used in requests like @code{mc} (which
8338 expects a single character as an argument) to change the font family on
8345 The @samp{.fn} register contains the current @dfn{real font name}
8346 of the current font.
8347 This is a string-valued register.
8348 If the current font is a style, the value of @code{\n[.fn]}
8349 is the proper concatenation of family and style name.
8352 @Defreq {sty, n style}
8353 @cindex changing font style (@code{sty})
8354 @cindex font style, changing (@code{sty})
8355 @cindex @code{cs} request, and font styles
8356 @cindex @code{bd} request, and font styles
8357 @cindex @code{tkf} request, and font styles
8358 @cindex @code{uf} request, and font styles
8359 @cindex @code{fspecial} request, and font styles
8360 Associate @var{style} with font position@tie{}@var{n}. A font position
8361 can be associated either with a font or with a style. The current
8362 font is the index of a font position and so is also either a font or a
8363 style. If it is a style, the font that is actually used is the font
8364 which name is the concatenation of the name of the current
8365 family and the name of the current style. For example, if the current
8366 font is@tie{}1 and font position@tie{}1 is associated with style
8367 @samp{R} and the current font family is @samp{T}, then font
8368 @samp{TR} will be used. If the current font is not a style, then the
8369 current family is ignored. If the requests @code{cs}, @code{bd},
8370 @code{tkf}, @code{uf}, or @code{fspecial} are applied to a style,
8371 they will instead be applied to the member of the current family
8372 corresponding to that style.
8374 @var{n}@tie{}must be a non-negative integer value.
8378 The default family can be set with the @option{-f} option
8379 (@pxref{Groff Options}). The @code{styles} command in the @file{DESC}
8380 file controls which font positions (if any) are initially associated
8381 with styles rather than fonts. For example, the default setting for
8382 @sc{PostScript} fonts
8398 @code{fam} and @code{\F} always check whether the current font position
8399 is valid; this can give surprising results if the current font position is
8400 associated with a style.
8402 In the following example, we want to access the @sc{PostScript} font
8403 @code{FooBar} from the font family @code{Foo}:
8408 @result{} warning: can't find font `FooR'
8412 The default font position at start-up is@tie{}1; for the
8413 @sc{PostScript} device, this is associated with style @samp{R}, so
8414 @code{gtroff} tries to open @code{FooR}.
8416 A solution to this problem is to use a dummy font like the following:
8419 .fp 0 dummy TR \" set up dummy font at position 0
8420 .sty \n[.fp] Bar \" register style `Bar'
8421 .ft 0 \" switch to font at position 0
8422 .fam Foo \" activate family `Foo'
8423 .ft Bar \" switch to font `FooBar'
8426 @xref{Font Positions}.
8429 @c ---------------------------------------------------------------------
8431 @node Font Positions, Using Symbols, Font Families, Fonts and Symbols
8432 @subsection Font Positions
8433 @cindex font positions
8434 @cindex positions, font
8436 For the sake of old phototypesetters and compatibility with old versions
8437 of @code{troff}, @code{gtroff} has the concept of font @dfn{positions},
8438 on which various fonts are mounted.
8440 @DefreqList {fp, pos font [@Var{external-name}]}
8442 @DefregListEnd {.fp}
8443 @cindex mounting font (@code{fp})
8444 @cindex font, mounting (@code{fp})
8445 Mount font @var{font} at position @var{pos} (which must be a
8446 non-negative integer). This numeric position can then be referred to
8447 with font changing commands. When @code{gtroff} starts it is using
8448 font position@tie{}1 (which must exist; position@tie{}0 is unused
8449 usually at start-up).
8451 @cindex font position register (@code{.f})
8452 The current font in use, as a font position, is available in the
8453 read-only number register @samp{.f}. This can be useful to remember the
8454 current font for later recall. It is associated with the current
8455 environment (@pxref{Environments}).
8458 .nr save-font \n[.f]
8460 ... text text text ...
8464 @cindex next free font position register (@code{.fp})
8465 The number of the next free font position is available in the read-only
8466 number register @samp{.fp}. This is useful when mounting a new font,
8470 .fp \n[.fp] NEATOFONT
8473 @pindex DESC@r{, and font mounting}
8474 Fonts not listed in the @file{DESC} file are automatically mounted on
8475 the next available font position when they are referenced. If a font
8476 is to be mounted explicitly with the @code{fp} request on an unused
8477 font position, it should be mounted on the first unused font position,
8478 which can be found in the @code{.fp} register. Although @code{gtroff}
8479 does not enforce this strictly, it is not allowed to mount a font at a
8480 position whose number is much greater (approx.@: 1000 positions) than
8481 that of any currently used position.
8483 The @code{fp} request has an optional third argument. This argument
8484 gives the external name of the font, which is used for finding the font
8485 description file. The second argument gives the internal name of the
8486 font which is used to refer to the font in @code{gtroff} after it has
8487 been mounted. If there is no third argument then the internal name is
8488 used as the external name. This feature makes it possible to use
8489 fonts with long names in compatibility mode.
8492 Both the @code{ft} request and the @code{\f} escape have alternative
8493 syntax forms to access font positions.
8495 @DefreqList {ft, nnn}
8496 @DefescItem {\\f, , n, }
8497 @DefescItem {\\f, @lparen{}, nn, }
8498 @DefescListEnd {\\f, @lbrack{}, nnn, @rbrack}
8499 @cindex changing font position (@code{\f})
8500 @cindex font position, changing (@code{\f})
8501 @cindex @code{sty} request, and font positions
8502 @cindex @code{fam} request, and font positions
8503 @cindex @code{\F}, and font positions
8507 Change the current font position to @var{nnn} (one-digit
8508 position@tie{}@var{n}, two-digit position @var{nn}), which must be a
8509 non-negative integer.
8511 If @var{nnn} is associated with a style (as set with the @code{sty}
8512 request or with the @code{styles} command in the @file{DESC} file), use
8513 it within the current font family (as set with the @code{fam} request,
8514 the @code{\F} escape, or with the @code{family} command in the @file{DESC}
8521 .ft \" switch back to font 1
8525 this is font 1 again
8528 @xref{Changing Fonts}, for the standard syntax form.
8531 @c ---------------------------------------------------------------------
8533 @node Using Symbols, Special Fonts, Font Positions, Fonts and Symbols
8534 @subsection Using Symbols
8535 @cindex using symbols
8536 @cindex symbols, using
8541 A @dfn{glyph} is a graphical representation of a @dfn{character}.
8542 While a character is an abstract entity containing semantic
8543 information, a glyph is something which can be actually seen on screen
8544 or paper. It is possible that a character has multiple glyph
8545 representation forms (for example, the character `A' can be either
8546 written in a roman or an italic font, yielding two different glyphs);
8547 sometimes more than one character maps to a single glyph (this is a
8548 @dfn{ligature} -- the most common is `fi').
8551 @cindex special fonts
8554 @cindex @code{special} request, and glyph search order
8555 @cindex @code{fspecial} request, and glyph search order
8556 A @dfn{symbol} is simply a named glyph. Within @code{gtroff}, all
8557 glyph names of a particular font are defined in its font file. If the
8558 user requests a glyph not available in this font, @code{gtroff} looks
8559 up an ordered list of @dfn{special fonts}. By default, the
8560 @sc{PostScript} output device supports the two special fonts @samp{SS}
8561 (slanted symbols) and @samp{S} (symbols) (the former is looked up
8562 before the latter). Other output devices use different names for
8563 special fonts. Fonts mounted with the @code{fonts} keyword in the
8564 @file{DESC} file are globally available. To install additional
8565 special fonts locally (i.e.@: for a particular font), use the
8566 @code{fspecial} request.
8568 Here the exact rules how @code{gtroff} searches a given symbol:
8572 If the symbol has been defined with the @code{char} request, use it.
8573 This hides a symbol with the same name in the current font.
8576 Check the current font.
8579 If the symbol has been defined with the @code{fchar} request, use it.
8582 Check whether the current font has a font-specific list of special fonts;
8583 test all fonts in the order of appearance in the last @code{fspecial}
8584 call if appropriate.
8587 If the symbol has been defined with the @code{fschar} request for the
8588 current font, use it.
8591 Check all fonts in the order of appearance in the last @code{special}
8595 If the symbol has been defined with the @code{schar} request, use it.
8598 As a last resort, consult all fonts loaded up to now for special fonts
8599 and check them, starting with the lowest font number. Note that this can
8600 sometimes lead to surprising results since the @code{fonts} line in the
8601 @file{DESC} file often contains empty positions which are filled later
8602 on. For example, consider the following:
8609 This mounts font @code{foo} at font position@tie{}3. We assume that
8610 @code{FOO} is a special font, containing glyph @code{foo},
8611 and that no font has been loaded yet. The line
8618 makes font @code{BAZ} special only if font @code{BAR} is active. We
8619 further assume that @code{BAZ} is really a special font, i.e., the font
8620 description file contains the @code{special} keyword, and that it
8621 also contains glyph @code{foo} with a special shape fitting to font
8622 @code{BAR}. After executing @code{fspecial}, font @code{BAR} is loaded at
8623 font position@tie{}1, and @code{BAZ} at position@tie{}2.
8625 We now switch to a new font @code{XXX}, trying to access glyph @code{foo}
8626 which is assumed to be missing. There are neither font-specific special
8627 fonts for @code{XXX} nor any other fonts made special with the
8628 @code{special} request, so @code{gtroff} starts the search for special
8629 fonts in the list of already mounted fonts, with increasing font
8630 positions. Consequently, it finds @code{BAZ} before @code{FOO} even for
8631 @code{XXX} which is not the intended behaviour.
8634 @xref{Font Files}, and @ref{Special Fonts}, for more details.
8636 @cindex list of available glyphs (@cite{groff_char(7)} man page)
8637 @cindex available glyphs, list (@cite{groff_char(7)} man page)
8638 @cindex glyphs, available, list (@cite{groff_char(7)} man page)
8639 The list of available symbols is device dependent; see the
8640 @cite{groff_char(7)} man page for a complete list of all glyphs. For
8644 man -Tdvi groff_char > groff_char.dvi
8648 for a list using the default DVI fonts (not all versions of the
8649 @code{man} program support the @option{-T} option). If you want to
8650 use an additional macro package to change the used fonts, @code{groff}
8651 must be called directly:
8654 groff -Tdvi -mec -man groff_char.7 > groff_char.dvi
8657 @cindex composite glyph names
8658 @cindex glyph names, composite
8659 @cindex groff glyph list (GGL)
8660 @cindex GGL (groff glyph list)
8661 @cindex adobe glyph list (AGL)
8662 @cindex AGL (adobe glyph list)
8663 Glyph names not listed in groff_char(7) are derived algorithmically,
8664 using a simplified version of the Adobe Glyph List (AGL) algorithm
8665 which is described in
8666 @uref{http://partners.adobe.com@//asn@//tech@//type@//unicodegn.jsp}.
8667 The (frozen) set of glyph names which can't be derived algorithmically
8668 is called @dfn{groff glyph list (GGL)}.
8672 A glyph for Unicode character U+@var{XXXX}[@var{X}[@var{X}]] which is
8673 not a composite character will be named
8674 @code{u@var{XXXX}@r{[}@var{X}@r{[}@var{X}@r{]]}}. @var{X} must be an
8675 uppercase hexadecimal digit. Examples: @code{u1234}, @code{u008E},
8676 @code{u12DB8}. The largest Unicode value is 0x10FFFF. There must be at
8677 least four @code{X} digits; if necessary, add leading zeroes (after the
8678 @samp{u}). No zero padding is allowed for character codes greater than
8679 0xFFFF. Surrogates (i.e., Unicode values greater than 0xFFFF
8680 represented with character codes from the surrogate area U+D800-U+DFFF)
8681 are not allowed too.
8684 A glyph representing more than a single input character will be named
8687 @samp{u} @var{component1} @samp{_} @var{component2} @samp{_} @var{component3} @dots{}
8691 Example: @code{u0045_0302_0301}.
8693 For simplicity, all Unicode characters which are composites must be
8694 decomposed maximally (this is normalization form@tie{}D in the Unicode
8695 standard); for example, @code{u00CA_0301} is not a valid glyph name
8696 since U+00CA (@sc{latin capital letter e with circumflex}) can be
8697 further decomposed into U+0045 (@sc{latin capital letter e}) and U+0302
8698 (@sc{combining circumflex accent}). @code{u0045_0302_0301} is thus the
8699 glyph name for U+1EBE, @sc{latin capital letter e with circumflex and
8703 groff maintains a table to decompose all algorithmically derived glyph
8704 names which are composites itself. For example, @code{u0100} (@sc{latin
8705 letter a with macron}) will be automatically decomposed into
8706 @code{u0041_0304}. Additionally, a glyph name of the GGL is preferred
8707 to an algorithmically derived glyph name; groff also automatically does
8708 the mapping. Example: The glyph @code{u0045_0302} will be mapped to
8712 glyph names of the GGL can't be used in composite glyph names; for
8713 example, @code{^E_u0301} is invalid.
8716 @DefescList {\\, @lparen{}, nm, }
8717 @DefescItem {\\, @lbrack{}, name, @rbrack}
8718 @DefescListEnd {\\, @lbrack{}, component1 component2 @dots{}, @rbrack}
8719 Insert a symbol @var{name} (two-character name @var{nm}) or a composite
8720 glyph with component glyphs @var{component1}, @var{component2},
8721 @enddots{} There is no special syntax for one-character names -- the
8722 natural form @samp{\@var{n}} would collide with escapes.@footnote{Note
8723 that a one-character symbol is not the same as an input character, i.e.,
8724 the character @code{a} is not the same as @code{\[a]}. By default,
8725 @code{groff} defines only a single one-character symbol, @code{\[-]}; it
8726 is usually accessed as @code{\-}. On the other hand, @code{gtroff} has
8727 the special feature that @code{\[char@var{XXX}]} is the same as the
8728 input character with character code @var{XXX}. For example,
8729 @code{\[char97]} is identical to the letter @code{a} if @acronym{ASCII}
8730 encoding is active.}
8732 If @var{name} is undefined, a warning of type @samp{char} is generated,
8733 and the escape is ignored. @xref{Debugging}, for information about
8736 groff resolves @code{\[...]} with more than a single component as
8741 Any component which is found in the GGL will be converted to the
8742 @code{u@var{XXXX}} form.
8745 Any component @code{u@var{XXXX}} which is found in the list of
8746 decomposable glyphs will be decomposed.
8749 The resulting elements are then concatenated with @samp{_} inbetween,
8750 dropping the leading @samp{u} in all elements but the first.
8753 No check for the existence of any component (similar to @code{tr}
8754 request) will be done.
8760 @samp{A} maps to @code{u0041}, @samp{ho} maps to @code{u02DB}, thus the
8761 final glyph name would be @code{u0041_02DB}. Note this is not the
8762 expected result: The ogonek glyph @samp{ho} is a spacing ogonek, but for
8763 a proper composite a non-spacing ogonek (U+0328) is necessary. Looking
8764 into the file @file{composite.tmac} one can find @w{@samp{.composite ho
8765 u0328}} which changes the mapping of @samp{ho} while a composite glyph
8766 name is constructed, causing the final glyph name to be
8773 @samp{^E} maps to @code{u0045_0302}, thus the final glyph name is
8774 @code{u0045_0302_0301} in all forms (assuming proper calls of the
8775 @code{composite} request).
8778 It is not possible to define glyphs with names like @w{@samp{A ho}}
8779 within a groff font file. This is not really a limitation; instead, you
8780 have to define @code{u0041_0328}.
8783 @Defesc {\\C, ', xxx, '}
8784 @cindex named character (@code{\C})
8785 @cindex character, named (@code{\C})
8786 Typeset the glyph named @var{xxx}.@footnote{@code{\C} is actually a
8787 misnomer since it accesses an output glyph.} Normally it is more
8788 convenient to use @code{\[@var{xxx}]}, but @code{\C} has the advantage
8789 that it is compatible with newer versions of @acronym{AT&T}
8790 @code{troff} and is available in compatibility mode.
8793 @Defreq {composite, from to}
8794 @pindex composite.tmac
8795 Map glyph name @var{from} to glyph name @var{to} if it is used in
8796 @code{\[...]} with more than one component. See above for examples.
8798 This mapping is based on glyph names only; no check for the existence of
8799 either glyph is done.
8801 A set of default mappings for many accents can be found in the file
8802 @file{composite.tmac} which is loaded at start-up.
8805 @Defesc {\\N, ', n, '}
8806 @cindex numbered glyph (@code{\N})
8807 @cindex glyph, numbered (@code{\N})
8808 @cindex @code{char} request, used with @code{\N}
8810 Typeset the glyph with code@tie{}@var{n} in the current font
8811 (@code{n}@tie{}is @strong{not} the input character code). The
8812 number @var{n}@tie{}can be any non-negative decimal integer. Most devices
8813 only have glyphs with codes between 0 and@tie{}255; the Unicode
8814 output device uses codes in the range 0--65535. If the current
8815 font does not contain a glyph with that code, special fonts are
8816 @emph{not} searched. The @code{\N} escape sequence can be
8817 conveniently used in conjunction with the @code{char} request:
8820 .char \[phone] \f[ZD]\N'37'
8825 @cindex unnamed glyphs
8826 @cindex glyphs, unnamed
8827 The code of each glyph is given in the fourth column in the font
8828 description file after the @code{charset} command. It is possible to
8829 include unnamed glyphs in the font description file by using a
8830 name of @samp{---}; the @code{\N} escape sequence is the only way to
8833 No kerning is applied to glyphs accessed with @code{\N}.
8836 Some escape sequences directly map onto special glyphs.
8839 This is a backslash followed by the apostrophe character, @acronym{ASCII}
8840 character @code{0x27} (@acronym{EBCDIC} character @code{0x7D}). The same
8841 as @code{\[aa]}, the acute accent.
8845 This is a backslash followed by @acronym{ASCII} character @code{0x60}
8846 (@acronym{EBCDIC} character @code{0x79} usually). The same as
8847 @code{\[ga]}, the grave accent.
8851 This is the same as @code{\[-]}, the minus sign in the current font.
8854 @Defreq {cflags, n c1 c2 @dots{}}
8855 @cindex glyph properties (@code{cflags})
8856 @cindex character properties (@code{cflags})
8857 @cindex properties of glyphs (@code{cflags})
8858 @cindex properties of characters (@code{cflags})
8859 Input characters and symbols have certain properties associated
8860 with it.@footnote{Note that the output glyphs themselves don't have
8861 such properties. For @code{gtroff}, a glyph is a numbered box with
8862 a given width, depth, and height, nothing else. All manipulations
8863 with the @code{cflags} request work on the input level.} These
8864 properties can be modified with the @code{cflags} request. The
8865 first argument is the sum of the desired flags and the remaining
8866 arguments are the characters or symbols to have those properties.
8867 It is possible to omit the spaces between the characters or symbols.
8871 @cindex end-of-sentence characters
8872 @cindex characters, end-of-sentence
8873 The character ends sentences (initially characters @samp{.?!} have this
8877 @cindex hyphenating characters
8878 @cindex characters, hyphenation
8879 Lines can be broken before the character (initially no characters have
8883 @cindex @code{hy} glyph, and @code{cflags}
8884 @cindex @code{em} glyph, and @code{cflags}
8885 Lines can be broken after the character (initially the character
8886 @samp{-} and the symbols @samp{\[hy]} and @samp{\[em]} have this property).
8889 @cindex overlapping characters
8890 @cindex characters, overlapping
8891 @cindex @code{ul} glyph, and @code{cflags}
8892 @cindex @code{rn} glyph, and @code{cflags}
8893 @cindex @code{ru} glyph, and @code{cflags}
8894 @cindex @code{radicalex} glyph, and @code{cflags}
8895 @cindex @code{sqrtex} glyph, and @code{cflags}
8896 The character overlaps horizontally if used as a horizontal line building
8897 element. Initially the symbols @samp{\[ul]}, @samp{\[rn]}, @samp{\[ru]},
8898 @samp{\[radicalex]}, and @samp{\[sqrtex]} have this property.
8901 @cindex @code{br} glyph, and @code{cflags}
8902 The character overlaps vertically if used as vertical line building element.
8903 Initially symbol @samp{\[br]} has this property.
8906 @cindex transparent characters
8907 @cindex character, transparent
8908 @cindex @code{"}, at end of sentence
8909 @cindex @code{'}, at end of sentence
8910 @cindex @code{)}, at end of sentence
8911 @cindex @code{]}, at end of sentence
8912 @cindex @code{*}, at end of sentence
8913 @cindex @code{dg} glyph, at end of sentence
8914 @cindex @code{rq} glyph, at end of sentence
8915 An end-of-sentence character followed by any number of characters with
8916 this property is treated as the end of a sentence if followed by a
8917 newline or two spaces; in other words the character is
8918 @dfn{transparent} for the purposes of end-of-sentence recognition --
8919 this is the same as having a zero space factor in @TeX{} (initially
8920 characters @samp{"')]*} and the symbols @samp{\[dg]} and @samp{\[rq]} have
8925 @DefreqList {char, g [@Var{string}]}
8926 @DefreqItem {fchar, g [@Var{string}]}
8927 @DefreqItem {fschar, f g [@Var{string}]}
8928 @DefreqListEnd {schar, g [@Var{string}]}
8929 @cindex defining character (@code{char})
8930 @cindex defining fallback character (@code{fchar}, @code{fschar}, @code{schar})
8931 @cindex character, defining (@code{char})
8932 @cindex character, defining fallback (@code{fchar}, @code{fschar}, @code{schar})
8933 @cindex fallback character, defining (@code{fchar}, @code{fschar}, @code{schar})
8934 @cindex creating new characters (@code{char})
8935 @cindex defining symbol (@code{char})
8936 @cindex symbol, defining (@code{char})
8937 @cindex defining glyph (@code{char})
8938 @cindex glyph, defining (@code{char})
8939 @cindex escape character, while defining glyph
8940 @cindex character, escape, while defining glyph
8941 @cindex @code{tr} request, and glyph definitions
8942 @cindex @code{cp} request, and glyph definitions
8943 @cindex @code{rc} request, and glyph definitions
8944 @cindex @code{lc} request, and glyph definitions
8945 @cindex @code{\l}, and glyph definitions
8946 @cindex @code{\L}, and glyph definitions
8947 @cindex @code{\&}, and glyph definitions
8948 @cindex @code{\e}, and glyph definitions
8949 @cindex @code{hcode} request, and glyph definitions
8950 Define a new glyph@tie{}@var{g} to be @var{string} (which can be
8951 empty).@footnote{@code{char} is a misnomer since an output glyph is
8952 defined.} Every time glyph@tie{}@var{g} needs to be printed,
8953 @var{string} is processed in a temporary environment and the result is
8954 wrapped up into a single object. Compatibility mode is turned off and
8955 the escape character is set to @samp{\} while @var{string} is being
8956 processed. Any emboldening, constant spacing or track kerning is
8957 applied to this object rather than to individual characters in
8960 A glyph defined by these requests can be used just
8961 like a normal glyph provided by the output device. In particular,
8962 other characters can be translated to it with the @code{tr} or
8963 @code{trin} requests; it can be made the leader character by the
8964 @code{lc} request; repeated patterns can be drawn with the glyph
8965 using the @code{\l} and @code{\L} escape sequences; words containing
8966 the glyph can be hyphenated correctly if the @code{hcode} request
8967 is used to give the glyph's symbol a hyphenation code.
8969 There is a special anti-recursion feature: Use of @code{g} within
8970 the glyph's definition is handled like normal characters and symbols
8971 not defined with @code{char}.
8973 Note that the @code{tr} and @code{trin} requests take precedence if
8974 @code{char} accesses the same symbol.
8988 The @code{fchar} request defines a fallback glyph:
8989 @code{gtroff} only checks for glyphs defined with @code{fchar}
8990 if it cannot find the glyph in the current font.
8991 @code{gtroff} carries out this test before checking special fonts.
8993 @code{fschar} defines a fallback glyph for font@tie{}@var{f}: @code{gtroff}
8994 checks for glyphs defined with @code{fschar} after the list of fonts
8995 declared as font-specific special fonts with the @code{fspecial} request,
8996 but before the list of fonts declared as global special fonts with the
8997 @code{special} request.
8999 Finally, the @code{schar} request defines a global fallback glyph:
9000 @code{gtroff} checks for glyphs defined with @code{schar} after the list
9001 of fonts declared as global special fonts with the @code{special} request,
9002 but before the already mounted special fonts.
9004 @xref{Using Symbols}, for a detailed description of the glyph
9005 searching mechanism in @code{gtroff}.
9008 @DefreqList {rchar, c1 c2 @dots{}}
9009 @DefreqListEnd {rfschar, f c1 c2 @dots{}}
9010 @cindex removing glyph definition (@code{rchar}, @code{rfschar})
9011 @cindex glyph, removing definition (@code{rchar}, @code{rfschar})
9012 @cindex fallback glyph, removing definition (@code{rchar}, @code{rfschar})
9013 Remove the definitions of glyphs @var{c1}, @var{c2},@tie{}@enddots{}
9014 This undoes the effect of a @code{char}, @code{fchar}, or
9015 @code{schar} request.
9017 It is possible to omit the whitespace between arguments.
9019 The request @code{rfschar} removes glyph definitions defined with
9020 @code{fschar} for glyph@tie{}f.
9023 @xref{Special Characters}.
9025 @c ---------------------------------------------------------------------
9027 @node Special Fonts, Artificial Fonts, Using Symbols, Fonts and Symbols
9028 @subsection Special Fonts
9029 @cindex special fonts
9030 @cindex fonts, special
9032 Special fonts are those that @code{gtroff} searches
9033 when it cannot find the requested glyph in the current font.
9034 The Symbol font is usually a special font.
9036 @code{gtroff} provides the following two requests to add more special
9037 fonts. @xref{Using Symbols}, for a detailed description of the glyph
9038 searching mechanism in @code{gtroff}.
9040 Usually, only non-TTY devices have special fonts.
9042 @DefreqList {special, [@Var{s1} @Var{s2} @dots{}]}
9043 @DefreqListEnd {fspecial, f [@Var{s1} @Var{s2} @dots{}]}
9046 Use the @code{special} request to define special fonts. Initially, this
9049 Use the @code{fspecial} request to designate special fonts only when
9050 font@tie{}@var{f} is active. Initially, this list is empty.
9052 Previous calls to @code{special} or @code{fspecial} are overwritten;
9053 without arguments, the particular list of special fonts is set to empty.
9054 Special fonts are searched in the order they appear as arguments.
9056 All fonts which appear in a call to @code{special} or @code{fspecial} are
9059 @xref{Using Symbols}, for the exact search order of glyphs.
9062 @c ---------------------------------------------------------------------
9064 @node Artificial Fonts, Ligatures and Kerning, Special Fonts, Fonts and Symbols
9065 @subsection Artificial Fonts
9066 @cindex artificial fonts
9067 @cindex fonts, artificial
9069 There are a number of requests and escapes for artificially creating
9070 fonts. These are largely vestiges of the days when output devices
9071 did not have a wide variety of fonts, and when @code{nroff} and
9072 @code{troff} were separate programs. Most of them are no longer
9073 necessary in GNU @code{troff}. Nevertheless, they are supported.
9075 @DefescList {\\H, ', height, '}
9076 @DefescItem {\\H, ', @t{+}height, '}
9077 @DefescItem {\\H, ', @t{-}height, '}
9078 @DefregListEnd {.height}
9079 @cindex changing the font height (@code{\H})
9080 @cindex font height, changing (@code{\H})
9081 @cindex height, font, changing (@code{\H})
9082 Change (increment, decrement) the height of the current font, but not
9083 the width. If @var{height} is zero, restore the original height.
9084 Default scaling indicator is @samp{z}.
9086 The read-only number register @code{.height} contains the font height as
9089 Currently, only the @option{-Tps} device supports this feature.
9091 Note that @code{\H} doesn't produce an input token in @code{gtroff}.
9092 As a consequence, it can be used in requests like @code{mc} (which
9093 expects a single character as an argument) to change the font on
9100 In compatibility mode, @code{gtroff} behaves differently: If an
9101 increment or decrement is used, it is always taken relative to the
9102 current point size and not relative to the previously selected font
9107 \H'+5'test \H'+5'test
9111 prints the word @samp{test} twice with the same font height (five
9112 points larger than the current font size).
9115 @DefescList {\\S, ', slant, '}
9116 @DefregListEnd {.slant}
9117 @cindex changing the font slant (@code{\S})
9118 @cindex font slant, changing (@code{\S})
9119 @cindex slant, font, changing (@code{\S})
9120 Slant the current font by @var{slant} degrees. Positive values slant
9121 to the right. Only integer values are possible.
9123 The read-only number register @code{.slant} contains the font slant as
9126 Currently, only the @option{-Tps} device supports this feature.
9128 Note that @code{\S} doesn't produce an input token in @code{gtroff}.
9129 As a consequence, it can be used in requests like @code{mc} (which
9130 expects a single character as an argument) to change the font on
9137 This request is incorrectly documented in the original @acronym{UNIX}
9138 troff manual; the slant is always set to an absolute value.
9141 @Defreq {ul, [@Var{lines}]}
9142 @cindex underlining (@code{ul})
9143 The @code{ul} request normally underlines subsequent lines if a TTY
9144 output device is used. Otherwise, the lines are printed in italics
9145 (only the term `underlined' is used in the following). The single
9146 argument is the number of input lines to be underlined; with no
9147 argument, the next line is underlined. If @var{lines} is zero or
9148 negative, stop the effects of @code{ul} (if it was active). Requests
9149 and empty lines do not count for computing the number of underlined
9150 input lines, even if they produce some output like @code{tl}. Lines
9151 inserted by macros (e.g.@: invoked by a trap) do count.
9153 At the beginning of @code{ul}, the current font is stored and the
9154 underline font is activated. Within the span of a @code{ul} request,
9155 it is possible to change fonts, but after the last line affected by
9156 @code{ul} the saved font is restored.
9158 This number of lines still to be underlined is associated with the
9159 current environment (@pxref{Environments}). The underline font can be
9160 changed with the @code{uf} request.
9162 @c XXX @xref should be changed to grotty
9164 @c @xref{Troff and Nroff Mode}, for a discussion how underlining is
9165 @c implemented in for TTY output devices, and which problems can arise.
9167 The @code{ul} request does not underline spaces.
9170 @Defreq {cu, [@Var{lines}]}
9171 @cindex continuous underlining (@code{cu})
9172 @cindex underlining, continuous (@code{cu})
9173 The @code{cu} request is similar to @code{ul} but underlines spaces as
9174 well (if a TTY output device is used).
9178 @cindex underline font (@code{uf})
9179 @cindex font for underlining (@code{uf})
9180 Set the underline font (globally) used by @code{ul} and @code{cu}. By
9181 default, this is the font at position@tie{}2. @var{font} can be either
9182 a non-negative font position or the name of a font.
9185 @DefreqList {bd, font [@Var{offset}]}
9186 @DefreqItem {bd, font1 font2 [@Var{offset}]}
9188 @cindex imitating bold face (@code{bd})
9189 @cindex bold face, imitating (@code{bd})
9190 Artificially create a bold font by printing each glyph twice,
9193 Two syntax forms are available.
9197 Imitate a bold font unconditionally. The first argument specifies the
9198 font to embolden, and the second is the number of basic units, minus
9199 one, by which the two glyphs are offset. If the second argument is
9200 missing, emboldening is turned off.
9202 @var{font} can be either a non-negative font position or the name of a
9205 @var{offset} is available in the @code{.b} read-only register if a
9206 special font is active; in the @code{bd} request, its default unit is
9209 @cindex @code{fspecial} request, and imitating bold
9211 @cindex embolding of special fonts
9212 @cindex special fonts, emboldening
9214 Imitate a bold form conditionally. Embolden @var{font1} by
9215 @var{offset} only if font @var{font2} is the current font. This
9216 command can be issued repeatedly to set up different emboldening
9217 values for different current fonts. If the second argument is
9218 missing, emboldening is turned off for this particular current font.
9220 This affects special fonts only (either set up with the @code{special}
9221 command in font files or with the @code{fspecial} request).
9225 @Defreq {cs, font [@Var{width} [@Var{em-size}]]}
9226 @cindex constant glyph space mode (@code{cs})
9227 @cindex mode for constant glyph space (@code{cs})
9228 @cindex glyph, constant space
9229 @cindex @code{ps} request, and constant glyph space mode
9230 Switch to and from @dfn{constant glyph space mode}. If activated, the
9231 width of every glyph is @math{@var{width}/36} ems. The em size is
9232 given absolutely by @var{em-size}; if this argument is missing, the em
9233 value is taken from the current font size (as set with the @code{ps}
9234 request) when the font is effectively in use. Without second and
9235 third argument, constant glyph space mode is deactivated.
9237 Default scaling indicator for @var{em-size} is @samp{z}; @var{width} is
9241 @c ---------------------------------------------------------------------
9243 @node Ligatures and Kerning, , Artificial Fonts, Fonts and Symbols
9244 @subsection Ligatures and Kerning
9245 @cindex ligatures and kerning
9246 @cindex kerning and ligatures
9248 Ligatures are groups of characters that are run together, i.e, producing
9249 a single glyph. For example, the letters `f' and `i' can form a
9250 ligature `fi' as in the word `file'. This produces a cleaner look
9251 (albeit subtle) to the printed output. Usually, ligatures are not
9252 available in fonts for TTY output devices.
9254 Most @sc{PostScript} fonts support the fi and fl ligatures. The C/A/T
9255 typesetter that was the target of @acronym{AT&T} @code{troff} also
9256 supported `ff', `ffi', and `ffl' ligatures. Advanced typesetters or
9257 `expert' fonts may include ligatures for `ft' and `ct', although GNU
9258 @code{troff} does not support these (yet).
9260 Only the current font is checked for ligatures and kerns; neither special
9261 fonts nor entities defined with the @code{char} request (and its siblings)
9262 are taken into account.
9264 @DefreqList {lg, [@Var{flag}]}
9265 @DefregListEnd {.lg}
9266 @cindex activating ligatures (@code{lg})
9267 @cindex ligatures, activating (@code{lg})
9268 @cindex ligatures enabled register (@code{.lg})
9269 Switch the ligature mechanism on or off; if the parameter is non-zero
9270 or missing, ligatures are enabled, otherwise disabled. Default is on.
9271 The current ligature mode can be found in the read-only number register
9272 @code{.lg} (set to 1 or@tie{}2 if ligatures are enabled, 0@tie{}otherwise).
9274 Setting the ligature mode to@tie{}2 enables the two-character ligatures
9275 (fi, fl, and ff) and disables the three-character ligatures (ffi and
9279 @dfn{Pairwise kerning} is another subtle typesetting mechanism that
9280 modifies the distance between a glyph pair to improve readability.
9281 In most cases (but not always) the distance is decreased.
9283 For example, compare the combination of the letters `V' and `A'. With
9284 kerning, `VA' is printed. Without kerning it appears as `V@w{}A'.
9286 Typewriter-like fonts and fonts for terminals where all glyphs
9287 have the same width don't use kerning.
9289 @DefreqList {kern, [@Var{flag}]}
9290 @DefregListEnd {.kern}
9291 @cindex activating kerning (@code{kern})
9292 @cindex kerning, activating (@code{kern})
9293 @cindex kerning enabled register (@code{.kern})
9294 Switch kerning on or off. If the parameter is non-zero or missing,
9295 enable pairwise kerning, otherwise disable it. The read-only number
9296 register @code{.kern} is set to@tie{}1 if pairwise kerning is enabled,
9299 @cindex zero width space character (@code{\&})
9300 @cindex character, zero width space (@code{\&})
9301 @cindex space character, zero width (@code{\&})
9302 If the font description file contains pairwise kerning information,
9303 glyphs from that font are kerned. Kerning between two glyphs
9304 can be inhibited by placing @code{\&} between them: @samp{V\&A}.
9306 @xref{Font File Format}.
9309 @cindex track kerning
9310 @cindex kerning, track
9311 @dfn{Track kerning} expands or reduces the space between glyphs.
9312 This can be handy, for example, if you need to squeeze a long word
9313 onto a single line or spread some text to fill a narrow column. It
9314 must be used with great care since it is usually considered bad
9315 typography if the reader notices the effect.
9317 @Defreq {tkf, f s1 n1 s2 n2}
9318 @cindex activating track kerning (@code{tkf})
9319 @cindex track kerning, activating (@code{tkf})
9320 Enable track kerning for font@tie{}@var{f}. If the current font
9321 is@tie{}@var{f} the width of every glyph is increased by an amount
9322 between @var{n1} and @var{n2} (@var{n1}, @var{n2} can be negative); if
9323 the current point size is less than or equal to @var{s1} the width is
9324 increased by @var{n1}; if it is greater than or equal to @var{s2} the
9325 width is increased by @var{n2}; if the point size is greater than or
9326 equal to @var{s1} and less than or equal to @var{s2} the increase in
9327 width is a linear function of the point size.
9329 The default scaling indicator is @samp{z} for @var{s1} and @var{s2},
9330 @samp{p} for @var{n1} and @var{n2}.
9332 Note that the track kerning amount is added even to the rightmost glyph
9333 in a line; for large values it is thus recommended to increase the line
9334 length by the same amount to compensate it.
9337 Sometimes, when typesetting letters of different fonts, more or less
9338 space at such boundaries are needed. There are two escapes to help
9342 @cindex italic correction (@code{\/})
9343 @cindex correction, italic (@code{\/})
9344 @cindex correction between italic and roman glyph (@code{\/}, @code{\,})
9345 @cindex roman glyph, correction after italic glyph (@code{\/})
9346 @cindex italic glyph, correction before roman glyph (@code{\/})
9347 @cindex glyph, italic correction (@code{\/})
9348 Increase the width of the preceding glyph so that the spacing
9349 between that glyph and the following glyph is correct if the
9350 following glyph is a roman glyph. For example, if an
9351 italic@tie{}@code{f} is immediately followed by a roman right
9352 parenthesis, then in many fonts the top right portion of the@tie{}@code{f}
9353 overlaps the top left of the right parenthesis. Use this escape
9354 sequence whenever an italic glyph is immediately followed by a
9355 roman glyph without any intervening space. This small amount of
9356 space is also called @dfn{italic correction}.
9362 @result{} {@it f}@r{)}
9364 @result{} @i{f}@r{)}
9370 @Defesc {\\\,, , , }
9371 @cindex left italic correction (@code{\,})
9372 @cindex correction, left italic (@code{\,})
9373 @cindex glyph, left italic correction (@code{\,})
9374 @cindex roman glyph, correction before italic glyph (@code{\,})
9375 @cindex italic glyph, correction after roman glyph (@code{\,})
9376 Modify the spacing of the following glyph so that the spacing
9377 between that glyph and the preceding glyph is correct if the
9378 preceding glyph is a roman glyph. Use this escape sequence
9379 whenever a roman glyph is immediately followed by an italic
9380 glyph without any intervening space. In analogy to above, this
9381 space could be called @dfn{left italic correction}, but this term
9388 @result{} @r{q}@i{f}
9390 @result{} @r{q}@math{@ptexcomma}@i{f}
9397 Insert a zero-width character, which is invisible. Its intended use
9398 is to stop interaction of a character with its surrounding.
9402 It prevents the insertion of extra space after an end-of-sentence
9408 @result{} Test. Test.
9411 @result{} Test. Test.
9415 It prevents interpretation of a control character at the beginning of
9420 @result{} warning: `Test' not defined
9426 It prevents kerning between two glyphs.
9434 @result{} @r{V@w{}A}
9440 It is needed to map an arbitrary character to nothing in the @code{tr}
9441 request (@pxref{Character Translations}).
9446 This escape is similar to @code{\&} except that it behaves like a
9447 character declared with the @code{cflags} request to be transparent
9448 for the purposes of an end-of-sentence character.
9450 Its main usage is in macro definitions to protect against arguments
9451 starting with a control character.
9463 @result{}This is a test.' This is a test.
9467 @result{}This is a test.' This is a test.
9472 @c =====================================================================
9474 @node Sizes, Strings, Fonts and Symbols, gtroff Reference
9480 @cindex size of type
9481 @cindex vertical spacing
9482 @cindex spacing, vertical
9483 @code{gtroff} uses two dimensions with each line of text, type size
9484 and vertical spacing. The @dfn{type size} is approximately the height
9485 of the tallest glyph.@footnote{This is usually the parenthesis.
9486 Note that in most cases the real dimensions of the glyphs in a font
9487 are @emph{not} related to its type size! For example, the standard
9488 @sc{PostScript} font families `Times Roman', `Helvetica', and
9489 `Courier' can't be used together at 10@dmn{pt}; to get acceptable
9490 output, the size of `Helvetica' has to be reduced by one point, and
9491 the size of `Courier' must be increased by one point.} @dfn{Vertical
9492 spacing} is the amount of space @code{gtroff} allows for a line of
9493 text; normally, this is about 20%@tie{}larger than the current type
9494 size. Ratios smaller than this can result in hard-to-read text;
9495 larger than this, it spreads the text out more vertically (useful for
9496 term papers). By default, @code{gtroff} uses 10@tie{}point type on
9497 12@tie{}point spacing.
9500 The difference between type size and vertical spacing is known, by
9501 typesetters, as @dfn{leading} (this is pronounced `ledding').
9504 * Changing Type Sizes::
9505 * Fractional Type Sizes::
9508 @c ---------------------------------------------------------------------
9510 @node Changing Type Sizes, Fractional Type Sizes, Sizes, Sizes
9511 @subsection Changing Type Sizes
9513 @DefreqList {ps, [@Var{size}]}
9514 @DefreqItem {ps, @t{+}@Var{size}}
9515 @DefreqItem {ps, @t{-}@Var{size}}
9516 @DefescItem {\\s, , size, }
9518 @cindex changing type sizes (@code{ps}, @code{\s})
9519 @cindex type sizes, changing (@code{ps}, @code{\s})
9520 @cindex point sizes, changing (@code{ps}, @code{\s})
9521 Use the @code{ps} request or the @code{\s} escape to change (increase,
9522 decrease) the type size (in points). Specify @var{size} as either an
9523 absolute point size, or as a relative change from the current size.
9524 The size@tie{}0, or no argument, goes back to the previous size.
9526 Default scaling indicator of @code{size} is @samp{z}. If @code{size}
9527 is zero or negative, it is set to 1@dmn{u}.
9529 @cindex type size registers (@code{.s}, @code{.ps})
9530 @cindex point size registers (@code{.s}, @code{.ps})
9531 The read-only number register @code{.s} returns the point size in
9532 points as a decimal fraction. This is a string. To get the point
9533 size in scaled points, use the @code{.ps} register instead.
9535 @code{.s} is associated with the current environment
9536 (@pxref{Environments}).
9543 wink, wink, \s+2nudge, nudge,\s+8 say no more!
9547 The @code{\s} escape may be called in a variety of ways. Much like
9548 other escapes there must be a way to determine where the argument ends
9549 and the text begins. Any of the following forms are valid:
9553 Set the point size to @var{n}@tie{}points. @var{n}@tie{}must be either
9554 0 or in the range 4 to@tie{}39.
9558 Increase or decrease the point size by @var{n}@tie{}points.
9559 @var{n}@tie{}must be exactly one digit.
9562 Set the point size to @var{nn}@tie{}points. @var{nn} must be exactly
9569 Increase or decrease the point size by @var{nn}@tie{}points. @var{nn}
9570 must be exactly two digits.
9573 Note that @code{\s} doesn't produce an input token in @code{gtroff}.
9574 As a consequence, it can be used in requests like @code{mc} (which
9575 expects a single character as an argument) to change the font on
9582 @xref{Fractional Type Sizes}, for yet another syntactical form of
9583 using the @code{\s} escape.
9586 @Defreq {sizes, s1 s2 @dots{} sn [0]}
9587 Some devices may only have certain permissible sizes, in which case
9588 @code{gtroff} rounds to the nearest permissible size.
9589 The @file{DESC} file specifies which sizes are permissible for the device.
9591 Use the @code{sizes} request to change the permissible sizes
9592 for the current output device.
9593 Arguments are in scaled points;
9594 the @code{sizescale} line in the
9595 @file{DESC} file for the output device
9596 provides the scaling factor.
9597 For example, if the scaling factor is 1000,
9598 then the value 12000 is 12@tie{}points.
9600 Each argument can be a single point size (such as @samp{12000}),
9601 or a range of sizes (such as @samp{4000-72000}).
9602 You can optionally end the list with a zero.
9605 @DefreqList {vs, [@Var{space}]}
9606 @DefreqItem {vs, @t{+}@Var{space}}
9607 @DefreqItem {vs, @t{-}@Var{space}}
9609 @cindex changing vertical line spacing (@code{vs})
9610 @cindex vertical line spacing, changing (@code{vs})
9611 @cindex vertical line spacing register (@code{.v})
9612 Change (increase, decrease) the vertical spacing by @var{space}. The
9613 default scaling indicator is @samp{p}.
9615 If @code{vs} is called without an argument, the vertical spacing is
9616 reset to the previous value before the last call to @code{vs}.
9618 @cindex @code{.V} register, and @code{vs}
9619 @code{gtroff} creates a warning of type @samp{range} if @var{space} is
9620 negative; the vertical spacing is then set to smallest positive value,
9621 the vertical resolution (as given in the @code{.V} register).
9623 Note that @w{@samp{.vs 0}} isn't saved in a diversion since it doesn't
9624 result in a vertical motion. You explicitly have to repeat this command
9625 before inserting the diversion.
9627 The read-only number register @code{.v} contains the current vertical
9628 spacing; it is associated with the current environment
9629 (@pxref{Environments}).
9632 @cindex vertical line spacing, effective value
9633 The effective vertical line spacing consists of four components. Breaking
9634 a line causes the following actions (in the given order).
9638 @cindex extra pre-vertical line space (@code{\x})
9639 @cindex line space, extra pre-vertical (@code{\x})
9640 Move the current point vertically by the @dfn{extra pre-vertical line
9641 space}. This is the minimum value of all @code{\x} escapes with a
9642 negative argument in the current output line.
9645 Move the current point vertically by the vertical line spacing as set with
9646 the @code{vs} request.
9649 Output the current line.
9652 @cindex extra post-vertical line space (@code{\x})
9653 @cindex line space, extra post-vertical (@code{\x})
9654 Move the current point vertically by the @dfn{extra post-vertical line
9655 space}. This is the maximum value of all @code{\x} escapes with a
9656 positive argument in the line which has just been output.
9659 @cindex post-vertical line spacing
9660 @cindex line spacing, post-vertical (@code{pvs})
9661 Move the current point vertically by the @dfn{post-vertical line spacing}
9662 as set with the @code{pvs} request.
9665 @cindex double-spacing (@code{vs}, @code{pvs})
9666 It is usually better to use @code{vs} or @code{pvs} instead of @code{ls}
9667 to produce double-spaced documents: @code{vs} and @code{pvs} have a finer
9668 granularity for the inserted vertical space compared to @code{ls};
9669 furthermore, certain preprocessors assume single-spacing.
9671 @xref{Manipulating Spacing}, for more details on the @code{\x} escape
9672 and the @code{ls} request.
9674 @DefreqList {pvs, [@Var{space}]}
9675 @DefreqItem {pvs, @t{+}@Var{space}}
9676 @DefreqItem {pvs, @t{-}@Var{space}}
9677 @DefregListEnd {.pvs}
9678 @cindex @code{ls} request, alternative to (@code{pvs})
9679 @cindex post-vertical line spacing, changing (@code{pvs})
9680 @cindex post-vertical line spacing register (@code{.pvs})
9681 Change (increase, decrease) the post-vertical spacing by
9682 @var{space}. The default scaling indicator is @samp{p}.
9684 If @code{pvs} is called without an argument, the post-vertical spacing is
9685 reset to the previous value before the last call to @code{pvs}.
9687 @code{gtroff} creates a warning of type @samp{range} if @var{space} is
9688 zero or negative; the vertical spacing is then set to zero.
9690 The read-only number register @code{.pvs} contains the current
9691 post-vertical spacing; it is associated with the current environment
9692 (@pxref{Environments}).
9695 @c ---------------------------------------------------------------------
9697 @node Fractional Type Sizes, , Changing Type Sizes, Sizes
9698 @subsection Fractional Type Sizes
9699 @cindex fractional type sizes
9700 @cindex fractional point sizes
9701 @cindex type sizes, fractional
9702 @cindex point sizes, fractional
9703 @cindex sizes, fractional
9705 @cindex @code{s} unit
9706 @cindex unit, @code{s}
9707 @cindex @code{z} unit
9708 @cindex unit, @code{z}
9709 @cindex @code{ps} request, with fractional type sizes
9710 @cindex @code{cs} request, with fractional type sizes
9711 @cindex @code{tkf} request, with fractional type sizes
9712 @cindex @code{\H}, with fractional type sizes
9713 @cindex @code{\s}, with fractional type sizes
9714 A @dfn{scaled point} is equal to @math{1/@var{sizescale}} points,
9715 where @var{sizescale} is specified in the @file{DESC} file (1@tie{}by
9716 default). There is a new scale indicator @samp{z} which has the
9717 effect of multiplying by @var{sizescale}. Requests and escape
9718 sequences in @code{gtroff} interpret arguments that represent a point
9719 size as being in units of scaled points, but they evaluate each such
9720 argument using a default scale indicator of @samp{z}. Arguments
9721 treated in this way are the argument to the @code{ps} request, the
9722 third argument to the @code{cs} request, the second and fourth
9723 arguments to the @code{tkf} request, the argument to the @code{\H}
9724 escape sequence, and those variants of the @code{\s} escape sequence
9725 that take a numeric expression as their argument (see below).
9727 For example, suppose @var{sizescale} is@tie{}1000; then a scaled point
9728 is equivalent to a millipoint; the request @w{@samp{.ps 10.25}} is
9729 equivalent to @w{@samp{.ps 10.25z}} and thus sets the point size to
9730 10250@tie{}scaled points, which is equal to 10.25@tie{}points.
9732 @code{gtroff} disallows the use of the @samp{z} scale indicator in
9733 instances where it would make no sense, such as a numeric
9734 expression whose default scale indicator was neither @samp{u} nor
9735 @samp{z}. Similarly it would make
9736 no sense to use a scaling indicator other than @samp{z} or @samp{u} in a
9737 numeric expression whose default scale indicator was @samp{z}, and so
9738 @code{gtroff} disallows this as well.
9740 There is also new scale indicator @samp{s} which multiplies by the
9741 number of units in a scaled point. So, for example, @samp{\n[.ps]s} is
9742 equal to @samp{1m}. Be sure not to confuse the @samp{s} and @samp{z}
9746 A read-only number register returning the point size in scaled points.
9748 @code{.ps} is associated with the current environment
9749 (@pxref{Environments}).
9753 @DefregListEnd {.sr}
9754 @cindex last-requested point size registers (@code{.psr}, @code{.sr})
9755 @cindex point size registers, last-requested (@code{.psr}, @code{.sr})
9756 @cindex @code{.ps} register, in comparison with @code{.psr}
9757 @cindex @code{.s} register, in comparison with @code{.sr}
9758 The last-requested point size in scaled points is contained in the
9759 @code{.psr} read-only number register. The last requested point size
9760 in points as a decimal fraction can be found in @code{.sr}. This is a
9761 string-valued read-only number register.
9763 Note that the requested point sizes are device-independent, whereas
9764 the values returned by the @code{.ps} and @code{.s} registers are not.
9765 For example, if a point size of 11@dmn{pt} is requested, and a
9766 @code{sizes} request (or a @code{sizescale} line in a @file{DESC} file)
9767 specifies 10.95@dmn{pt} instead, this value is actually used.
9769 Both registers are associated with the current environment
9770 (@pxref{Environments}).
9773 The @code{\s} escape has the following syntax for working with
9774 fractional type sizes:
9779 Set the point size to @var{n}@tie{}scaled points; @var{n}@tie{}is a numeric
9780 expression with a default scale indicator of @samp{z}.
9790 Increase or or decrease the point size by @var{n}@tie{}scaled points;
9791 @var{n}@tie{}is a numeric expression with a default scale indicator of
9798 @c =====================================================================
9800 @node Strings, Conditionals and Loops, Sizes, gtroff Reference
9804 @code{gtroff} has string variables, which are entirely for user
9805 convenience (i.e.@: there are no built-in strings exept @code{.T}, but
9806 even this is a read-write string variable).
9808 @DefreqList {ds, name [@Var{string}]}
9809 @DefreqItem {ds1, name [@Var{string}]}
9810 @DefescItem {\\*, , n, }
9811 @DefescItem {\\*, @lparen{}, nm, }
9812 @DefescListEnd {\\*, @lbrack{}, name arg1 arg2 @dots{}, @rbrack{}}
9813 @cindex string interpolation (@code{\*})
9814 @cindex string expansion (@code{\*})
9815 @cindex interpolation of strings (@code{\*})
9816 @cindex expansion of strings (@code{\*})
9817 @cindex string arguments
9818 @cindex arguments, of strings
9819 Define and access a string variable @var{name} (one-character
9820 name@tie{}@var{n}, two-character name @var{nm}). If @var{name} already
9821 exists, @code{ds} overwrites the previous definition. Only the syntax form
9822 using brackets can take arguments which are handled identically to
9823 macro arguments; the single exception is that a closing bracket as an
9824 argument must be enclosed in double quotes. @xref{Request and Macro
9825 Arguments}, and @ref{Parameters}.
9832 This is \*[foo nice].
9833 @result{} This is a nice test.
9836 The @code{\*} escape @dfn{interpolates} (expands in-place) a
9837 previously-defined string variable. To be more precise, the stored
9838 string is pushed onto the input stack which is then parsed by
9839 @code{gtroff}. Similar to number registers, it is possible to nest
9840 strings, i.e. string variables can be called within string variables.
9842 If the string named by the @code{\*} escape does not exist, it is
9843 defined as empty, and a warning of type @samp{mac} is emitted (see
9844 @ref{Debugging}, for more details).
9846 @cindex comments, with @code{ds}
9847 @cindex @code{ds} request, and comments
9848 @strong{Caution:} Unlike other requests, the second argument to the
9849 @code{ds} request takes up the entire line including trailing spaces.
9850 This means that comments on a line with such a request can introduce
9851 unwanted space into a string.
9854 .ds UX \s-1UNIX\s0\u\s-3tm\s0\d \" UNIX trademark
9858 Instead the comment should be put on another line or have the comment
9859 escape adjacent with the end of the string.
9862 .ds UX \s-1UNIX\s0\u\s-3tm\s0\d\" UNIX trademark
9865 @cindex trailing quotes
9866 @cindex quotes, trailing
9867 @cindex leading spaces with @code{ds}
9868 @cindex spaces with @code{ds}
9869 @cindex @code{ds} request, and leading spaces
9870 To produce leading space the string can be started with a double
9871 quote. No trailing quote is needed; in fact, any trailing quote is
9872 included in your string.
9875 .ds sign " Yours in a white wine sauce,
9878 @cindex multi-line strings
9879 @cindex strings, multi-line
9880 @cindex newline character, in strings, escaping
9881 @cindex escaping newline characters, in strings
9882 Strings are not limited to a single line of text. A string can span
9883 several lines by escaping the newlines with a backslash. The
9884 resulting string is stored @emph{without} the newlines.
9887 .ds foo lots and lots \
9888 of text are on these \
9892 It is not possible to have real newlines in a string. To put a single
9893 double quote character into a string, use two consecutive double quote
9896 The @code{ds1} request turns off compatibility mode
9897 while interpreting a string. To be more precise, a @dfn{compatibility
9898 save} input token is inserted at the beginning of the string, and a
9899 @dfn{compatibility restore} input token at the end.
9903 .ds aa The value of xxx is \\n[xxx].
9904 .ds1 bb The value of xxx ix \\n[xxx].
9909 @result{} warning: number register `[' not defined
9910 @result{} The value of xxx is 0xxx].
9912 @result{} The value of xxx ix 12345.
9915 @cindex name space, common, of macros, diversions, and strings
9916 @cindex common name space of macros, diversions, and strings
9917 @cindex macros, shared name space with strings and diversions
9918 @cindex strings, shared name space with macros and diversions
9919 @cindex diversions, shared name space with macros and strings
9920 Strings, macros, and diversions (and boxes) share the same name space.
9921 Internally, even the same mechanism is used to store them. This has
9922 some interesting consequences. For example, it is possible to call a
9923 macro with string syntax and vice versa.
9930 @result{} This is a funny test.
9932 .ds yyy a funny test
9935 @result{} This is a funny test.
9938 Diversions and boxes can be also called with string syntax.
9940 Another consequence is that you can copy one-line diversions or boxes
9948 .ds yyy This is \*[xxx]\c
9950 @result{} @r{This is a }@i{test}.
9954 As the previous example shows, it is possible to store formatted
9955 output in strings. The @code{\c} escape prevents the insertion of an
9956 additional blank line in the output.
9958 Copying diversions longer than a single output line produces
9968 .ds yyy This is \*[xxx]\c
9970 @result{} test This is a funny.
9973 Usually, it is not predictable whether a diversion contains one or
9974 more output lines, so this mechanism should be avoided. With
9975 @acronym{UNIX} @code{troff}, this was the only solution to strip off a
9976 final newline from a diversion. Another disadvantage is that the
9977 spaces in the copied string are already formatted, making them
9978 unstretchable. This can cause ugly results.
9980 @cindex stripping final newline in diversions
9981 @cindex diversion, stripping final newline
9982 @cindex final newline, stripping in diversions
9983 @cindex newline, final, stripping in diversions
9984 @cindex horizontal space, unformatting
9985 @cindex space, horizontal, unformatting
9986 @cindex unformatting horizontal space
9987 A clean solution to this problem is available in GNU @code{troff},
9988 using the requests @code{chop} to remove the final newline of a
9989 diversion, and @code{unformat} to make the horizontal spaces
10002 @result{} This is a funny test.
10005 @xref{Gtroff Internals}, for more information.
10008 @DefreqList {as, name [@Var{string}]}
10009 @DefreqListEnd {as1, name [@Var{string}]}
10010 @cindex appending to a string (@code{as})
10011 @cindex string, appending (@code{as})
10012 The @code{as} request is similar to @code{ds} but appends @var{string}
10013 to the string stored as @var{name} instead of redefining it. If
10014 @var{name} doesn't exist yet, it is created.
10017 .as sign " with shallots, onions and garlic,
10020 The @code{as1} request is similar to @code{as}, but compatibility mode
10021 is switched off while the appended string is interpreted. To be more
10022 precise, a @dfn{compatibility save} input token is inserted at the
10023 beginning of the appended string, and a @dfn{compatibility restore}
10024 input token at the end.
10027 Rudimentary string manipulation routines are given with the next two
10030 @Defreq {substring, str n1 [@Var{n2}]}
10031 @cindex substring (@code{substring})
10032 Replace the string named @var{str} with the substring
10033 defined by the indices @var{n1} and@tie{}@var{n2}. The first character
10034 in the string has index@tie{}0. If @var{n2} is omitted, it is taken to
10035 be equal to the string's length. If the index value @var{n1} or
10036 @var{n2} is negative, it is counted from the end of the
10037 string, going backwards: The last character has index@tie{}@minus{}1, the
10038 character before the last character has index@tie{}@minus{}2, etc.
10042 .substring xxx 1 -4
10048 @Defreq {length, reg str}
10049 @cindex length of a string (@code{length})
10050 @cindex string, length of (@code{length})
10051 Compute the number of characters of @var{str} and return it in the
10052 number register @var{reg}. If @var{reg} doesn't exist, it is created.
10053 @code{str} is read in copy mode.
10056 .ds xxx abcd\h'3i'efgh
10057 .length yyy \*[xxx]
10063 @Defreq {rn, xx yy}
10064 @cindex renaming request (@code{rn})
10065 @cindex request, renaming (@code{rn})
10066 @cindex renaming macro (@code{rn})
10067 @cindex macro, renaming (@code{rn})
10068 @cindex renaming string (@code{rn})
10069 @cindex string, renaming (@code{rn})
10070 @cindex renaming diversion (@code{rn})
10071 @cindex diversion, renaming (@code{rn})
10072 Rename the request, macro, diversion, or string @var{xx} to @var{yy}.
10076 @cindex removing request (@code{rm})
10077 @cindex request, removing (@code{rm})
10078 @cindex removing macro (@code{rm})
10079 @cindex macro, removing (@code{rm})
10080 @cindex removing string (@code{rm})
10081 @cindex string, removing (@code{rm})
10082 @cindex removing diversion (@code{rm})
10083 @cindex diversion, removing (@code{rm})
10084 Remove the request, macro, diversion, or string @var{xx}. @code{gtroff}
10085 treats subsequent invocations as if the object had never been defined.
10088 @Defreq {als, new old}
10089 @cindex alias, string, creating (@code{als})
10090 @cindex alias, macro, creating (@code{als})
10091 @cindex alias, diversion, creating (@code{als})
10092 @cindex creating alias, for string (@code{als})
10093 @cindex creating alias, for macro (@code{als})
10094 @cindex creating alias, for diversion (@code{als})
10095 @cindex string, creating alias (@code{als})
10096 @cindex macro, creating alias (@code{als})
10097 @cindex diversion, creating alias (@code{als})
10098 Create an alias named @var{new} for the request, string, macro, or
10099 diversion object named @var{old}. The new name and the old name are
10100 exactly equivalent (it is similar to a hard rather than a soft
10101 link). If @var{old} is undefined, @code{gtroff} generates a warning of
10102 type @samp{mac} and ignores the request.
10106 Remove (chop) the last character from the macro, string, or diversion
10107 named @var{xx}. This is useful for removing the newline from the end
10108 of diversions that are to be interpolated as strings. This command
10109 can be used repeatedly; see @ref{Gtroff Internals}, for details on
10110 nodes inserted additionally by @code{gtroff}.
10113 @xref{Identifiers}, and @ref{Comments}.
10116 @c =====================================================================
10118 @node Conditionals and Loops, Writing Macros, Strings, gtroff Reference
10119 @section Conditionals and Loops
10120 @cindex conditionals and loops
10121 @cindex loops and conditionals
10124 * Operators in Conditionals::
10129 @c ---------------------------------------------------------------------
10131 @node Operators in Conditionals, if-else, Conditionals and Loops, Conditionals and Loops
10132 @subsection Operators in Conditionals
10134 @cindex @code{if} request, operators to use with
10135 @cindex @code{while} request, operators to use with
10136 In @code{if} and @code{while} requests, there are several more
10137 operators available:
10142 True if the current page is even or odd numbered (respectively).
10145 True if the document is being processed in nroff mode (i.e., the
10146 @code{.nroff} command has been issued).
10149 True if the document is being processed in troff mode (i.e., the
10150 @code{.troff} command has been issued).
10153 Always false. This condition is for compatibility with other
10154 @code{troff} versions only (identifying a @code{-Tversatec} device).
10156 @item '@var{xxx}'@var{yyy}'
10157 True if the string @var{xxx} is equal to the string @var{yyy}. Other
10158 characters can be used in place of the single quotes; the same set of
10159 delimiters as for the @code{\D} escape is used (@pxref{Escapes}).
10160 @code{gtroff} formats the strings before being compared:
10171 The resulting motions, glyph sizes, and fonts have to
10172 match,@footnote{The created output nodes must be identical.
10173 @xref{Gtroff Internals}.} and not the individual motion, size, and
10174 font requests. In the previous example, @samp{|} and @samp{\fR|\fP}
10175 both result in a roman @samp{|} glyph with the same point size and
10176 at the same location on the page, so the strings are equal. If
10177 @samp{.ft@tie{}I} had been added before the @samp{.ie}, the result
10178 would be ``false'' because (the first) @samp{|} produces an italic
10179 @samp{|} rather than a roman one.
10182 True if there is a number register named @var{xxx}.
10185 True if there is a string, macro, diversion, or request named @var{xxx}.
10188 True if there is a color named @var{xxx}.
10191 True if there is a glyph @var{g} available@footnote{The name of this
10192 conditional operator is a misnomer since it tests names of output
10193 glyphs.}; @var{g} is either an @acronym{ASCII} character or a special
10194 character (@code{\(@var{gg}} or @code{\[@var{ggg}]}); the condition
10195 is also true if @var{g} has been defined by the @code{char} request.
10198 Note that these operators can't be combined with other operators like
10199 @samp{:} or @samp{&}; only a leading @samp{!} (without whitespace
10200 between the exclamation mark and the operator) can be used to negate
10212 A whitespace after @samp{!} always evaluates to zero (this bizarre
10213 behaviour is due to compatibility with @acronym{UNIX} @code{troff}).
10221 @result{} r xxx true
10224 It is possible to omit the whitespace before the argument to the
10225 @samp{r}, @samp{d}, and @samp{c} operators.
10227 @xref{Expressions}.
10229 @c ---------------------------------------------------------------------
10231 @node if-else, while, Operators in Conditionals, Conditionals and Loops
10232 @subsection if-else
10235 @code{gtroff} has if-then-else constructs like other languages, although
10236 the formatting can be painful.
10238 @Defreq {if, expr anything}
10240 Evaluate the expression @var{expr}, and executes @var{anything} (the
10241 remainder of the line) if @var{expr} evaluates to a value greater than
10242 zero (true). @var{anything} is interpreted as though it was on a line
10243 by itself (except that leading spaces are swallowed).
10244 @xref{Expressions}, for more info.
10249 .if ((\n[xxx] == 1) & (\n[yyy] == 2)) true
10254 @Defreq{nop, anything}
10255 Executes @var{anything}.
10256 This is similar to @code{.if@tie{}1}.
10259 @DefreqList {ie, expr anything}
10260 @DefreqListEnd {el, anything}
10261 Use the @code{ie} and @code{el} requests to write an if-then-else.
10262 The first request is the `if' part and the latter is the `else' part.
10265 .ie n .ls 2 \" double-spacing in nroff
10266 .el .ls 1 \" single-spacing in troff
10270 @c there is a bug in makeinfo <= 4.1a: you can't have `@{' as an argument
10273 @c and in 4.2 you still can't use @{ in macros.
10275 @c @DefescList {\@{, , , }
10276 @c @DefescListEnd {\@}, , , }
10277 @deffn Escape @t{\@{}
10278 @deffnx Escape @t{\@}}
10281 @cindex begin of conditional block (@code{\@{})
10282 @cindex end of conditional block (@code{\@}})
10283 @cindex conditional block, begin (@code{\@{})
10284 @cindex conditional block, end (@code{\@}})
10285 @cindex block, conditional, begin (@code{\@{})
10286 @cindex block, condititional, end (@code{\@}})
10287 In many cases, an if (or if-else) construct needs to execute more than
10288 one request. This can be done using the @code{\@{} and @code{\@}}
10289 escapes. The following example shows the possible ways to use these
10290 escapes (note the position of the opening and closing braces).
10305 @xref{Expressions}.
10307 @c ---------------------------------------------------------------------
10309 @node while, , if-else, Conditionals and Loops
10313 @code{gtroff} provides a looping construct using the @code{while}
10314 request, which is used much like the @code{if} (and related) requests.
10316 @Defreq {while, expr anything}
10317 Evaluate the expression @var{expr}, and repeatedly execute
10318 @var{anything} (the remainder of the line) until @var{expr} evaluates
10323 .while (\na < 9) \@{\
10327 @result{} 1, 2, 3, 4, 5, 6, 7, 8, 9, 10
10332 @cindex @code{de} request, and @code{while}
10335 The body of a @code{while} request is treated like the body of a
10336 @code{de} request: @code{gtroff} temporarily stores it in a macro
10337 which is deleted after the loop has been exited. It can considerably
10338 slow down a macro if the body of the @code{while} request (within the
10339 macro) is large. Each time the macro is executed, the @code{while}
10340 body is parsed and stored again as a temporary macro.
10345 . while (\\n[num] > 0) \@{\
10346 . \" many lines of code
10352 @cindex recursive macros
10353 @cindex macros, recursive
10355 The traditional and ofter better solution (@acronym{UNIX} @code{troff}
10356 doesn't have the @code{while} request) is to use a recursive macro
10357 instead which is parsed only once during its definition.
10361 . if (\\n[num] > 0) \@{\
10362 . \" many lines of code
10375 Note that the number of available recursion levels is set to@tie{}1000
10376 (this is a compile-time constant value of @code{gtroff}).
10379 The closing brace of a @code{while} body must end a line.
10384 . while (\n[a] < 10) \@{\
10387 @result{} unbalanced \@{ \@}
10393 @cindex @code{while} request, confusing with @code{br}
10394 @cindex @code{break} request, in a @code{while} loop
10395 @cindex @code{continue} request, in a @code{while} loop
10396 Break out of a @code{while} loop. Be sure not to confuse this with
10397 the @code{br} request (causing a line break).
10400 @Defreq {continue, }
10401 Finish the current iteration of a @code{while} loop, immediately
10402 restarting the next iteration.
10405 @xref{Expressions}.
10408 @c =====================================================================
10410 @node Writing Macros, Page Motions, Conditionals and Loops, gtroff Reference
10411 @section Writing Macros
10412 @cindex writing macros
10413 @cindex macros, writing
10415 A @dfn{macro} is a collection of text and embedded commands which can
10416 be invoked multiple times. Use macros to define common operations.
10418 @DefreqList {de, name [@Var{end}]}
10419 @DefreqItem {de1, name [@Var{end}]}
10420 @DefreqItem {dei, name [@Var{end}]}
10421 @DefreqListEnd {dei1, name [@Var{end}]}
10422 Define a new macro named @var{name}. @code{gtroff} copies subsequent
10423 lines (starting with the next one) into an internal buffer until it
10424 encounters the line @samp{..} (two dots). The optional second
10425 argument to @code{de} changes this to a macro to @samp{.@var{end}}.
10427 There can be whitespace after the first dot in the line containing the
10428 ending token (either @samp{.} or macro @samp{@var{end}}).
10430 Here a small example macro called @samp{P} which causes a break and
10431 inserts some vertical space. It could be used to separate paragraphs.
10440 The following example defines a macro within another. Remember that
10441 expansion must be protected twice; once for reading the macro and
10442 once for executing.
10445 \# a dummy macro to avoid a warning
10451 . nop \f[B]Hallo \\\\$1!\f[]
10457 @result{} @b{Hallo Joe!}
10461 Since @code{\f} has no expansion, it isn't necessary to protect its
10462 backslash. Had we defined another macro within @code{bar} which takes
10463 a parameter, eight backslashes would be necessary before @samp{$1}.
10465 The @code{de1} request turns off compatibility mode
10466 while executing the macro. On entry, the current compatibility mode
10467 is saved and restored at exit.
10473 The value of xxx is \\n[xxx].
10476 The value of xxx ix \\n[xxx].
10482 @result{} warning: number register
\e' not defined
10483 @result{} The value of xxx is 0xxx].
10485 @result{} The value of xxx ix 12345.
10488 The @code{dei} request defines a macro indirectly.
10489 That is, it expands strings whose names
10490 are @var{name} or @var{end} before performing the append.
10507 The @code{dei1} request is similar to @code{dei} but with compatibility
10508 mode switched off during execution of the defined macro.
10511 Using @file{trace.tmac}, you can trace calls to @code{de} and @code{de1}.
10513 Note that macro identifiers are shared with identifiers for strings and
10517 @DefreqList {am, name [@Var{end}]}
10518 @DefreqItem {am1, name [@Var{end}]}
10519 @DefreqItem {ami, name [@Var{end}]}
10520 @DefreqListEnd {ami1, name [@Var{end}]}
10521 @cindex appending to a macro (@code{am})
10522 @cindex macro, appending (@code{am})
10523 Works similarly to @code{de} except it appends onto the macro named
10524 @var{name}. So, to make the previously defined @samp{P} macro actually
10525 do indented instead of block paragraphs, add the necessary code to the
10526 existing macro like this:
10534 The @code{am1} request turns off compatibility mode
10535 while executing the appended macro piece. To be more precise, a
10536 @dfn{compatibility save} input token is inserted at the beginning of
10537 the appended code, and a @dfn{compatibility restore} input token at
10540 The @code{ami} request appends indirectly,
10541 meaning that @code{gtroff} expands strings whose names
10542 are @var{name} or @var{end} before performing the append.
10544 The @code{ami1} request is similar to @code{ami} but compatibility mode
10545 is switched off during execution of the defined macro.
10548 Using @file{trace.tmac}, you can trace calls to @code{am} and @code{am1}.
10551 @xref{Strings}, for the @code{als} request to rename a macro.
10553 The @code{de}, @code{am}, @code{di}, @code{da}, @code{ds}, and
10554 @code{as} requests (together with its variants) only create a new object
10555 if the name of the macro, diversion or string diversion is currently
10556 undefined or if it is defined to be a request; normally they modify the
10557 value of an existing object.
10559 @Defreq {return, [@Var{anything}]}
10560 Exit a macro, immediately returning to the caller.
10562 If called with an argument, exit twice, namely the current macro and the
10563 macro one level higher. This is used to define a wrapper macro for
10564 @code{return} in @file{trace.tmac}.
10572 @c ---------------------------------------------------------------------
10574 @node Copy-in Mode, Parameters, Writing Macros, Writing Macros
10575 @subsection Copy-in Mode
10576 @cindex copy-in mode
10577 @cindex mode, copy-in
10579 @cindex @code{\n}, when reading text for a macro
10580 @cindex @code{\$}, when reading text for a macro
10581 @cindex @code{\*}, when reading text for a macro
10582 @cindex @code{\\}, when reading text for a macro
10583 @cindex \@key{RET}, when reading text for a macro
10584 When @code{gtroff} reads in the text for a macro, string, or diversion,
10585 it copies the text (including request lines, but excluding escapes) into
10586 an internal buffer. Escapes are converted into an internal form,
10587 except for @code{\n}, @code{\$}, @code{\*}, @code{\\} and
10588 @code{\@key{RET}} which are evaluated and inserted into the text where
10589 the escape was located. This is known as @dfn{copy-in} mode or
10592 What this means is that you can specify when these escapes are to be
10593 evaluated (either at copy-in time or at the time of use) by insulating
10594 the escapes with an extra backslash. Compare this to the @code{\def}
10595 and @code{\edef} commands in @TeX{}.
10597 The following example prints the numbers 20 and@tie{}10:
10609 @c ---------------------------------------------------------------------
10611 @node Parameters, , Copy-in Mode, Writing Macros
10612 @subsection Parameters
10615 The arguments to a macro or string can be examined using a variety of
10619 @cindex number of arguments register (@code{.$})
10620 The number of arguments passed to a macro or string. This is a read-only
10623 Note that the @code{shift} request can change its value.
10626 Any individual argument can be retrieved with one of the following
10629 @DefescList {\\$, , n, }
10630 @DefescItem {\\$, @lparen{}, nn, }
10631 @DefescListEnd {\\$, @lbrack{}, nnn, @rbrack{}}
10632 @cindex copy-in mode, and macro arguments
10633 @cindex macro, arguments (@code{\$})
10634 @cindex arguments, macro (@code{\$})
10635 Retrieve the @var{n}@dmn{th}, @var{nn}@dmn{th} or @var{nnn}@dmn{th}
10636 argument. As usual, the first form only accepts a single number
10637 (larger than zero), the second a two-digit number (larger or equal
10638 to@tie{}10), and the third any positive integer value (larger
10639 than zero). Macros and strings can have an unlimited number of arguments.
10640 Note that due to copy-in mode, use two backslashes on these in actual use
10641 to prevent interpolation until the macro is actually invoked.
10644 @Defreq {shift, [@Var{n}]}
10645 Shift the arguments 1@tie{}position, or as
10646 many positions as specified by its argument. After executing this
10647 request, argument@tie{}@var{i} becomes argument @math{@var{i}-@var{n}};
10648 arguments 1 to@tie{}@var{n} are no longer available. Shifting by
10649 negative amounts is currently undefined.
10651 The register @code{.$} is adjusted accordingly.
10654 @DefescList {\\$*, , , }
10655 @DefescListEnd {\\$@@, , , }
10656 In some cases it is convenient to use all of the arguments at once (for
10657 example, to pass the arguments along to another macro). The @code{\$*}
10658 escape concatenates all the arguments separated by spaces. A
10659 similar escape is @code{\$@@}, which concatenates all the
10660 arguments with each surrounded by double quotes, and separated by
10661 spaces. If not in compatibility mode, the input level of double quotes
10662 is preserved (see @ref{Request and Macro Arguments}).
10665 @Defesc {\\$0, , , }
10666 @cindex macro name register (@code{\$0})
10667 @cindex @code{als} request, and @code{\$0}
10668 The name used to invoke the current macro.
10669 The @code{als} request can make a macro have more than one name.
10674 . if \\n[error] \@{\
10675 . tm \\$0: Houston, we have a problem.
10680 .als foo generic-macro
10681 .als bar generic-macro
10685 @xref{Request and Macro Arguments}.
10688 @c =====================================================================
10690 @node Page Motions, Drawing Requests, Writing Macros, gtroff Reference
10691 @section Page Motions
10692 @cindex page motions
10693 @cindex motions, page
10695 @xref{Manipulating Spacing}, for a discussion of the main request for
10696 vertical motion, @code{sp}.
10698 @DefreqList {mk, [@Var{reg}]}
10699 @DefreqListEnd {rt, [@Var{dist}]}
10700 @cindex marking vertical page location (@code{mk})
10701 @cindex page location, vertical, marking (@code{mk})
10702 @cindex location, vertical, page, marking (@code{mk})
10703 @cindex vertical page location, marking (@code{mk})
10704 @cindex returning to marked vertical page location (@code{rt})
10705 @cindex page location, vertical, returning to marked (@code{rt})
10706 @cindex location, vertical, page, returning to marked (@code{rt})
10707 @cindex vertical page location, returning to marked (@code{rt})
10708 The request @code{mk} can be used to mark a location on a page, for
10709 movement to later. This request takes a register name as an argument
10710 in which to store the current page location. With no argument it
10711 stores the location in an internal register. The results of this can
10712 be used later by the @code{rt} or the @code{sp} request (or the
10715 The @code{rt} request returns @emph{upwards} to the location marked
10716 with the last @code{mk} request. If used with an argument, return to
10717 a position which distance from the top of the page is @var{dist} (no
10718 previous call to @code{mk} is necessary in this case). Default scaling
10719 indicator is @samp{v}.
10721 Here a primitive solution for a two-column macro.
10724 .nr column-length 1.5i
10726 .nr bottom-margin 1m
10733 . ll \\n[column-length]u
10734 . wh -\\n[bottom-margin]u 2c-trap
10741 . ie \\n[right-side] \@{\
10743 . po -(\\n[column-length]u + \\n[column-gap]u)
10745 . wh -\\n[bottom-margin]u
10748 . \" switch to right side
10750 . po +(\\n[column-length]u + \\n[column-gap]u)
10759 This is a small test which shows how the
10760 rt request works in combination with mk.
10763 Starting here, text is typeset in two columns.
10764 Note that this implementation isn't robust
10765 and thus not suited for a real two-column
10772 This is a small test which shows how the
10773 rt request works in combination with mk.
10775 Starting here, isn't robust
10776 text is typeset and thus not
10777 in two columns. suited for a
10778 Note that this real two-column
10779 implementation macro.
10783 The following escapes give fine control of movements about the page.
10785 @Defesc {\\v, ', e, '}
10786 @cindex vertical motion (@code{\v})
10787 @cindex motion, vertical (@code{\v})
10788 Move vertically, usually from the current location on the page (if no
10789 absolute position operator @samp{|} is used). The
10790 argument@tie{}@var{e} specifies the distance to move; positive is
10791 downwards and negative upwards. The default scaling indicator for this
10792 escape is @samp{v}. Beware, however, that @code{gtroff} continues text
10793 processing at the point where the motion ends, so you should always
10794 balance motions to avoid interference with text processing.
10796 @code{\v} doesn't trigger a trap. This can be quite useful; for example,
10797 consider a page bottom trap macro which prints a marker in the margin to
10798 indicate continuation of a footnote or something similar.
10801 There are some special-case escapes for vertical motion.
10803 @Defesc {\\r, , , }
10804 Move upwards@tie{}1@dmn{v}.
10807 @Defesc {\\u, , , }
10808 Move upwards@tie{}.5@dmn{v}.
10811 @Defesc {\\d, , , }
10812 Move down@tie{}.5@dmn{v}.
10815 @Defesc {\\h, ', e, '}
10816 @cindex inserting horizontal space (@code{\h})
10817 @cindex horizontal space (@code{\h})
10818 @cindex space, horizontal (@code{\h})
10819 @cindex horizontal motion (@code{\h})
10820 @cindex motion, horizontal (@code{\h})
10821 Move horizontally, usually from the current location (if no absolute
10822 position operator @samp{|} is used). The expression@tie{}@var{e}
10823 indicates how far to move: positive is rightwards and negative
10824 leftwards. The default scaling indicator for this escape is @samp{m}.
10826 This horizontal space is not discarded at the end of a line. To insert
10827 discardable space of a certain length use the @code{ss} request.
10830 There are a number of special-case escapes for horizontal motion.
10832 @Defesc {\\@key{SP}, , , }
10833 @cindex space, unbreakable
10834 @cindex unbreakable space
10835 An unbreakable and unpaddable (i.e.@: not expanded during filling)
10836 space. (Note: This is a backslash followed by a space.)
10839 @Defesc {\\~, , , }
10840 An unbreakable space that stretches like a normal inter-word space
10841 when a line is adjusted.
10844 @Defesc {\\|, , , }
10845 A 1/6@dmn{th} em space. Ignored for TTY output devices (rounded to
10849 @Defesc {\\^, , , }
10850 A 1/12@dmn{th} em space. Ignored for TTY output devices (rounded to
10854 @Defesc {\\0, , , }
10855 @cindex space, width of a digit (@code{\0})
10856 @cindex digit width space (@code{\0})
10857 A space the size of a digit.
10860 The following string sets the @TeX{} logo:
10863 .ds TeX T\h'-.1667m'\v'.224m'E\v'-.224m'\h'-.125m'X
10866 @DefescList {\\w, ', text, '}
10873 @DefregListEnd {skw}
10874 @cindex width escape (@code{\w})
10875 Return the width of the specified @var{text} in basic units.
10876 This allows horizontal movement based on the width of some
10877 arbitrary text (e.g.@: given as an argument to a macro).
10880 The length of the string `abc' is \w'abc'u.
10881 @result{} The length of the string `abc' is 72u.
10884 Font changes may occur in @var{text} which don't affect current
10887 After use, @code{\w} sets several registers:
10892 The highest and lowest point of the baseline, respectively, in @var{text}.
10896 Like the @code{st} and @code{sb} registers, but takes account of the
10897 heights and depths of glyphs. With other words, this gives the
10898 highest and lowest point of @var{text}. Values below the baseline are
10902 Defines the kinds of glyphs occurring in @var{text}:
10906 only short glyphs, no descenders or tall glyphs.
10909 at least one descender.
10912 at least one tall glyph.
10915 at least one each of a descender and a tall glyph.
10919 The amount of horizontal space (possibly negative) that should be added
10920 to the last glyph before a subscript.
10923 How far to right of the center of the last glyph in the @code{\w}
10924 argument, the center of an accent from a roman font should be placed
10929 @DefescList {\\k, , p, }
10930 @DefescItem {\\k, @lparen{}, ps, }
10931 @DefescListEnd {\\k, @lbrack{}, position, @rbrack}
10932 @cindex saving horizontal input line position (@code{\k})
10933 @cindex horizontal input line position, saving (@code{\k})
10934 @cindex input line position, horizontal, saving (@code{\k})
10935 @cindex position, horizontal input line, saving (@code{\k})
10936 @cindex line, input, horizontal position, saving (@code{\k})
10937 Store the current horizontal position in the @emph{input} line in
10938 number register with name @var{position} (one-character name@tie{}@var{p},
10939 two-character name @var{ps}). Use this, for example, to return to the
10940 beginning of a string for highlighting or other decoration.
10944 @cindex horizontal input line position register (@code{hp})
10945 @cindex input line, horizontal position, register (@code{hp})
10946 @cindex position, horizontal, in input line, register (@code{hp})
10947 @cindex line, input, horizontal position, register (@code{hp})
10948 The current horizontal position at the input line.
10952 @cindex horizontal output line position register (@code{.k})
10953 @cindex output line, horizontal position, register (@code{.k})
10954 @cindex position, horizontal, in output line, register (@code{.k})
10955 @cindex line, output, horizontal position, register (@code{.k})
10956 A read-only number register containing the current horizontal output
10957 position (relative to the current indentation).
10960 @Defesc {\\o, ', abc, '}
10961 @cindex overstriking glyphs (@code{\o})
10962 @cindex glyphs, overstriking (@code{\o})
10963 Overstrike glyphs @var{a}, @var{b}, @var{c}, @dots{}; the glyphs
10964 are centered, and the resulting spacing is the largest width of the
10968 @Defesc {\\z, , g, , }
10969 @cindex zero-width printing (@code{\z}, @code{\Z})
10970 @cindex printing, zero-width (@code{\z}, @code{\Z})
10971 Print glyph @var{g} with zero width, i.e., without spacing. Use
10972 this to overstrike glyphs left-aligned.
10975 @Defesc {\\Z, ', anything, '}
10976 @cindex zero-width printing (@code{\z}, @code{\Z})
10977 @cindex printing, zero-width (@code{\z}, @code{\Z})
10978 Print @var{anything}, then restore the horizontal and vertical position.
10979 The argument may not contain tabs or leaders.
10981 The following is an example of a strike-through macro:
10986 \Z@@\v'-.25m'\l'\\n[ww]u'@@\\$1
10991 an actual emergency!
10996 @c =====================================================================
10998 @node Drawing Requests, Traps, Page Motions, gtroff Reference
10999 @section Drawing Requests
11000 @cindex drawing requests
11001 @cindex requests for drawing
11003 @code{gtroff} provides a number of ways to draw lines and other figures
11004 on the page. Used in combination with the page motion commands (see
11005 @ref{Page Motions}, for more info), a wide variety of figures can be
11006 drawn. However, for complex drawings these operations can be quite
11007 cumbersome, and it may be wise to use graphic preprocessors like
11008 @code{gpic} or @code{ggrn}. @xref{gpic}, and @ref{ggrn}, for more
11011 All drawing is done via escapes.
11013 @DefescList {\\l, ', l, '}
11014 @DefescListEnd {\\l, ', lg, '}
11015 @cindex drawing horizontal lines (@code{\l})
11016 @cindex horizontal line, drawing (@code{\l})
11017 @cindex line, horizontal, drawing (@code{\l})
11018 Draw a line horizontally. @var{l} is the length of the line to be
11019 drawn. If it is positive, start the line at the current location and
11020 draw to the right; its end point is the new current location. Negative
11021 values are handled differently: The line starts at the current location
11022 and draws to the left, but the current location doesn't move.
11024 @var{l} can also be specified absolutely (i.e.@: with a leading
11025 @samp{|}) which draws back to the beginning of the input line.
11026 Default scaling indicator is @samp{m}.
11028 @cindex underscore glyph (@code{\[ru]})
11029 @cindex glyph, underscore (@code{\[ru]})
11030 @cindex line drawing glyph
11031 @cindex glyph, for line drawing
11032 The optional second parameter@tie{}@var{g} is a glyph to draw the line
11033 with. If this second argument is not specified, @code{gtroff} uses
11034 the underscore glyph, @code{\[ru]}.
11036 @cindex zero width space character (@code{\&})
11037 @cindex character, zero width space (@code{\&})
11038 @cindex space character, zero width (@code{\&})
11039 To separate the two arguments (to prevent @code{gtroff} from
11040 interpreting a drawing glyph as a scaling indicator if the glyph is
11041 represented by a single character) use @code{\&}.
11043 Here a small useful example:
11047 \[br]\\$*\[br]\l'|0\[rn]'\l'|0\[ul]'
11052 Note that this works by outputting a box rule (a vertical line), then
11053 the text given as an argument and then another box rule. Finally, the
11054 line drawing escapes both draw from the current location to the
11055 beginning of the @emph{input} line -- this works because the line
11056 length is negative, not moving the current point.
11059 @DefescList {\\L, ', l, '}
11060 @DefescListEnd {\\L, ', lg, '}
11061 @cindex drawing vertical lines (@code{\L})
11062 @cindex vertical line drawing (@code{\L})
11063 @cindex line, vertical, drawing (@code{\L})
11064 @cindex line drawing glyph
11065 @cindex glyph for line drawing
11066 @cindex box rule glyph (@code{\[br]})
11067 @cindex glyph, box rule (@code{\[br]})
11068 Draw vertical lines. Its parameters are
11069 similar to the @code{\l} escape, except that the default scaling
11070 indicator is @samp{v}. The movement is downwards for positive values,
11071 and upwards for negative values. The default glyph is the box rule
11072 glyph, @code{\[br]}. As with the vertical motion escapes, text
11073 processing blindly continues where the line ends.
11076 This is a \L'3v'test.
11080 Here the result, produced with @code{grotty}.
11090 @Defesc {\\D, ', command arg @dots{}, '}
11091 The @code{\D} escape provides a variety of drawing functions.
11092 Note that on character devices, only vertical and horizontal lines are
11093 supported within @code{grotty}; other devices may only support a subset
11094 of the available drawing functions.
11096 The default scaling indicator for all subcommands of @code{\D} is
11097 @samp{m} for horizontal distances and @samp{v} for vertical ones.
11098 Exceptions are @w{@code{\D'f @dots{}'}} and @w{@code{\D't @dots{}'}}
11099 which use @code{u} as the default, and @w{@code{\D'F@var{x} @dots{}'}}
11100 which arguments are treated similar to the @code{defcolor} request.
11103 @item \D'l @var{dx} @var{dy}'
11104 @cindex line, drawing (@w{@code{\D'l @dots{}'}})
11105 @cindex drawing a line (@w{@code{\D'l @dots{}'}})
11106 Draw a line from the current location to the relative point specified by
11107 (@var{dx},@var{dy}), where positive values mean down and right,
11108 respectively. The end point of the line is the new current location.
11110 The following example is a macro for creating a box around a text string;
11111 for simplicity, the box margin is taken as a fixed value, 0.2@dmn{m}.
11117 \h'-.2m'\v'(.2m - \\n[rsb]u)'\
11118 \D'l 0 -(\\n[rst]u - \\n[rsb]u + .4m)'\
11119 \D'l (\\n[@@wd]u + .4m) 0'\
11120 \D'l 0 (\\n[rst]u - \\n[rsb]u + .4m)'\
11121 \D'l -(\\n[@@wd]u + .4m) 0'\
11122 \h'.2m'\v'-(.2m - \\n[rsb]u)'\
11129 First, the width of the string is stored in register @code{@@wd}. Then,
11130 four lines are drawn to form a box, properly offset by the box margin.
11131 The registers @code{rst} and @code{rsb} are set by the @code{\w} escape,
11132 containing the largest height and depth of the whole string.
11134 @item \D'c @var{d}'
11135 @cindex circle, drawing (@w{@code{\D'c @dots{}'}})
11136 @cindex drawing a circle (@w{@code{\D'c @dots{}'}})
11137 Draw a circle with a diameter of@tie{}@var{d} with the leftmost point at the
11138 current position. After drawing, the current location is positioned at the
11139 rightmost point of the circle.
11141 @item \D'C @var{d}'
11142 @cindex circle, solid, drawing (@w{@code{\D'C @dots{}'}})
11143 @cindex drawing a solid circle (@w{@code{\D'C @dots{}'}})
11144 @cindex solid circle, drawing (@w{@code{\D'C @dots{}'}})
11145 Draw a solid circle with the same parameters and behaviour as an outlined
11146 circle. No outline is drawn.
11148 @item \D'e @var{x} @var{y}'
11149 @cindex drawing an ellipse (@w{@code{\D'e @dots{}'}})
11150 @cindex ellipse, drawing (@w{@code{\D'e @dots{}'}})
11151 Draw an ellipse with a horizontal diameter of @var{x} and a vertical
11152 diameter of @var{y} with the leftmost point at the current position.
11153 After drawing, the current location is positioned at the rightmost point of
11156 @item \D'E @var{x} @var{y}'
11157 @cindex ellipse, solid, drawing (@w{@code{\D'E @dots{}'}})
11158 @cindex drawing a solid ellipse (@w{@code{\D'E @dots{}'}})
11159 @cindex solid ellipse, drawing (@w{@code{\D'E @dots{}'}})
11160 Draw a solid ellipse with the same parameters and behaviour as an
11161 outlined ellipse. No outline is drawn.
11163 @item \D'a @var{dx1} @var{dy1} @var{dx2} @var{dy2}'
11164 @cindex arc, drawing (@w{@code{\D'a @dots{}'}})
11165 @cindex drawing an arc (@w{@code{\D'a @dots{}'}})
11166 Draw an arc clockwise from the current location through the two
11167 specified relative locations (@var{dx1},@var{dy1}) and
11168 (@var{dx2},@var{dy2}). The coordinates of the first point are relative
11169 to the current position, and the coordinates of the second point are
11170 relative to the first point. After drawing, the current position is moved
11171 to the final point of the arc.
11173 @item \D'~ @var{dx1} @var{dy1} @var{dx2} @var{dy2} @dots{}'
11174 @cindex drawing a spline (@w{@code{\D'~ @dots{}'}})
11175 @cindex spline, drawing (@w{@code{\D'~ @dots{}'}})
11176 Draw a spline from the current location to the relative point
11177 (@var{dx1},@var{dy1}) and then to (@var{dx2},@var{dy2}), and so on.
11178 The current position is moved to the terminal point of the drawn curve.
11180 @item \D'f @var{n}'
11181 @cindex gray shading (@w{@code{\D'f @dots{}'}})
11182 @cindex shading filled objects (@w{@code{\D'f @dots{}'}})
11183 Set the shade of gray to be used for filling solid objects to@tie{}@var{n};
11184 @var{n}@tie{}must be an integer between 0 and@tie{}1000, where 0
11185 corresponds solid white and 1000 to solid black, and values in between
11186 correspond to intermediate shades of gray. This applies only to solid
11187 circles, solid ellipses, and solid polygons. By default, a level of
11190 Despite of being silly, the current point is moved horizontally to the
11191 right by@tie{}@var{n}.
11193 @cindex @w{@code{\D'f @dots{}'}} and horizontal resolution
11194 Don't use this command! It has the serious drawback that it will be
11195 always rounded to the next integer multiple of the horizontal resolution
11196 (the value of the @code{hor} keyword in the @file{DESC} file). Use
11197 @code{\M} (@pxref{Colors}) or @w{@code{\D'Fg @dots{}'}} instead.
11199 @item \D'p @var{dx1} @var{dy1} @var{dx2} @var{dy2} @dots{}'
11200 @cindex drawing a polygon (@w{@code{\D'p @dots{}'}})
11201 @cindex polygon, drawing (@w{@code{\D'p @dots{}'}})
11202 Draw a polygon from the current location to the relative position
11203 (@var{dx1},@var{dy1}) and then to (@var{dx2},@var{dy2}) and so on.
11204 When the specified data points are exhausted, a line is drawn back
11205 to the starting point. The current position is changed by adding the
11206 sum of all arguments with odd index to the actual horizontal position and
11207 the even ones to the vertical position.
11209 @item \D'P @var{dx1} @var{dy1} @var{dx2} @var{dy2} @dots{}'
11210 @cindex polygon, solid, drawing (@w{@code{\D'P @dots{}'}})
11211 @cindex drawing a solid polygon (@w{@code{\D'P @dots{}'}})
11212 @cindex solid polygon, drawing (@w{@code{\D'P @dots{}'}})
11213 Draw a solid polygon with the same parameters and behaviour as an
11214 outlined polygon. No outline is drawn.
11216 Here a better variant of the box macro to fill the box with some color.
11217 Note that the box must be drawn before the text since colors in
11218 @code{gtroff} are not transparent; the filled polygon would hide the
11225 \h'-.2m'\v'(.2m - \\n[rsb]u)'\
11227 \D'P 0 -(\\n[rst]u - \\n[rsb]u + .4m) \
11228 (\\n[@@wd]u + .4m) 0 \
11229 0 (\\n[rst]u - \\n[rsb]u + .4m) \
11230 -(\\n[@@wd]u + .4m) 0'\
11231 \h'.2m'\v'-(.2m - \\n[rsb]u)'\
11238 @item \D't @var{n}'
11239 @cindex line thickness (@w{@code{\D't @dots{}'}})
11240 @cindex thickness of lines (@w{@code{\D't @dots{}'}})
11241 Set the current line thickness to @var{n}@tie{}machine units. A value of
11242 zero selects the smallest available line thickness. A negative value
11243 makes the line thickness proportional to the current point size (this is
11244 the default behaviour of @acronym{AT&T} @code{troff}).
11246 Despite of being silly, the current point is moved horizontally to the
11247 right by@tie{}@var{n}.
11249 @item \D'F@var{scheme} @var{color_components}'
11250 @cindex unnamed fill colors (@code{\D'F@dots{}'})
11251 @cindex fill colors, unnamed (@code{\D'F@dots{}'})
11252 @cindex colors, fill, unnamed (@code{\D'F@dots{}'})
11253 Change current fill color. @var{scheme} is a single letter denoting the
11254 color scheme: @samp{r} (rgb), @samp{c} (cmy), @samp{k} (cmyk), @samp{g}
11255 (gray), or @samp{d} (default color). The color components use exactly
11256 the same syntax as in the @code{defcolor} request (@pxref{Colors}); the
11257 command @code{\D'Fd'} doesn't take an argument.
11259 @emph{No} position changing!
11265 \D'Fg .3' \" same gray as \D'f 700'
11266 \D'Fr #0000ff' \" blue
11270 @xref{Graphics Commands}.
11272 @Defesc {\\b, ', string, '}
11273 @cindex pile, glyph (@code{\b})
11274 @cindex glyph pile (@code{\b})
11275 @cindex stacking glyphs (@code{\b})
11276 @dfn{Pile} a sequence of glyphs vertically, and center it vertically
11277 on the current line. Use it to build large brackets and braces.
11279 Here an example how to create a large opening brace:
11282 \b'\[lt]\[bv]\[lk]\[bv]\[lb]'
11285 @cindex @code{\b}, limitations
11286 @cindex limitations of @code{\b} escape
11287 The first glyph is on the top, the last glyph in @var{string} is
11288 at the bottom. Note that @code{gtroff} separates the glyphs
11289 vertically by 1@dmn{m}, and the whole object is centered 0.5@dmn{m}
11290 above the current baseline; the largest glyph width is used as the
11291 width for the whole object. This rather unflexible positioning
11292 algorithm doesn't work with @option{-Tdvi} since the bracket pieces vary
11293 in height for this device. Instead, use the @code{eqn} preprocessor.
11295 @xref{Manipulating Spacing}, how to adjust the vertical spacing with
11296 the @code{\x} escape.
11300 @c =====================================================================
11302 @node Traps, Diversions, Drawing Requests, gtroff Reference
11306 @dfn{Traps} are locations, which, when reached, call a specified
11307 macro. These traps can occur at a given location on the page, at a
11308 given location in the current diversion, at a blank line,
11309 after a certain number of input lines, or at the end of input.
11311 @cindex planting a trap
11312 @cindex trap, planting
11313 Setting a trap is also called @dfn{planting}.
11314 @cindex trap, springing
11315 @cindex springing a trap
11316 It is also said that a trap is @dfn{sprung} if the associated macro
11320 * Page Location Traps::
11321 * Diversion Traps::
11322 * Input Line Traps::
11323 * Blank Line Traps::
11324 * End-of-input Traps::
11327 @c ---------------------------------------------------------------------
11329 @node Page Location Traps, Diversion Traps, Traps, Traps
11330 @subsection Page Location Traps
11331 @cindex page location traps
11332 @cindex traps, page location
11334 @dfn{Page location traps} perform an action when @code{gtroff}
11335 reaches or passes a certain vertical location on the page. Page
11336 location traps have a variety of purposes, including:
11340 setting headers and footers
11343 setting body text in multiple columns
11349 @DefreqList {vpt, flag}
11350 @DefregListEnd {.vpt}
11351 @cindex enabling vertical position traps (@code{vpt})
11352 @cindex vertical position traps, enabling (@code{vpt})
11353 @cindex vertical position trap enable register (@code{.vpt})
11354 Enable vertical position traps if @var{flag} is non-zero, or disables
11355 them otherwise. Vertical position traps are traps set by the @code{wh}
11356 or @code{dt} requests. Traps set by the @code{it} request are not
11357 vertical position traps. The parameter that controls whether vertical
11358 position traps are enabled is global. Initially vertical position traps
11359 are enabled. The current setting of this is available in the
11360 @code{.vpt} read-only number register.
11362 Note that a page can't be ejected if @code{vpt} is set to zero.
11365 @Defreq {wh, dist [@Var{macro}]}
11366 Set a page location trap. Non-negative values for @var{dist} set
11367 the trap relative to the top of the page; negative values set
11368 the trap relative to the bottom of the page. Default scaling
11369 indicator is @samp{v}.
11371 @var{macro} is the name of the macro to execute when the
11372 trap is sprung. If @var{macro} is missing, remove the first trap
11373 (if any) at @var{dist}.
11375 @cindex page headers
11376 @cindex page footers
11379 The following is a simple example of how many macro packages
11380 set headers and footers.
11383 .de hd \" Page header
11389 .de fo \" Page footer
11395 .wh 0 hd \" trap at top of the page
11396 .wh -1i fo \" trap one inch from bottom
11399 A trap at or below the bottom of the page is ignored; it can be made
11400 active by either moving it up or increasing the page length so that the
11401 trap is on the page.
11403 It is possible to have more than one trap at the same location; to do so,
11404 the traps must be defined at different locations, then moved together with
11405 the @code{ch} request; otherwise the second trap would replace the first
11406 one. Earlier defined traps hide later defined traps if moved to the same
11407 position (the many empty lines caused by the @code{bp} request are omitted
11408 in the following example):
11441 @cindex distance to next trap register (@code{.t})
11442 @cindex trap, distance, register (@code{.t})
11443 A read-only number register holding the distance to the next trap.
11445 If there are no traps between the current position and the bottom of the
11446 page, it contains the distance to the page bottom. In a diversion, the
11447 distance to the page bottom is infinite (the returned value is the biggest
11448 integer which can be represented in @code{groff}) if there are no diversion
11452 @Defreq {ch, macro [@Var{dist}]}
11453 @cindex changing trap location (@code{ch})
11454 @cindex trap, changing location (@code{ch})
11455 Change the location of a trap.
11456 The first argument is the name of the macro to be invoked at
11457 the trap, and the second argument is the new location for the trap
11458 (note that the parameters are specified in opposite order as in the
11459 @code{wh} request). This is useful for building up footnotes in a
11460 diversion to allow more space at the bottom of the page for them.
11462 Default scaling indicator for @var{dist} is @samp{v}. If @var{dist}
11463 is missing, the trap is removed.
11469 ... (simplified) footnote example ...
11475 The read-only number register @code{.ne} contains the amount of space
11476 that was needed in the last @code{ne} request that caused a trap to be
11477 sprung. Useful in conjunction with the @code{.trunc} register.
11478 @xref{Page Control}, for more information.
11480 Since the @code{.ne} register is only set by traps it doesn't make
11481 much sense to use it outside of trap macros.
11485 @cindex @code{ne} request, and the @code{.trunc} register
11486 @cindex truncated vertical space register (@code{.trunc})
11487 A read-only register containing the amount of vertical space truncated
11488 by the most recently sprung vertical position trap, or, if the trap was
11489 sprung by an @code{ne} request, minus the amount of vertical motion
11490 produced by the @code{ne} request. In other words, at the point a trap
11491 is sprung, it represents the difference of what the vertical position
11492 would have been but for the trap, and what the vertical position
11495 Since the @code{.trunc} register is only set by traps it doesn't make
11496 much sense to use it outside of trap macros.
11500 @cindex @code{bp} request, and traps (@code{.pe})
11501 @cindex traps, sprung by @code{bp} request (@code{.pe})
11502 @cindex page ejecting register (@code{.pe})
11503 A read-only register which is set to@tie{}1 while a page is ejected with
11504 the @code{bp} request (or by the end of input).
11506 Outside of traps this register is always zero. In the following example,
11507 only the second call to@tie{}@code{x} is caused by @code{bp}.
11528 @cindex diversions, and traps
11529 @cindex traps, and diversions
11530 An important fact to consider while designing macros is that diversions and
11531 traps do not interact normally. For example, if a trap invokes a header
11532 macro (while outputting a diversion) which tries to change the font on the
11533 current page, the effect will not be visible before the diversion has
11534 completely been printed (except for input protected with @code{\!} or
11535 @code{\?}) since the data in the diversion is already formatted. In most
11536 cases, this is not the expected behaviour.
11538 @c ---------------------------------------------------------------------
11540 @node Diversion Traps, Input Line Traps, Page Location Traps, Traps
11541 @subsection Diversion Traps
11542 @cindex diversion traps
11543 @cindex traps, diversion
11545 @Defreq {dt, [@Var{dist} @Var{macro}]}
11546 @cindex @code{.t} register, and diversions
11547 @cindex setting diversion trap (@code{dt})
11548 @cindex diversion trap, setting (@code{dt})
11549 @cindex trap, diversion, setting (@code{dt})
11550 Set a trap @emph{within} a diversion.
11551 @var{dist} is the location of the trap
11552 (identical to the @code{wh} request; default scaling indicator is
11553 @samp{v}) and @var{macro} is the name of the macro to be invoked.
11554 If called without arguments, the diversion trap is removed.
11556 Note that there exists only a single diversion trap.
11558 The number register @code{.t} still works within diversions.
11559 @xref{Diversions}, for more information.
11562 @c ---------------------------------------------------------------------
11564 @node Input Line Traps, Blank Line Traps, Diversion Traps, Traps
11565 @subsection Input Line Traps
11566 @cindex input line traps
11567 @cindex traps, input line
11569 @DefreqList {it, n macro}
11570 @DefreqItem {itc, n macro}
11571 @cindex setting input line trap (@code{it})
11572 @cindex input line trap, setting (@code{it})
11573 @cindex trap, input line, setting (@code{it})
11574 Set an input line trap.
11575 @var{n}@tie{}is the number of lines of input which may be read before
11576 springing the trap, @var{macro} is the macro to be invoked.
11577 Request lines are not counted as input lines.
11579 For example, one possible use is to have a macro which prints the
11580 next @var{n}@tie{}lines in a bold font.
11593 @cindex input line traps and interrupted lines (@code{itc})
11594 @cindex interrupted lines and input line traps (@code{itc})
11595 @cindex traps, input line, and interrupted lines (@code{itc})
11596 @cindex lines, interrupted, and input line traps (@code{itc})
11597 The @code{itc} request is identical
11598 except that an interrupted text line (ending with @code{\c})
11599 is not counted as a separate line.
11601 Both requests are associated with the current environment
11602 (@pxref{Environments}); switching to another environment disables the
11603 current input trap, and going back reactivates it, restoring the number
11604 of already processed lines.
11607 @c ---------------------------------------------------------------------
11609 @node Blank Line Traps, End-of-input Traps, Input Line Traps, Traps
11610 @subsection Blank Line Traps
11611 @cindex blank line traps
11612 @cindex traps, blank line
11614 @Defreq {blm, macro}
11615 @cindex blank line macro (@code{blm})
11616 Set a blank line trap.
11617 @code{gtroff} executes @var{macro} when it encounters a blank line in
11621 @c ---------------------------------------------------------------------
11623 @node End-of-input Traps, , Blank Line Traps, Traps
11624 @subsection End-of-input Traps
11625 @cindex end-of-input traps
11626 @cindex traps, end-of-input
11628 @Defreq {em, macro}
11629 @cindex setting end-of-input trap (@code{em})
11630 @cindex end-of-input trap, setting (@code{em})
11631 @cindex trap, end-of-input, setting (@code{em})
11632 @cindex end-of-input macro (@code{em})
11633 @cindex macro, end-of-input (@code{em})
11634 Set a trap at the end of input. @var{macro} is executed after the
11635 last line of the input file has been processed.
11637 For example, if the document had to have a section at the bottom of the
11638 last page for someone to approve it, the @code{em} request could be
11644 . sp |(\\n[.t] - 6v)
11658 @c =====================================================================
11660 @node Diversions, Environments, Traps, gtroff Reference
11661 @section Diversions
11664 In @code{gtroff} it is possible to @dfn{divert} text into a named
11665 storage area. Due to the similarity to defining macros it is sometimes
11666 said to be stored in a macro. This is used for saving text for output
11667 at a later time, which is useful for keeping blocks of text on the same
11668 page, footnotes, tables of contents, and indices.
11670 @cindex top-level diversion
11671 @cindex diversion, top-level
11672 For orthogonality it is said that @code{gtroff} is in the @dfn{top-level
11673 diversion} if no diversion is active (i.e., the data is diverted to the
11676 @DefreqList {di, macro}
11677 @DefreqListEnd {da, macro}
11678 @cindex beginning diversion (@code{di})
11679 @cindex diversion, beginning (@code{di})
11680 @cindex ending diversion (@code{di})
11681 @cindex diversion, ending (@code{di})
11682 @cindex appending to a diversion (@code{da})
11683 @cindex diversion, appending (@code{da})
11684 Begin a diversion. Like the @code{de}
11685 request, it takes an argument of a macro name to divert subsequent text
11686 into. The @code{da} macro appends to an existing diversion.
11688 @code{di} or @code{da} without an argument ends the diversion.
11691 @DefreqList {box, macro}
11692 @DefreqListEnd {boxa, macro}
11693 Begin (or appends to) a diversion like the
11694 @code{di} and @code{da} requests.
11695 The difference is that @code{box} and @code{boxa}
11696 do not include a partially-filled line in the diversion.
11708 @result{} Before the box. After the box.
11710 @result{} In the box.
11717 Before the diversion.
11722 After the diversion.
11724 @result{} After the diversion.
11726 @result{} Before the diversion. In the diversion.
11729 @code{box} or @code{boxa} without an argument ends the diversion.
11733 @DefregListEnd {.d}
11734 @cindex @code{nl} register, and @code{.d}
11735 @cindex nested diversions
11736 @cindex diversion, nested
11737 @cindex diversion name register (@code{.z})
11738 @cindex vertical position in diversion register (@code{.d})
11739 @cindex position, vertical, in diversion, register (@code{.d})
11740 @cindex diversion, vertical position in, register (@code{.d})
11741 Diversions may be nested. The read-only number register @code{.z}
11742 contains the name of the current diversion (this is a string-valued
11743 register). The read-only number register @code{.d} contains the current
11744 vertical place in the diversion. If not in a diversion it is the same
11745 as register @code{nl}.
11749 @cindex high-water mark register (@code{.h})
11750 @cindex mark, high-water, register (@code{.h})
11751 @cindex position of lowest text line (@code{.h})
11752 @cindex text line, position of lowest (@code{.h})
11753 The @dfn{high-water mark} on the current page. It corresponds to the
11754 text baseline of the lowest line on the page. This is a read-only
11758 .tm .h==\n[.h], nl==\n[nl]
11759 @result{} .h==0, nl==-1
11763 .tm .h==\n[.h], nl==\n[nl]
11764 @result{} .h==40, nl==120
11767 @cindex @code{.h} register, difference to @code{nl}
11768 @cindex @code{nl} register, difference to @code{.h}
11770 As can be seen in the previous example, empty lines are not considered
11771 in the return value of the @code{.h} register.
11775 @DefregListEnd {dl}
11776 @cindex @code{dn} register, and @code{da} (@code{boxa})
11777 @cindex @code{dl} register, and @code{da} (@code{boxa})
11778 @cindex @code{da} request, and @code{dn} (@code{dl})
11779 @cindex @code{boxa} request, and @code{dn} (@code{dl})
11780 After completing a diversion, the read-write number registers @code{dn}
11781 and @code{dl} contain the vertical and horizontal size of the diversion.
11782 Note that only the just processed lines are counted: For the computation
11783 of @code{dn} and @code{dl}, the requests @code{da} and @code{boxa} are
11784 handled as if @code{di} and @code{box} had been used -- lines which have
11785 been already stored in a macro are not taken into account.
11788 .\" Center text both horizontally & vertically
11790 .\" Enclose macro definitions in .eo and .ec
11791 .\" to avoid the doubling of the backslash
11793 .\" macro .(c starts centering mode
11804 .\" macro .)c terminates centering mode
11809 . nr @@s (((\n[.t]u - \n[dn]u) / 2u) - 1v)
11821 .\" End of macro definitions, restore escape mechanism
11826 @DefescList {\\!, , , }
11827 @DefescListEnd {\\?, , anything, \\?}
11828 @cindex transparent output (@code{\!}, @code{\?})
11829 @cindex output, transparent (@code{\!}, @code{\?})
11830 Prevent requests, macros, and escapes from being
11831 interpreted when read into a diversion. Both escapes take the given text
11832 and @dfn{transparently} embed it into the diversion. This is useful for
11833 macros which shouldn't be invoked until the diverted text is actually
11836 The @code{\!} escape transparently embeds text up to
11837 and including the end of the line.
11838 The @code{\?} escape transparently embeds text until the next
11839 occurrence of the @code{\?} escape. Example:
11846 @var{anything} may not contain newlines; use @code{\!} to embed
11847 newlines in a diversion. The escape sequence @code{\?} is also
11848 recognized in copy mode and turned into a single internal code; it is
11849 this code that terminates @var{anything}. Thus the following example
11856 \?\\?\\\\?\\\\\\\\nx\\\\?\\?\?
11870 Both escapes read the data in copy mode.
11872 @cindex @code{\!}, in top-level diversion
11873 @cindex top-level diversion, and @code{\!}
11874 @cindex diversion, top-level, and @code{\!}
11875 If @code{\!} is used in the top-level diversion, its argument is
11876 directly embedded into the @code{gtroff} intermediate output. This can
11877 be used for example to control a postprocessor which processes the data
11878 before it is sent to the device driver.
11880 @cindex @code{\?}, in top-level diversion
11881 @cindex top-level diversion, and @code{\?}
11882 @cindex diversion, top-level, and @code{\?}
11883 The @code{\?} escape used in the top-level diversion produces no output
11884 at all; its argument is simply ignored.
11887 @cindex @code{\!}, and @code{output}
11888 @cindex @code{output} request, and @code{\!}
11889 @Defreq {output, string}
11890 Emit @var{string} directly to the @code{gtroff} intermediate output
11891 (subject to copy-mode interpretation); this is similar to @code{\!} used
11892 at the top level. An initial double quote in @var{string} is stripped off
11893 to allow initial blanks.
11895 This request can't be used before the first page has started -- if you get
11896 an error, simply insert @code{.br} before the @code{output} request.
11898 Without argument, @code{output} is ignored.
11900 Use with caution! It is normally only needed for mark-up used by a
11901 postprocessor which does something with the output before sending it to
11902 the output device, filtering out @var{string} again.
11905 @Defreq {asciify, div}
11906 @cindex unformatting diversions (@code{asciify})
11907 @cindex diversion, unformatting (@code{asciify})
11908 @cindex @code{trin} request, and @code{asciify}
11909 @dfn{Unformat} the diversion specified by @var{div}
11910 in such a way that @acronym{ASCII} characters, characters translated with
11911 the @code{trin} request, space characters, and some escape sequences that
11912 were formatted and diverted are treated like ordinary input
11913 characters when the diversion is reread. It can be also used for gross
11914 hacks; for example, the following sets register@tie{}@code{n} to@tie{}1.
11927 @xref{Copy-in Mode}.
11930 @Defreq {unformat, div}
11931 Like @code{asciify}, unformat the specified diversion.
11932 However, @code{unformat} only unformats spaces and tabs
11934 Unformatted tabs are treated as input tokens,
11935 and spaces are stretchable again.
11937 The vertical size of lines is not preserved; glyph information (font,
11938 font size, space width, etc.)@: is retained.
11942 @c =====================================================================
11944 @node Environments, Suppressing output, Diversions, gtroff Reference
11945 @section Environments
11946 @cindex environments
11948 It happens frequently that some text should be printed in a certain
11949 format regardless of what may be in effect at the time, for example, in
11950 a trap invoked macro to print headers and footers. To solve this
11951 @code{gtroff} processes text in @dfn{environments}. An
11952 environment contains most of the parameters that control text
11953 processing. It is possible to switch amongst these environments; by
11954 default @code{gtroff} processes text in environment@tie{}0. The
11955 following is the information kept in an environment.
11959 font parameters (size, family, style, glyph height and slant, space
11960 and sentence space size)
11963 page parameters (line length, title length, vertical spacing,
11964 line spacing, indentation, line numbering, centering, right-justifying,
11965 underlining, hyphenation data)
11968 fill and adjust mode
11971 tab stops, tab and leader characters, escape character,
11972 no-break and hyphen indicators, margin character data
11975 partially collected lines
11981 drawing and fill colours
11984 These environments may be given arbitrary names (see @ref{Identifiers},
11985 for more info). Old versions of @code{troff} only had environments
11986 named @samp{0}, @samp{1}, and @samp{2}.
11988 @DefreqList {ev, [@Var{env}]}
11989 @DefregListEnd {.ev}
11990 @cindex switching environments (@code{ev})
11991 @cindex environment, switching (@code{ev})
11992 @cindex environment number/name register (@code{.ev})
11993 Switch to another environment. The argument @var{env} is the name of
11994 the environment to switch to. With no argument, @code{gtroff} switches
11995 back to the previous environment. There is no limit on the number of
11996 named environments; they are created the first time that they are
11997 referenced. The @code{.ev} read-only register contains the name or
11998 number of the current environment. This is a string-valued register.
12000 Note that a call to @code{ev} (with argument) pushes the previously
12001 active environment onto a stack. If, say, environments @samp{foo},
12002 @samp{bar}, and @samp{zap} are called (in that order), the first
12003 @code{ev} request without parameter switches back to environment
12004 @samp{bar} (which is popped off the stack), and a second call
12005 switches back to environment @samp{foo}.
12007 Here is an example:
12020 \(dg Note the large, friendly letters.
12026 @cindex copying environment (@code{evc})
12027 @cindex environment, copying (@code{evc})
12028 Copy the environment @var{env} into the current environment.
12030 The following environment data is not copied:
12034 Partially filled lines.
12037 The status whether the previous line was interrupted.
12040 The number of lines still to center, or to right-justify, or to underline
12041 (with or without underlined spaces); they are set to zero.
12044 The status whether a temporary indent is active.
12047 Input traps and its associated data.
12050 Line numbering mode is disabled; it can be reactivated with
12054 The number of consecutive hyphenated lines (set to zero).
12061 @DefregListEnd {.csk}
12062 @cindex environment, dimensions of last glyph (@code{.w}, @code{.cht}, @code{.cdp}, @code{.csk})
12063 @cindex width, of last glyph (@code{.w})
12064 @cindex height, of last glyph (@code{.cht})
12065 @cindex depth, of last glyph (@code{.cdp})
12066 @cindex skew, of last glyph (@code{.csk})
12067 @cindex last glyph, dimensions (@code{.w}, @code{.cht}, @code{.cdp}, @code{.csk})
12068 @cindex glyph, last, dimensions (@code{.w}, @code{.cht}, @code{.cdp}, @code{.csk})
12069 The @code{\n[.w]} register contains the
12070 width of the last glyph added to the current environment.
12072 The @code{\n[.cht]} register contains the
12073 height of the last glyph added to the current environment.
12075 The @code{\n[.cdp]} register contains the
12076 depth of the last glyph added to the current environment.
12077 It is positive for glyphs extending below the baseline.
12079 The @code{\n[.csk]} register contains the
12080 @dfn{skew} (how far to the right of the glyph's center
12081 that @code{gtroff} should place an accent)
12082 of the last glyph added to the current environment.
12086 @cindex environment, previous line length (@code{.n})
12087 @cindex line length, previous (@code{.n})
12088 @cindex length of previous line (@code{.n})
12089 @cindex previous line length (@code{.n})
12090 The @code{\n[.n]} register contains the
12091 length of the previous output line in the current environment.
12095 @c =====================================================================
12097 @node Suppressing output, Colors, Environments, gtroff Reference
12098 @section Suppressing output
12100 @Defesc {\\O, , num, }
12101 @cindex suppressing output (@code{\O})
12102 @cindex output, suppressing (@code{\O})
12103 Disable or enable output depending on the value of @var{num}:
12107 Disable any glyphs from being emitted to the device driver, provided that
12108 the escape occurs at the outer level (see @code{\O[3]} and @code{\O[4]}).
12109 Motion is not suppressed so effectively @code{\O[0]} means @emph{pen up}.
12112 Enable output of glyphs, provided that the escape occurs at the outer
12120 @code{\O0} and @code{\O1} also reset the four registers @samp{opminx},
12121 @samp{opminy}, @samp{opmaxx}, and @samp{opmaxy} to @minus{}1.
12122 @xref{Register Index}. These four registers mark the top left and
12123 bottom right hand corners of a box which encompasses all written glyphs.
12125 For example the input text:
12128 Hello \O[0]world \O[1]this is a test.
12132 produces the following output:
12135 Hello this is a test.
12140 Provided that the escape occurs at the outer level, enable output of
12141 glyphs and also write out to @code{stderr} the page number and four
12142 registers encompassing the glyphs previously written since the last call
12146 Begin a nesting level. At start-up, @code{gtroff} is at outer level.
12149 End a nesting level.
12151 @item \O[5@var{P}@var{filename}]
12152 This escape is @code{grohtml} specific. Provided that this escape
12153 occurs at the outer nesting level write the @code{filename} to
12154 @code{stderr}. The position of the image, @var{P}, must be specified
12155 and must be one of @code{l}, @code{r}, @code{c}, or@tie{}@code{i} (left,
12156 right, centered, inline). @var{filename} will be associated with the
12157 production of the next inline image.
12161 @c =====================================================================
12163 @node Colors, I/O, Suppressing output, gtroff Reference
12167 @DefreqList {color, [@Var{n}]}
12168 @DefregListEnd {.color}
12169 If @var{n} is missing or non-zero, activate colors (this is the default);
12170 otherwise, turn it off.
12172 The read-only number register @code{.color} is@tie{}1 if colors are active,
12175 Internally, @code{color} sets a global flag; it does not produce a token.
12176 Similar to the @code{cp} request, you should use it at the beginning of
12177 your document to control color output.
12179 Colors can be also turned off with the @option{-c} command line option.
12182 @Defreq {defcolor, ident scheme color_components}
12183 Define color with name @var{ident}. @var{scheme} can be one of the
12184 following values: @code{rgb} (three components), @code{cmy} (three
12185 components), @code{cmyk} (four components), and @code{gray} or
12186 @code{grey} (one component).
12188 @cindex default color
12189 @cindex color, default
12190 Color components can be given either as a hexadecimal string or as
12191 positive decimal integers in the range 0--65535. A hexadecimal string
12192 contains all color components concatenated. It must start with either
12193 @code{#} or @code{##}; the former specifies hex values in the range
12194 0--255 (which are internally multiplied by@tie{}257), the latter in the
12195 range 0--65535. Examples: @code{#FFC0CB} (pink), @code{##ffff0000ffff}
12196 (magenta). The default color name @c{default} can't be redefined; its
12197 value is device-specific (usually black). It is possible that the
12198 default color for @code{\m} and @code{\M} is not identical.
12200 @cindex @code{f} unit, and colors
12201 @cindex unit, @code{f}, and colors
12202 A new scaling indicator@tie{}@code{f} has been introduced which multiplies
12203 its value by 65536; this makes it convenient to specify color components
12204 as fractions in the range 0 to@tie{}1 (1f equals 65536u). Example:
12207 .defcolor darkgreen rgb 0.1f 0.5f 0.2f
12210 Note that @code{f} is the default scaling indicator for the
12211 @code{defcolor} request, thus the above statement is equivalent to
12214 .defcolor darkgreen rgb 0.1 0.5 0.2
12218 @DefescList {\\m, , c, }
12219 @DefescItem {\\m, @lparen{}, co, }
12220 @DefescItem {\\m, @lbrack{}, color, @rbrack}
12221 @DefregListEnd {.m}
12222 Set drawing color. The following example shows how to turn the next four
12226 \m[red]these are in red\m[] and these words are in black.
12229 The escape @code{\m[]} returns to the previous color.
12231 @cindex drawing color name register (@code{.m})
12232 @cindex name, drawing color, register (@code{.m})
12233 @cindex color name, drawing, register (@code{.m})
12234 The name of the current drawing color is available in the read-only,
12235 string-valued number register @samp{.m}.
12237 The drawing color is associated with the current environment
12238 (@pxref{Environments}).
12240 Note that @code{\m} doesn't produce an input token in @code{gtroff}.
12241 As a consequence, it can be used in requests like @code{mc} (which
12242 expects a single character as an argument) to change the color on
12250 @DefescList {\\M, , c, }
12251 @DefescItem {\\M, @lparen{}, co, }
12252 @DefescItem {\\M, @lbrack{}, color, @rbrack}
12253 @DefregListEnd {.M}
12254 Set background color for filled objects drawn with the
12255 @code{\D'@dots{}'} commands.
12257 A red ellipse can be created with the following code:
12260 \M[red]\h'0.5i'\D'E 2i 1i'\M[]
12263 The escape @code{\M[]} returns to the previous fill color.
12265 @cindex background color name register (@code{.M})
12266 @cindex name, background color, register (@code{.M})
12267 @cindex color name, background, register (@code{.M})
12268 The name of the current background color is available in the read-only,
12269 string-valued number register @samp{.M}.
12271 The fill color is associated with the current environment
12272 (@pxref{Environments}).
12274 Note that @code{\M} doesn't produce an input token in @code{gtroff}.
12278 @c =====================================================================
12280 @node I/O, Postprocessor Access, Colors, gtroff Reference
12283 @cindex input and output requests
12284 @cindex requests for input and output
12285 @cindex output and input requests
12287 @code{gtroff} has several requests for including files:
12290 @cindex including a file (@code{so})
12291 @cindex file, inclusion (@code{so})
12292 Read in the specified @var{file} and
12293 includes it in place of the @code{so} request. This is quite useful for
12294 large documents, e.g.@: keeping each chapter in a separate file.
12295 @xref{gsoelim}, for more information.
12297 Since @code{gtroff} replaces the @code{so} request with the contents
12298 of @code{file}, it makes a difference whether the data is terminated with
12299 a newline or not: Assuming that file @file{xxx} contains the word
12300 @samp{foo} without a final newline, this
12309 yields @samp{This is foobar}.
12311 The search path for @var{file} can be controlled with the @option{-I} command
12315 @Defreq {pso, command}
12316 Read the standard output from the specified @var{command}
12317 and includes it in place of the @code{pso} request.
12320 @cindex mode, safer
12321 @cindex unsafe mode
12322 @cindex mode, unsafe
12323 This request causes an error if used in safer mode (which is the default).
12324 Use @code{groff}'s or @code{troff}'s @option{-U} option to activate unsafe
12327 The comment regarding a final newline for the @code{so} request is valid
12328 for @code{pso} also.
12331 @Defreq {mso, file}
12332 Identical to the @code{so} request except that @code{gtroff} searches for
12333 the specified @var{file} in the same directories as macro files for the
12334 the @option{-m} command line option. If the file name to be included
12335 has the form @file{@var{name}.tmac} and it isn't found, @code{mso} tries
12336 to include @file{tmac.@var{name}} and vice versa.
12339 @DefreqList {trf, file}
12340 @DefreqListEnd {cf, file}
12341 @cindex transparent output (@code{cf}, @code{trf})
12342 @cindex output, transparent (@code{cf}, @code{trf})
12343 Transparently output the contents of @var{file}. Each line is output
12344 as if it were preceded by @code{\!}; however, the lines are not subject
12345 to copy mode interpretation. If the file does not end with a newline,
12346 then a newline is added (@code{trf} only). For example, to define a
12347 macro@tie{}@code{x} containing the contents of file@tie{}@file{f}, use
12355 Both @code{trf} and @code{cf}, when used in a diversion,
12356 embeds an object in the diversion which, when reread, causes the
12357 contents of @var{file} to be transparently copied through to the
12358 output. In @acronym{UNIX} @code{troff}, the contents of @var{file}
12359 is immediately copied through to the output regardless of whether there
12360 is a current diversion; this behaviour is so anomalous that it must be
12363 @cindex @code{trf} request, and invalid characters
12364 @cindex characters, invalid for @code{trf} request
12365 @cindex invalid characters for @code{trf} request
12366 While @code{cf} copies the contents of @var{file} completely unprocessed,
12367 @code{trf} disallows characters such as NUL that are not valid
12368 @code{gtroff} input characters (@pxref{Identifiers}).
12370 Both requests cause a line break.
12373 @Defreq {nx, [@Var{file}]}
12374 @cindex processing next file (@code{nx})
12375 @cindex file, processing next (@code{nx})
12376 @cindex next file, processing (@code{nx})
12377 Force @code{gtroff} to continue processing of
12378 the file specified as an argument. If no argument is given, immediately
12379 jump to the end of file.
12382 @Defreq {rd, [@Var{prompt} [@Var{arg1} @Var{arg2} @dots{}]]}
12383 @cindex reading from standard input (@code{rd})
12384 @cindex standard input, reading from (@code{rd})
12385 @cindex input, standard, reading from (@code{rd})
12386 Read from standard input, and include what is read as though it
12387 were part of the input file. Text is read until a blank line
12390 If standard input is a TTY input device (keyboard), write @var{prompt}
12391 to standard error, followed by a colon (or send BEL for a beep if no
12392 argument is given).
12394 Arguments after @var{prompt} are available for the input. For example,
12401 with the input @w{@samp{This is \$2.}} prints
12408 @cindex form letters
12409 @cindex letters, form
12410 Using the @code{nx} and @code{rd} requests,
12411 it is easy to set up form letters. The form
12412 letter template is constructed like this, putting the following lines
12413 into a file called @file{repeat.let}:
12429 @cindex @code{ex} request, used with @code{nx} and @code{rd}
12431 When this is run, a file containing the following lines should be
12432 redirected in. Note that requests included in this file are executed
12433 as though they were part of the form letter. The last block of input
12434 is the @code{ex} request which tells @code{groff} to stop processing. If
12435 this was not there, @code{groff} would not know when to stop.
12439 708 NW 19th Av., #202
12446 San Diego, CA 92103
12454 Pipe the output of @code{gtroff} to the shell command(s)
12455 specified by @var{pipe}. This request must occur before
12456 @code{gtroff} has a chance to print anything.
12459 @cindex mode, safer
12460 @cindex unsafe mode
12461 @cindex mode, unsafe
12462 @code{pi} causes an error if used in safer mode (which is the default).
12463 Use @code{groff}'s or @code{troff}'s @option{-U} option to activate unsafe
12466 Multiple calls to @code{pi} are allowed, acting as a chain. For example,
12474 is the same as @w{@samp{.pi foo | bar}}.
12476 @cindex @code{groff}, and @code{pi} request
12477 @cindex @code{pi} request, and @code{groff}
12478 Note that the intermediate output format of @code{gtroff} is piped to
12479 the specified commands. Consequently, calling @code{groff} without the
12480 @option{-Z} option normally causes a fatal error.
12483 @DefreqList {sy, cmds}
12484 @DefregListEnd {systat}
12485 Execute the shell command(s) specified by @var{cmds}. The output is not
12486 saved anyplace, so it is up to the user to do so.
12489 @cindex mode, safer
12490 @cindex unsafe mode
12491 @cindex mode, unsafe
12492 This request causes an error if used in safer mode (which is the default).
12493 Use @code{groff}'s or @code{troff}'s @option{-U} option to activate unsafe
12496 For example, the following code fragment introduces the current time into a
12499 @cindex time, current
12500 @cindex current time
12503 .sy perl -e 'printf ".nr H %d\\n.nr M %d\\n.nr S %d\\n",\
12504 (localtime(time))[2,1,0]' > /tmp/x\n[$$]
12506 .sy rm /tmp/x\n[$$]
12511 Note that this works by having the @code{perl} script (run by @code{sy})
12512 print out the @code{nr} requests which set the number registers
12513 @code{H}, @code{M}, and @code{S}, and then reads those commands in with
12514 the @code{so} request.
12516 For most practical purposes, the number registers @code{seconds},
12517 @code{minutes}, and @code{hours} which are initialized at start-up of
12518 @code{gtroff} should be sufficient. Use the @code{af} request to get a
12525 \n[hours]:\n[minutes]:\n[seconds]
12528 @cindex @code{system()} return value register (@code{systat})
12529 The @code{systat} read-write number register contains the return value
12530 of the @code{system()} function executed by the last @code{sy} request.
12533 @DefreqList {open, stream file}
12534 @DefreqListEnd {opena, stream file}
12535 @cindex opening file (@code{open})
12536 @cindex file, opening (@code{open})
12537 @cindex appending to a file (@code{opena})
12538 @cindex file, appending to (@code{opena})
12539 Open the specified @var{file} for writing and
12540 associates the specified @var{stream} with it.
12542 The @code{opena} request is like @code{open}, but if the file exists,
12543 append to it instead of truncating it.
12546 @cindex mode, safer
12547 @cindex unsafe mode
12548 @cindex mode, unsafe
12549 Both @code{open} and @code{opena} cause an error if used in safer mode
12550 (which is the default). Use @code{groff}'s or @code{troff}'s @option{-U}
12551 option to activate unsafe mode.
12554 @DefreqList {write, stream data}
12555 @DefreqListEnd {writec, stream data}
12556 @cindex copy-in mode, and @code{write} requests
12557 @cindex mode, copy-in, and @code{write} requests
12558 @cindex writing to file (@code{write})
12559 @cindex file, writing to (@code{write})
12560 Write to the file associated with the specified @var{stream}.
12561 The stream must previously have
12562 been the subject of an open request. The remainder of the line is
12563 interpreted as the @code{ds} request reads its second argument: A
12564 leading @samp{"} is stripped, and it is read in copy-in mode.
12566 The @code{writec} request is like @code{write}, but only
12567 @code{write} appends a newline to the data.
12570 @Defreq {writem, stream xx}
12571 @cindex @code{asciify} request, and @code{writem}
12572 Write the contents of the macro or string @var{xx}
12573 to the file associated with the specified @var{stream}.
12575 @var{xx} is read in copy mode, i.e., already formatted elements are
12576 ignored. Consequently, diversions must be unformatted with the
12577 @code{asciify} request before calling @code{writem}. Usually, this
12578 means a loss of information.
12581 @Defreq {close, stream}
12582 @cindex closing file (@code{close})
12583 @cindex file, closing (@code{close})
12584 Close the specified @var{stream};
12585 the stream is no longer an acceptable argument to the
12586 @code{write} request.
12588 Here a simple macro to write an index entry.
12594 . write idx \\n[%] \\$*
12603 @DefescList {\\V, , e, }
12604 @DefescItem {\\V, @lparen{}, ev, }
12605 @DefescListEnd {\\V, @lbrack{}, env, @rbrack}
12606 Interpolate the contents of the specified environment variable
12607 @var{env} (one-character name@tie{}@var{e}, two-character name @var{ev})
12608 as returned by the function @code{getenv}. @code{\V} is interpreted
12613 @c =====================================================================
12615 @node Postprocessor Access, Miscellaneous, I/O, gtroff Reference
12616 @section Postprocessor Access
12617 @cindex postprocessor access
12618 @cindex access of postprocessor
12620 There are two escapes which give information directly to the
12621 postprocessor. This is particularly useful for embedding
12622 @sc{PostScript} into the final document.
12624 @Defesc {\\X, ', xxx, '}
12625 Embeds its argument into the @code{gtroff}
12626 output preceded with @w{@samp{x X}}.
12628 @cindex @code{\&}, in @code{\X}
12629 @cindex @code{\)}, in @code{\X}
12630 @cindex @code{\%}, in @code{\X}
12632 @cindex @code{\:}, in @code{\X}
12635 @cindex @code{\@r{<colon>}}, in @code{\X}
12637 The escapes @code{\&}, @code{\)}, @code{\%}, and @code{\:} are ignored
12638 within @code{\X}, @w{@samp{\ }} and @code{\~} are converted to single
12639 space characters. All other escapes (except @code{\\} which produces a
12640 backslash) cause an error.
12642 @kindex use_charnames_in_special
12643 @pindex DESC@r{, and @code{use_charnames_in_special}}
12644 @cindex @code{\X}, and special characters
12645 If the @samp{use_charnames_in_special} keyword is set in the @file{DESC}
12646 file, special characters no longer cause an error; the name @var{xx} is
12647 represented as @samp{\(@var{xx})} in the @w{@samp{x X}} output command.
12648 Additionally, the backslash is represented as @code{\\}.
12650 @samp{use_charnames_in_special} is currently used by @code{grohtml} only.
12653 @DefescList {\\Y, , n, }
12654 @DefescItem {\\Y, @lparen{}, nm, }
12655 @DefescListEnd {\\Y, @lbrack{}, name, @rbrack}
12656 This is approximately equivalent to @samp{\X'\*[@var{name}]'}
12657 (one-character name@tie{}@var{n}, two-character name @var{nm}).
12658 However, the contents of the string or macro @var{name} are not
12659 interpreted; also it is permitted for @var{name} to have been defined
12660 as a macro and thus contain newlines (it is not permitted for the
12661 argument to @code{\X} to contain newlines). The inclusion of
12662 newlines requires an extension to the @acronym{UNIX} @code{troff}
12663 output format, and confuses drivers that do not know about this
12664 extension (@pxref{Device Control Commands}).
12667 @xref{Output Devices}.
12670 @c =====================================================================
12672 @node Miscellaneous, Gtroff Internals, Postprocessor Access, gtroff Reference
12673 @section Miscellaneous
12675 This section documents parts of @code{gtroff} which cannot (yet) be
12676 categorized elsewhere in this manual.
12678 @Defreq {nm, [@Var{start} [@Var{inc} [@Var{space} [@Var{indent}]]]]}
12679 @cindex printing line numbers (@code{nm})
12680 @cindex line numbers, printing (@code{nm})
12681 @cindex numbers, line, printing (@code{nm})
12682 Print line numbers.
12683 @var{start} is the line number of the @emph{next}
12684 output line. @var{inc} indicates which line numbers are printed.
12685 For example, the value@tie{}5 means to emit only line numbers which
12686 are multiples of@tie{}5; this defaults to@tie{}1. @var{space} is the
12687 space to be left between the number and the text; this defaults to
12688 one digit space. The fourth argument is the indentation of the line
12689 numbers, defaulting to zero. Both @var{space} and @var{indent} are
12690 given as multiples of digit spaces; they can be negative also.
12691 Without any arguments, line numbers are turned off.
12693 @code{gtroff} reserves three digit spaces for the line number (which is
12694 printed right-justified) plus the amount given by @var{indent}; the
12695 output lines are concatenated to the line numbers, separated by
12696 @var{space}, and @emph{without} reducing the line length. Depending
12697 on the value of the horizontal page offset (as set with the
12698 @code{po} request), line numbers which are longer than the reserved
12699 space stick out to the left, or the whole line is moved to the right.
12701 Parameters corresponding to missing arguments are not changed; any
12702 non-digit argument (to be more precise, any argument starting with a
12703 character valid as a delimiter for identifiers) is also treated as
12706 If line numbering has been disabled with a call to @code{nm} without
12707 an argument, it can be reactivated with @samp{.nm +0}, using the
12708 previously active line numbering parameters.
12710 The parameters of @code{nm} are associated with the current environment
12711 (@pxref{Environments}). The current output line number is available
12712 in the number register @code{ln}.
12717 This test shows how line numbering works with groff.
12719 This test shows how line numbering works with groff.
12723 This test shows how line numbering works with groff.
12725 This test shows how line numbering works with groff.
12729 And here the result:
12732 This test shows how
12733 line numbering works
12734 999 with groff. This
12735 1000 test shows how line
12736 1001 numbering works with
12738 This test shows how
12741 This test shows how
12742 1005 line numbering
12747 @Defreq {nn, [@Var{skip}]}
12748 Temporarily turn off line numbering. The argument is the number
12749 of lines not to be numbered; this defaults to@tie{}1.
12752 @Defreq {mc, glyph [@Var{dist}]}
12753 @cindex margin glyph (@code{mc})
12754 @cindex glyph, for margins (@code{mc})
12755 Print a @dfn{margin character} to the right of the
12756 text.@footnote{@dfn{Margin character} is a misnomer since it is an
12757 output glyph.} The first argument is the glyph to be
12758 printed. The second argument is the distance away from the right
12759 margin. If missing, the previously set value is used; default is
12760 10@dmn{pt}). For text lines that are too long (that is, longer than
12761 the text length plus @var{dist}), the margin character is directly
12762 appended to the lines.
12764 With no arguments the margin character is turned off.
12765 If this occurs before a break, no margin character is printed.
12767 For compatibility with @acronym{AT&T} @code{troff}, a call to @code{mc}
12768 to set the margin character can't be undone immediately; at least one
12769 line gets a margin character. Thus
12788 @cindex @code{tl} request, and @code{mc}
12789 For empty lines and lines produced by the @code{tl} request no margin
12790 character is emitted.
12792 The margin character is associated with the current environment
12793 (@pxref{Environments}).
12797 This is quite useful for indicating text that has changed, and, in fact,
12798 there are programs available for doing this (they are called
12799 @code{nrchbar} and @code{changebar} and can be found in any
12800 @samp{comp.sources.unix} archive).
12805 This paragraph is highlighted with a margin
12808 Note that vertical space isn't marked.
12812 But we can fake it with `\&'.
12818 This paragraph is highlighted |
12819 with a margin character. |
12821 Note that vertical space isn't |
12824 But we can fake it with `\&'. |
12828 @DefreqList {psbb, filename}
12832 @DefregListEnd {ury}
12833 @cindex PostScript, bounding box
12834 @cindex bounding box
12835 Retrieve the bounding box of the PostScript image
12836 found in @var{filename}.
12837 The file must conform to
12838 Adobe's @dfn{Document Structuring Conventions} (DSC);
12839 the command searches for a @code{%%BoundingBox} comment
12840 and extracts the bounding box values into the number registers
12841 @code{llx}, @code{lly}, @code{urx}, and @code{ury}.
12842 If an error occurs (for example, @code{psbb} cannot find
12843 the @code{%%BoundingBox} comment),
12844 it sets the four number registers to zero.
12846 The search path for @var{filename} can be controlled with the @option{-I}
12847 command line option.
12851 @c =====================================================================
12853 @node Gtroff Internals, Debugging, Miscellaneous, gtroff Reference
12854 @section @code{gtroff} Internals
12856 @cindex input token
12857 @cindex token, input
12858 @cindex output node
12859 @cindex node, output
12860 @code{gtroff} processes input in three steps. One or more input
12861 characters are converted to an @dfn{input token}.@footnote{Except the
12862 escapes @code{\f}, @code{\F}, @code{\H}, @code{\m}, @code{\M}, @code{\R},
12863 @code{\s}, and @code{\S} which are processed immediately if not in
12864 copy-in mode.} Then, one or more input tokens are converted to an
12865 @dfn{output node}. Finally, output nodes are converted to the
12866 intermediate output language understood by all output devices.
12868 Actually, before step one happens, @code{gtroff} converts certain
12869 escape sequences into reserved input characters (not accessible by
12870 the user); such reserved characters are used for other internal
12871 processing also -- this is the very reason why not all characters
12872 are valid input. @xref{Identifiers}, for more on this topic.
12874 For example, the input string @samp{fi\[:u]} is converted into a
12875 character token @samp{f}, a character token @samp{i}, and a special
12876 token @samp{:u} (representing u@tie{}umlaut). Later on, the character
12877 tokens @samp{f} and @samp{i} are merged to a single output node
12878 representing the ligature glyph @samp{fi} (provided the current font
12879 has a glyph for this ligature); the same happens with @samp{:u}. All
12880 output glyph nodes are `processed' which means that they are invariably
12881 associated with a given font, font size, advance width, etc. During
12882 the formatting process, @code{gtroff} itself adds various nodes to
12883 control the data flow.
12885 Macros, diversions, and strings collect elements in two chained lists:
12886 a list of input tokens which have been passed unprocessed, and a list
12887 of output nodes. Consider the following the diversion.
12899 It contains these elements.
12901 @multitable {@i{vertical size node}} {token list} {element number}
12902 @item node list @tab token list @tab element number
12904 @item @i{line start node} @tab --- @tab 1
12905 @item @i{glyph node @code{a}} @tab --- @tab 2
12906 @item @i{word space node} @tab --- @tab 3
12907 @item --- @tab @code{b} @tab 4
12908 @item --- @tab @code{\n} @tab 5
12909 @item @i{glyph node @code{c}} @tab --- @tab 6
12910 @item @i{vertical size node} @tab --- @tab 7
12911 @item @i{vertical size node} @tab --- @tab 8
12912 @item --- @tab @code{\n} @tab 9
12915 @cindex @code{\v}, internal representation
12917 Elements 1, 7, and@tie{}8 are inserted by @code{gtroff}; the latter two
12918 (which are always present) specify the vertical extent of the last
12919 line, possibly modified by @code{\x}. The @code{br} request finishes
12920 the current partial line, inserting a newline input token which is
12921 subsequently converted to a space when the diversion is reread. Note
12922 that the word space node has a fixed width which isn't stretchable
12923 anymore. To convert horizontal space nodes back to input tokens, use
12924 the @code{unformat} request.
12926 Macros only contain elements in the token list (and the node list is
12927 empty); diversions and strings can contain elements in both lists.
12929 Note that the @code{chop} request simply reduces the number of elements in a
12930 macro, string, or diversion by one. Exceptions are @dfn{compatibility save}
12931 and @dfn{compatibility ignore} input tokens which are ignored. The
12932 @code{substring} request also ignores those input tokens.
12934 Some requests like @code{tr} or @code{cflags} work on glyph
12935 identifiers only; this means that the associated glyph can be changed
12936 without destroying this association. This can be very helpful for
12937 substituting glyphs. In the following example, we assume that
12938 glyph @samp{foo} isn't available by default, so we provide a
12939 substitution using the @code{fchar} request and map it to input
12940 character @samp{x}.
12948 Now let us assume that we install an additional special font
12949 @samp{bar} which has glyph @samp{foo}.
12957 Since glyphs defined with @code{fchar} are searched before glyphs
12958 in special fonts, we must call @code{rchar} to remove the definition
12959 of the fallback glyph. Anyway, the translation is still active;
12960 @samp{x} now maps to the real glyph @samp{foo}.
12963 @c =====================================================================
12965 @node Debugging, Implementation Differences, Gtroff Internals, gtroff Reference
12969 @code{gtroff} is not easy to debug, but there are some useful features
12970 and strategies for debugging.
12972 @Defreq {lf, line [@Var{filename}]}
12974 @cindex multi-file documents
12975 @cindex documents, multi-file
12976 @cindex setting input line number (@code{lf})
12977 @cindex input line number, setting (@code{lf})
12978 @cindex number, input line, setting (@code{lf})
12979 Change the line number and optionally the file name @code{gtroff} shall
12980 use for error and warning messages. @var{line} is the input line number
12981 of the @emph{next} line.
12983 Without argument, the request is ignored.
12985 This is a debugging aid for documents which are split into many files,
12986 then put together with @code{soelim} and other preprocessors. Usually,
12987 it isn't invoked manually.
12989 Note that other @code{troff} implementations (including the original
12990 @acronym{AT&T} version) handle @code{lf} differently. For them,
12991 @var{line} changes the line number of the @emph{current} line.
12994 @DefreqList {tm, string}
12995 @DefreqItem {tm1, string}
12996 @DefreqListEnd {tmc, string}
12997 @cindex printing to stderr (@code{tm}, @code{tm1}, @code{tmc})
12998 @cindex stderr, printing to (@code{tm}, @code{tm1}, @code{tmc})
12999 Send @var{string} to the standard error output;
13000 this is very useful for printing debugging messages among other things.
13002 @var{string} is read in copy mode.
13004 The @code{tm} request ignores leading spaces of @var{string}; @code{tm1}
13005 handles its argument similar to the @code{ds} request: a leading double
13006 quote in @var{string} is stripped to allow initial blanks.
13008 The @code{tmc} request is similar to @code{tm1} but does
13009 not append a newline (as is done in @code{tm} and @code{tm1}).
13012 @Defreq {ab, [@Var{string}]}
13013 @cindex aborting (@code{ab})
13014 Similar to the @code{tm} request, except that
13015 it causes @code{gtroff} to stop processing. With no argument it
13016 prints @samp{User Abort.} to standard error.
13020 @cindex @code{ex} request, use in debugging
13021 @cindex exiting (@code{ex})
13022 The @code{ex} request also causes @code{gtroff} to stop processing;
13023 see also @ref{I/O}.
13026 When doing something involved it is useful to leave the debugging
13027 statements in the code and have them turned on by a command line flag.
13030 .if \n(DB .tm debugging output
13034 To activate these statements say
13040 If it is known in advance that there will be many errors and no useful
13041 output, @code{gtroff} can be forced to suppress formatted output with
13042 the @option{-z} flag.
13045 @cindex dumping symbol table (@code{pm})
13046 @cindex symbol table, dumping (@code{pm})
13047 Print the entire symbol table on @code{stderr}. Names of all defined
13048 macros, strings, and diversions are print together with their size in
13049 bytes. Since @code{gtroff} sometimes adds nodes by itself, the
13050 returned size can be larger than expected.
13052 This request differs from @acronym{UNIX} @code{troff}: @code{gtroff}
13053 reports the sizes of diversions, ignores an additional argument to
13054 print only the total of the sizes, and the size isn't returned in
13055 blocks of 128 characters.
13059 @cindex dumping number registers (@code{pnr})
13060 @cindex number registers, dumping (@code{pnr})
13061 Print the names and contents of all
13062 currently defined number registers on @code{stderr}.
13066 @cindex dumping traps (@code{ptr})
13067 @cindex traps, dumping (@code{ptr})
13068 Print the names and positions of all traps
13069 (not including input line traps and diversion traps) on @code{stderr}.
13070 Empty slots in the page trap list are printed as well, because they can
13071 affect the priority of subsequently planted traps.
13075 @cindex flush output (@code{fl})
13076 @cindex output, flush (@code{fl})
13077 @cindex interactive use of @code{gtroff}
13078 @cindex @code{gtroff}, interactive use
13079 Instruct @code{gtroff} to flush its output immediately. The intent
13080 is for interactive use, but this behaviour is currently not
13081 implemented in @code{gtroff}. Contrary to @acronym{UNIX} @code{troff},
13082 TTY output is sent to a device driver also (@code{grotty}), making it
13083 non-trivial to communicate interactively.
13085 This request causes a line break.
13088 @Defreq {backtrace, }
13089 @cindex backtrace of input stack (@code{backtrace})
13090 @cindex input stack, backtrace (@code{backtrace})
13091 Print a backtrace of the input stack to the standard error stream.
13093 Consider the following in file @file{test}:
13107 On execution, @code{gtroff} prints the following:
13110 test:2: backtrace: macro `xxx'
13111 test:5: backtrace: macro `yyy'
13112 test:8: backtrace: file `test'
13115 The option @option{-b} of @code{gtroff} internally calls a variant of
13116 this request on each error and warning.
13120 @cindex input stack, setting limit
13121 Use the @code{slimit} number register
13122 to set the maximum number of objects on the input stack.
13123 If @code{slimit} is less than or equal to@tie{}0,
13124 there is no limit set.
13125 With no limit, a buggy recursive macro can exhaust virtual memory.
13127 The default value is 1000; this is a compile-time constant.
13130 @Defreq {warnscale, si}
13131 Set the scaling indicator used in warnings to @var{si}. Valid values for
13132 @var{si} are @samp{u}, @samp{i}, @samp{c}, @samp{p}, and @samp{P}. At
13133 startup, it is set to @samp{i}.
13136 @Defreq {spreadwarn, [@Var{limit}]}
13137 Make @code{gtroff} emit a warning if the additional space inserted for
13138 each space between words in an output line is larger or equal to
13139 @var{limit}. A negative value is changed to zero; no argument toggles the
13140 warning on and off without changing @var{limit}. The default scaling
13141 indicator is @samp{m}. At startup, @code{spreadwarn} is deactivated, and
13142 @var{limit} is set to 3@dmn{m}.
13151 will cause a warning if @code{gtroff} must add 0.2@dmn{m} or more for each
13152 interword space in a line.
13154 This request is active only if text is justified to both margins (using
13159 @code{gtroff} has command line options for printing out more warnings
13160 (@option{-w}) and for printing backtraces (@option{-b}) when a warning
13161 or an error occurs. The most verbose level of warnings is @option{-ww}.
13163 @DefreqList {warn, [@Var{flags}]}
13164 @DefregListEnd {.warn}
13165 @cindex level of warnings (@code{warn})
13166 @cindex warnings, level (@code{warn})
13167 Control the level of warnings checked for. The @var{flags} are the sum
13168 of the numbers associated with each warning that is to be enabled; all
13169 other warnings are disabled. The number associated with each warning is
13170 listed below. For example, @w{@code{.warn 0}} disables all warnings,
13171 and @w{@code{.warn 1}} disables all warnings except that about missing
13172 glyphs. If no argument is given, all warnings are enabled.
13174 The read-only number register @code{.warn} contains the current warning
13182 @c ---------------------------------------------------------------------
13184 @node Warnings, , Debugging, Debugging
13185 @subsection Warnings
13188 The warnings that can be given to @code{gtroff} are divided into the
13189 following categories. The name associated with each warning is used by
13190 the @option{-w} and @option{-W} options; the number is used by the
13191 @code{warn} request and by the @code{.warn} register.
13196 Non-existent glyphs.@footnote{@code{char} is a misnomer since it reports
13197 missing glyphs -- there aren't missing input characters, only invalid
13198 ones.} This is enabled by default.
13202 Invalid numeric expressions. This is enabled by default.
13203 @xref{Expressions}.
13209 In fill mode, lines which could not be broken so that their length was
13210 less than the line length. This is enabled by default.
13214 Missing or mismatched closing delimiters.
13218 @cindex @code{ie} request, and warnings
13219 @cindex @code{el} request, and warnings
13220 Use of the @code{el} request with no matching @code{ie} request.
13225 Meaningless scaling indicators.
13229 Out of range arguments.
13233 Dubious syntax in numeric expressions.
13237 @cindex @code{di} request, and warnings
13238 @cindex @code{da} request, and warnings
13239 Use of @code{di} or @code{da} without an argument when there is no
13244 @cindex @code{de}, @code{de1}, @code{dei} requests, and warnings
13245 @cindex @code{am}, @code{am1}, @code{ami} requests, and warnings
13246 @cindex @code{ds}, @code{ds1} requests, and warnings
13247 @cindex @code{as}, @code{as1} requests, and warnings
13248 @cindex @code{di} request, and warnings
13249 @cindex @code{da} request, and warnings
13250 @cindex @code{box}, @code{boxa} requests, and warnings
13251 @cindex @code{\*}, and warnings
13252 Use of undefined strings, macros and diversions. When an undefined
13253 string, macro, or diversion is used, that string is automatically
13254 defined as empty. So, in most cases, at most one warning is given
13259 @cindex @code{nr} request, and warnings
13260 @cindex @code{\R}, and warnings
13261 @cindex @code{\n}, and warnings
13262 Use of undefined number registers. When an undefined number register is
13263 used, that register is automatically defined to have a value of@tie{}0.
13264 So, in most cases, at most one warning is given for use of a particular
13269 @cindex @code{\t}, and warnings
13270 Use of a tab character where a number was expected.
13274 @cindex @code{\@}}, and warnings
13275 Use of @code{\@}} where a number was expected.
13279 Requests that are missing non-optional arguments.
13283 Invalid input characters.
13287 Unrecognized escape sequences. When an unrecognized escape sequence
13288 @code{\@var{X}} is encountered, the escape character is ignored, and
13289 @var{X} is printed.
13293 @cindex compatibility mode
13294 Missing space between a request or macro and its argument. This warning
13295 is given when an undefined name longer than two characters is
13296 encountered, and the first two characters of the name make a defined
13297 name. The request or macro is not invoked. When this warning is
13298 given, no macro is automatically defined. This is enabled by default.
13299 This warning never occurs in compatibility mode.
13303 Non-existent fonts. This is enabled by default.
13307 Invalid escapes in text ignored with the @code{ig} request. These are
13308 conditions that are errors when they do not occur in ignored text.
13312 Color related warnings.
13315 All warnings except @samp{di}, @samp{mac} and @samp{reg}. It is
13316 intended that this covers all warnings that are useful with traditional
13324 @c =====================================================================
13326 @node Implementation Differences, , Debugging, gtroff Reference
13327 @section Implementation Differences
13328 @cindex implementation differences
13329 @cindex differences in implementation
13330 @cindex incompatibilities with @acronym{AT&T} @code{troff}
13331 @cindex compatibility mode
13332 @cindex mode, compatibility
13334 GNU @code{troff} has a number of features which cause incompatibilities
13335 with documents written with old versions of @code{troff}.
13338 @cindex names, long
13339 Long names cause some incompatibilities. @acronym{UNIX} @code{troff}
13346 @cindex @code{\*}, incompatibilities with @acronym{AT&T} @code{troff}
13347 @cindex @code{\n}, incompatibilities with @acronym{AT&T} @code{troff}
13349 as defining a string @samp{ab} with contents @samp{cd}. Normally, GNU
13350 @code{troff} interprets this as a call of a macro named
13351 @code{dsabcd}. Also @acronym{UNIX} @code{troff} interprets
13352 @code{\*[} or @code{\n[} as references to a string or number register
13353 called @samp{[}. In GNU @code{troff}, however, this is normally
13354 interpreted as the start of a long name. In compatibility mode GNU
13355 @code{troff} interprets long names in the traditional way
13356 (which means that they are not recognized as names).
13358 @DefreqList {cp, [@Var{n}]}
13359 @DefreqItem {do, cmd}
13360 @DefregListEnd {.C}
13361 If @var{n} is missing or non-zero, turn on compatibility mode;
13362 otherwise, turn it off.
13364 The read-only number register @code{.C} is@tie{}1 if compatibility mode is
13365 on, 0@tie{}otherwise.
13367 Compatibility mode can be also turned on with the @option{-C} command line
13370 The @code{do} request turns off compatibility mode
13371 while executing its arguments as a @code{gtroff} command.
13378 executes the @code{fam} request when compatibility mode
13381 @code{gtroff} restores the previous compatibility setting
13382 before interpreting any files sourced by the @var{cmd}.
13385 @cindex input level in delimited arguments
13386 @cindex delimited arguments, incompatibilities with @acronym{AT&T} @code{troff}
13387 Two other features are controlled by @option{-C}. If not in
13388 compatibility mode, GNU @code{troff} preserves the input level in
13389 delimited arguments:
13397 In compatibility mode, the string @samp{72def'} is returned; without
13398 @option{-C} the resulting string is @samp{168} (assuming a TTY output
13401 @cindex @code{\f}, incompatibilities with @acronym{AT&T} @code{troff}
13402 @cindex @code{\H}, incompatibilities with @acronym{AT&T} @code{troff}
13403 @cindex @code{\s}, incompatibilities with @acronym{AT&T} @code{troff}
13404 @cindex @code{\S}, incompatibilities with @acronym{AT&T} @code{troff}
13405 Finally, the escapes @code{\f}, @code{\H}, @code{\m}, @code{\M},
13406 @code{\R}, @code{\s}, and @code{\S} are transparent for recognizing the
13407 beginning of a line only in compatibility mode (this is a rather obscure
13408 feature). For example, the code
13418 prints @samp{Hallo!} in bold face if in compatibility mode, and
13419 @samp{.xx} in bold face otherwise.
13421 @cindex @code{\A}, incompatibilities with @acronym{AT&T} @code{troff}
13422 @cindex @code{\|}, incompatibilities with @acronym{AT&T} @code{troff}
13423 @cindex @code{\^}, incompatibilities with @acronym{AT&T} @code{troff}
13424 @cindex @code{\&}, incompatibilities with @acronym{AT&T} @code{troff}
13425 @cindex @code{\@{}, incompatibilities with @acronym{AT&T} @code{troff}
13426 @cindex @code{\@}}, incompatibilities with @acronym{AT&T} @code{troff}
13427 @cindex @code{\@key{SP}}, incompatibilities with @acronym{AT&T} @code{troff}
13428 @cindex @code{\'}, incompatibilities with @acronym{AT&T} @code{troff}
13429 @cindex @code{\`}, incompatibilities with @acronym{AT&T} @code{troff}
13430 @cindex @code{\-}, 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{\c}, incompatibilities with @acronym{AT&T} @code{troff}
13435 GNU @code{troff} does not allow the use of the escape sequences
13436 @code{\|}, @code{\^}, @code{\&}, @code{\@{}, @code{\@}},
13437 @code{\@key{SP}}, @code{\'}, @code{\`}, @code{\-}, @code{\_}, @code{\!},
13438 @code{\%}, and @code{\c} in names of strings, macros, diversions, number
13439 registers, fonts or environments; @acronym{UNIX} @code{troff} does. The
13440 @code{\A} escape sequence (@pxref{Identifiers}) may be helpful in
13441 avoiding use of these escape sequences in names.
13443 @cindex fractional point sizes
13444 @cindex fractional type sizes
13445 @cindex point sizes, fractional
13446 @cindex type sizes, fractional
13447 @cindex sizes, fractional
13448 @cindex @code{ps} request, incompatibilities with @acronym{AT&T} @code{troff}
13449 Fractional point sizes cause one noteworthy incompatibility. In
13450 @acronym{UNIX} @code{troff} the @code{ps} request ignores scale
13451 indicators and thus
13458 sets the point size to 10@tie{}points, whereas in GNU @code{troff} it
13459 sets the point size to 10@tie{}scaled points. @xref{Fractional Type
13460 Sizes}, for more information.
13462 @cindex @code{bd} request, incompatibilities with @acronym{AT&T} @code{troff}
13463 @cindex @code{cs} request, incompatibilities with @acronym{AT&T} @code{troff}
13464 @cindex @code{tr} request, incompatibilities with @acronym{AT&T} @code{troff}
13465 @cindex @code{fp} request, incompatibilities with @acronym{AT&T} @code{troff}
13466 @cindex input characters and output glyphs, compatibility with @acronym{AT&T} @code{troff}
13467 @cindex output glyphs, and input characters,compatibility with @acronym{AT&T} @code{troff}
13468 @cindex characters, input, and output glyphs, compatibility with @acronym{AT&T} @code{troff}
13469 @cindex glyphs, output, and input characters, compatibility with @acronym{AT&T} @code{troff}
13470 In GNU @code{troff} there is a fundamental difference between
13471 (unformatted) input characters and (formatted) output glyphs.
13472 Everything that affects how a glyph is output is stored
13473 with the glyph node; once a glyph node has been constructed it is
13474 unaffected by any subsequent requests that are executed, including
13475 @code{bd}, @code{cs}, @code{tkf}, @code{tr}, or @code{fp} requests.
13476 Normally glyphs are constructed from input characters at the
13477 moment immediately before the glyph is added to the current output
13478 line. Macros, diversions and strings are all, in fact, the same type of
13479 object; they contain lists of input characters and glyph nodes in
13480 any combination. A glyph node does not behave like an input
13481 character for the purposes of macro processing; it does not inherit any
13482 of the special properties that the input character from which it was
13483 constructed might have had. For example,
13493 @cindex printing backslash (@code{\\}, @code{\e}, @code{\E}, @code{\[rs]})
13494 @cindex backslash, printing (@code{\\}, @code{\e}, @code{\E}, @code{\[rs]})
13495 @cindex @code{\e}, incompatibilities with @acronym{AT&T} @code{troff}
13496 @cindex @code{\!}, incompatibilities with @acronym{AT&T} @code{troff}
13497 @cindex @code{\?}, incompatibilities with @acronym{AT&T} @code{troff}
13498 @cindex transparent output, incompatibilities with @acronym{AT&T} @code{troff}
13499 @cindex output, transparent, incompatibilities with @acronym{AT&T} @code{troff}
13501 prints @samp{\\} in GNU @code{troff}; each pair of input backslashes
13502 is turned into one output backslash and the resulting output backslashes
13503 are not interpreted as escape characters when they are reread.
13504 @acronym{UNIX} @code{troff} would interpret them as escape characters
13505 when they were reread and would end up printing one @samp{\}. The
13506 correct way to obtain a printable backslash is to use the @code{\e}
13507 escape sequence: This always prints a single instance of the current
13508 escape character, regardless of whether or not it is used in a
13509 diversion; it also works in both GNU @code{troff} and @acronym{UNIX}
13510 @code{troff}.@footnote{To be completely independent of the current
13511 escape character, use @code{\(rs} which represents a reverse solidus
13512 (backslash) glyph.} To store, for some reason, an escape sequence in a
13513 diversion that will be interpreted when the diversion is reread, either
13514 use the traditional @code{\!} transparent output facility, or, if this
13515 is unsuitable, the new @code{\?} escape sequence.
13517 @xref{Diversions}, and @ref{Gtroff Internals}, for more information.
13521 @c =====================================================================
13522 @c =====================================================================
13524 @node Preprocessors, Output Devices, gtroff Reference, Top
13525 @chapter Preprocessors
13526 @cindex preprocessors
13528 This chapter describes all preprocessors that come with @code{groff} or
13529 which are freely available.
13542 @c =====================================================================
13544 @node geqn, gtbl, Preprocessors, Preprocessors
13545 @section @code{geqn}
13546 @cindex @code{eqn}, the program
13547 @cindex @code{geqn}, the program
13555 @c ---------------------------------------------------------------------
13557 @node Invoking geqn, , geqn, geqn
13558 @subsection Invoking @code{geqn}
13559 @cindex invoking @code{geqn}
13560 @cindex @code{geqn}, invoking
13565 @c =====================================================================
13567 @node gtbl, gpic, geqn, Preprocessors
13568 @section @code{gtbl}
13569 @cindex @code{tbl}, the program
13570 @cindex @code{gtbl}, the program
13578 @c ---------------------------------------------------------------------
13580 @node Invoking gtbl, , gtbl, gtbl
13581 @subsection Invoking @code{gtbl}
13582 @cindex invoking @code{gtbl}
13583 @cindex @code{gtbl}, invoking
13588 @c =====================================================================
13590 @node gpic, ggrn, gtbl, Preprocessors
13591 @section @code{gpic}
13592 @cindex @code{pic}, the program
13593 @cindex @code{gpic}, the program
13601 @c ---------------------------------------------------------------------
13603 @node Invoking gpic, , gpic, gpic
13604 @subsection Invoking @code{gpic}
13605 @cindex invoking @code{gpic}
13606 @cindex @code{gpic}, invoking
13611 @c =====================================================================
13613 @node ggrn, grap, gpic, Preprocessors
13614 @section @code{ggrn}
13615 @cindex @code{grn}, the program
13616 @cindex @code{ggrn}, the program
13624 @c ---------------------------------------------------------------------
13626 @node Invoking ggrn, , ggrn, ggrn
13627 @subsection Invoking @code{ggrn}
13628 @cindex invoking @code{ggrn}
13629 @cindex @code{ggrn}, invoking
13634 @c =====================================================================
13636 @node grap, grefer, ggrn, Preprocessors
13637 @section @code{grap}
13638 @cindex @code{grap}, the program
13640 A free implementation of @code{grap}, written by Ted Faber,
13641 is available as an extra package from the following address:
13644 @uref{http://www.lunabase.org/~faber/Vault/software/grap/}
13648 @c =====================================================================
13650 @node grefer, gsoelim, grap, Preprocessors
13651 @section @code{grefer}
13652 @cindex @code{refer}, the program
13653 @cindex @code{grefer}, the program
13658 * Invoking grefer::
13661 @c ---------------------------------------------------------------------
13663 @node Invoking grefer, , grefer, grefer
13664 @subsection Invoking @code{grefer}
13665 @cindex invoking @code{grefer}
13666 @cindex @code{grefer}, invoking
13671 @c =====================================================================
13673 @node gsoelim, , grefer, Preprocessors
13674 @section @code{gsoelim}
13675 @cindex @code{soelim}, the program
13676 @cindex @code{gsoelim}, the program
13681 * Invoking gsoelim::
13684 @c ---------------------------------------------------------------------
13686 @node Invoking gsoelim, , gsoelim, gsoelim
13687 @subsection Invoking @code{gsoelim}
13688 @cindex invoking @code{gsoelim}
13689 @cindex @code{gsoelim}, invoking
13695 @c =====================================================================
13696 @c =====================================================================
13698 @node Output Devices, File formats, Preprocessors, Top
13699 @chapter Output Devices
13700 @cindex output devices
13701 @cindex devices for output
13706 * Special Characters::
13717 @c =====================================================================
13719 @node Special Characters, grotty, Output Devices, Output Devices
13720 @section Special Characters
13721 @cindex special characters
13722 @cindex characters, special
13729 @c =====================================================================
13731 @node grotty, grops, Special Characters, Output Devices
13732 @section @code{grotty}
13733 @cindex @code{grotty}, the program
13738 * Invoking grotty::
13741 @c ---------------------------------------------------------------------
13743 @node Invoking grotty, , grotty, grotty
13744 @subsection Invoking @code{grotty}
13745 @cindex invoking @code{grotty}
13746 @cindex @code{grotty}, invoking
13750 @c The following is no longer true; fix and extend it.
13753 @c @cindex Teletype
13754 @c @cindex ISO 6249 SGR
13755 @c @cindex terminal control sequences
13756 @c @cindex control sequences, for terminals
13757 @c For TTY output devices, underlining is done by emitting sequences of
13758 @c @samp{_} and @samp{\b} (the backspace character) before the actual
13759 @c character. Literally, this is printing an underline character, then
13760 @c moving back one character position, and printing the actual character
13761 @c at the same position as the underline character (similar to a
13762 @c typewriter). Usually, a modern terminal can't interpret this (and the
13763 @c original Teletype machines for which this sequence was appropriate are
13764 @c no longer in use). You need a pager program like @code{less} which
13765 @c translates this into ISO 6429 SGR sequences to control terminals.
13768 @c =====================================================================
13770 @node grops, grodvi, grotty, Output Devices
13771 @section @code{grops}
13772 @cindex @code{grops}, the program
13778 * Embedding PostScript::
13781 @c ---------------------------------------------------------------------
13783 @node Invoking grops, Embedding PostScript, grops, grops
13784 @subsection Invoking @code{grops}
13785 @cindex invoking @code{grops}
13786 @cindex @code{grops}, invoking
13790 @c ---------------------------------------------------------------------
13792 @node Embedding PostScript, , Invoking grops, grops
13793 @subsection Embedding @sc{PostScript}
13794 @cindex embedding PostScript
13795 @cindex PostScript, embedding
13800 @c =====================================================================
13802 @node grodvi, grolj4, grops, Output Devices
13803 @section @code{grodvi}
13804 @cindex @code{grodvi}, the program
13809 * Invoking grodvi::
13812 @c ---------------------------------------------------------------------
13814 @node Invoking grodvi, , grodvi, grodvi
13815 @subsection Invoking @code{grodvi}
13816 @cindex invoking @code{grodvi}
13817 @cindex @code{grodvi}, invoking
13822 @c =====================================================================
13824 @node grolj4, grolbp, grodvi, Output Devices
13825 @section @code{grolj4}
13826 @cindex @code{grolj4}, the program
13831 * Invoking grolj4::
13834 @c ---------------------------------------------------------------------
13836 @node Invoking grolj4, , grolj4, grolj4
13837 @subsection Invoking @code{grolj4}
13838 @cindex invoking @code{grolj4}
13839 @cindex @code{grolj4}, invoking
13844 @c =====================================================================
13846 @node grolbp, grohtml, grolj4, Output Devices
13847 @section @code{grolbp}
13848 @cindex @code{grolbp}, the program
13853 * Invoking grolbp::
13856 @c ---------------------------------------------------------------------
13858 @node Invoking grolbp, , grolbp, grolbp
13859 @subsection Invoking @code{grolbp}
13860 @cindex invoking @code{grolbp}
13861 @cindex @code{grolbp}, invoking
13866 @c =====================================================================
13868 @node grohtml, gxditview, grolbp, Output Devices
13869 @section @code{grohtml}
13870 @cindex @code{grohtml}, the program
13875 * Invoking grohtml::
13876 * grohtml specific registers and strings::
13879 @c ---------------------------------------------------------------------
13881 @node Invoking grohtml, grohtml specific registers and strings, grohtml, grohtml
13882 @subsection Invoking @code{grohtml}
13883 @cindex invoking @code{grohtml}
13884 @cindex @code{grohtml}, invoking
13888 @c ---------------------------------------------------------------------
13890 @node grohtml specific registers and strings, , Invoking grohtml, grohtml
13891 @subsection @code{grohtml} specific registers and strings
13892 @cindex registers specific to @code{grohtml}
13893 @cindex strings specific to @code{grohtml}
13894 @cindex @code{grohtml}, registers and strings
13896 @DefmpregList {ps4html, grohtml}
13897 @DefstrListEnd {www-image-template, grohtml}
13898 The registers @code{ps4html} and @code{www-image-template} are defined
13899 by the @code{pre-grohtml} preprocessor. @code{pre-grohtml} reads in
13900 the @code{troff} input, marks up the inline equations and passes the
13904 troff -Tps -rps4html=1 -dwww-image-template=@var{template}
13914 The PostScript device is used to create all the image files, and the
13915 register @code{ps4html} enables the macro sets to ignore floating
13916 keeps, footers, and headings.
13918 The register @code{www-image-template} is set to the user specified
13919 template name or the default name.
13923 @c =====================================================================
13925 @node gxditview, , grohtml, Output Devices
13926 @section @code{gxditview}
13927 @cindex @code{gxditview}, the program
13932 * Invoking gxditview::
13935 @c ---------------------------------------------------------------------
13937 @node Invoking gxditview, , gxditview, gxditview
13938 @subsection Invoking @code{gxditview}
13939 @cindex invoking @code{gxditview}
13940 @cindex @code{gxditview}, invoking
13947 @c =====================================================================
13948 @c =====================================================================
13950 @node File formats, Installation, Output Devices, Top
13951 @chapter File formats
13952 @cindex file formats
13953 @cindex formats, file
13955 All files read and written by @code{gtroff} are text files. The
13956 following two sections describe their format.
13964 @c =====================================================================
13966 @node gtroff Output, Font Files, File formats, File formats
13967 @section @code{gtroff} Output
13968 @cindex @code{gtroff}, output
13969 @cindex output, @code{gtroff}
13971 This section describes the intermediate output format of GNU
13972 @code{troff}. This output is produced by a run of @code{gtroff}
13973 before it is fed into a device postprocessor program.
13975 As @code{groff} is a wrapper program around @code{gtroff} that
13976 automatically calls a postprocessor, this output does not show up
13977 normally. This is why it is called @dfn{intermediate}.
13978 @code{groff} provides the option @option{-Z} to inhibit postprocessing,
13979 such that the produced intermediate output is sent to standard output
13980 just like calling @code{gtroff} manually.
13982 @cindex troff output
13983 @cindex output, troff
13984 @cindex intermediate output
13985 @cindex output, intermediate
13986 Here, the term @dfn{troff output} describes what is output by
13987 @code{gtroff}, while @dfn{intermediate output} refers to the language
13988 that is accepted by the parser that prepares this output for the
13989 postprocessors. This parser is smarter on whitespace and implements
13990 obsolete elements for compatibility, otherwise both formats are the
13991 same.@footnote{The parser and postprocessor for intermediate output
13992 can be found in the file@*
13993 @file{@var{groff-source-dir}/src/libs/libdriver/input.cpp}.}
13995 The main purpose of the intermediate output concept is to facilitate
13996 the development of postprocessors by providing a common programming
13997 interface for all devices. It has a language of its own that is
13998 completely different from the @code{gtroff} language. While the
13999 @code{gtroff} language is a high-level programming language for text
14000 processing, the intermediate output language is a kind of low-level
14001 assembler language by specifying all positions on the page for writing
14004 The intermediate output produced by @code{gtroff} is fairly readable,
14005 while output from @acronym{AT&T} @code{troff} is rather hard to
14006 understand because of strange habits that are still supported, but not
14007 used any longer by @code{gtroff}.
14010 * Language Concepts::
14011 * Command Reference::
14012 * Intermediate Output Examples::
14013 * Output Language Compatibility::
14016 @c ---------------------------------------------------------------------
14018 @node Language Concepts, Command Reference, gtroff Output, gtroff Output
14019 @subsection Language Concepts
14021 During the run of @code{gtroff}, the input data is cracked down to the
14022 information on what has to be printed at what position on the intended
14023 device. So the language of the intermediate output format can be quite
14024 small. Its only elements are commands with and without arguments.
14025 In this section, the term @dfn{command} always refers to the intermediate
14026 output language, and never to the @code{gtroff} language used for document
14027 formatting. There are commands for positioning and text writing, for drawing, and
14028 for device controlling.
14036 @node Separation, Argument Units, Language Concepts, Language Concepts
14037 @subsubsection Separation
14039 @acronym{AT&T} @code{troff} output has strange requirements on whitespace.
14040 The @code{gtroff} output parser, however, is smart about whitespace by
14041 making it maximally optional. The whitespace characters, i.e., the
14042 tab, space, and newline characters, always have a syntactical meaning.
14043 They are never printable because spacing within the output is always
14044 done by positioning commands.
14046 Any sequence of space or tab characters is treated as a single
14047 @dfn{syntactical space}. It separates commands and arguments, but is
14048 only required when there would occur a clashing between the command code
14049 and the arguments without the space. Most often, this happens when
14050 variable-length command names, arguments, argument lists, or command
14051 clusters meet. Commands and arguments with a known, fixed length need
14052 not be separated by syntactical space.
14054 A line break is a syntactical element, too. Every command argument can be
14055 followed by whitespace, a comment, or a newline character. Thus a
14056 @dfn{syntactical line break} is defined to consist of optional
14057 syntactical space that is optionally followed by a comment, and a
14060 The normal commands, those for positioning and text, consist of a
14061 single letter taking a fixed number of arguments. For historical reasons,
14062 the parser allows to stack such commands on the same line, but
14063 fortunately, in @code{gtroff}'s intermediate output, every command with
14064 at least one argument is followed by a line break, thus providing
14065 excellent readability.
14067 The other commands -- those for drawing and device controlling --
14068 have a more complicated structure; some recognize long command names,
14069 and some take a variable number of arguments. So all @samp{D} and
14070 @samp{x} commands were designed to request a syntactical line break
14071 after their last argument. Only one command, @w{@samp{x X}},
14072 has an argument that can stretch over several lines; all other
14073 commands must have all of their arguments on the same line as the
14074 command, i.e., the arguments may not be splitted by a line break.
14076 Empty lines (these are lines containing only space and/or a comment), can
14077 occur everywhere. They are just ignored.
14079 @node Argument Units, Document Parts, Separation, Language Concepts
14080 @subsubsection Argument Units
14082 Some commands take integer arguments that are assumed to represent
14083 values in a measurement unit, but the letter for the corresponding
14084 scale indicator is not written with the output command arguments.
14085 Most commands assume the scale indicator @samp{u}, the basic unit of
14086 the device, some use @samp{z}, the scaled point unit of the device,
14087 while others, such as the color commands, expect plain integers.
14089 Note that single characters can have the eighth bit set, as can the
14090 names of fonts and special characters. The names of characters and
14091 fonts can be of arbitrary length. A character that is to be printed
14092 will always be in the current font.
14094 A string argument is always terminated by the next whitespace
14095 character (space, tab, or newline); an embedded @samp{#} character is
14096 regarded as part of the argument, not as the beginning of a comment
14097 command. An integer argument is already terminated by the next
14098 non-digit character, which then is regarded as the first character of
14099 the next argument or command.
14101 @node Document Parts, , Argument Units, Language Concepts
14102 @subsubsection Document Parts
14104 A correct intermediate output document consists of two parts, the
14105 @dfn{prologue} and the @dfn{body}.
14107 The task of the prologue is to set the general device parameters
14108 using three exactly specified commands. @code{gtroff}'s prologue
14109 is guaranteed to consist of the following three lines (in that order):
14113 x res @var{n} @var{h} @var{v}
14118 with the arguments set as outlined in @ref{Device Control Commands}.
14119 Note that the parser for the intermediate output format is able to
14120 swallow additional whitespace and comments as well even in the
14123 The body is the main section for processing the document data.
14124 Syntactically, it is a sequence of any commands different from the
14125 ones used in the prologue. Processing is terminated as soon as the
14126 first @w{@samp{x stop}} command is encountered; the last line of any
14127 @code{gtroff} intermediate output always contains such a command.
14129 Semantically, the body is page oriented. A new page is started by a
14130 @samp{p} command. Positioning, writing, and drawing commands are
14131 always done within the current page, so they cannot occur before the
14132 first @samp{p} command. Absolute positioning (by the @samp{H} and
14133 @samp{V} commands) is done relative to the current page; all other
14134 positioning is done relative to the current location within this page.
14136 @c ---------------------------------------------------------------------
14138 @node Command Reference, Intermediate Output Examples, Language Concepts, gtroff Output
14139 @subsection Command Reference
14141 This section describes all intermediate output commands, both from
14142 @acronym{AT&T} @code{troff} as well as the @code{gtroff} extensions.
14145 * Comment Command::
14146 * Simple Commands::
14147 * Graphics Commands::
14148 * Device Control Commands::
14149 * Obsolete Command::
14152 @node Comment Command, Simple Commands, Command Reference, Command Reference
14153 @subsubsection Comment Command
14156 @item #@var{anything}@angles{end of line}
14157 A comment. Ignore any characters from the @samp{#} character up to
14158 the next newline character.
14160 This command is the only possibility for commenting in the intermediate
14161 output. Each comment can be preceded by arbitrary syntactical space;
14162 every command can be terminated by a comment.
14165 @node Simple Commands, Graphics Commands, Comment Command, Command Reference
14166 @subsubsection Simple Commands
14168 The commands in this subsection have a command code consisting of a
14169 single character, taking a fixed number of arguments. Most of them
14170 are commands for positioning and text writing. These commands are
14171 smart about whitespace. Optionally, syntactical space can be inserted
14172 before, after, and between the command letter and its arguments.
14173 All of these commands are stackable, i.e., they can be preceded by
14174 other simple commands or followed by arbitrary other commands on the
14175 same line. A separating syntactical space is only necessary when two
14176 integer arguments would clash or if the preceding argument ends with a
14181 .if (\n[@USE_ENV_STACK] == 1) \{\
14183 Open a new environment by copying the actual device configuration data
14184 to the environment stack.
14186 The current environment is setup by the device specification and
14187 manipulated by the setting commands.
14191 Close the actual environment (opened by a preceding
14193 and restore the previous environment from the environment
14194 stack as the actual device configuration data.
14196 \} \" endif @USE_ENV_STACK
14199 @item C @var{xxx}@angles{whitespace}
14200 Print a special character named @var{xxx}. The trailing
14201 syntactical space or line break is necessary to allow glyph names
14202 of arbitrary length. The glyph is printed at the current print
14203 position; the glyph's size is read from the font file. The print
14204 position is not changed.
14207 Print glyph@tie{}@var{g} at the current print position;@footnote{@samp{c}
14208 is actually a misnomer since it outputs a glyph.} the glyph's size is
14209 read from the font file. The print position is not changed.
14212 Set font to font number@tie{}@var{n} (a non-negative integer).
14215 Move right to the absolute vertical position@tie{}@var{n} (a
14216 non-negative integer in basic units @samp{u} relative to left edge
14220 Move @var{n} (a non-negative integer) basic units @samp{u} horizontally
14221 to the right. The original @acronym{UNIX} troff manual allows negative
14222 values for @var{n} also, but @code{gtroff} doesn't use this.
14224 @item m @var{color-scheme} @r{[}@var{component} @dots{}@r{]}
14225 Set the color for text (glyphs), line drawing, and the outline of
14226 graphic objects using different color schemes; the analoguous command
14227 for the filling color of graphic objects is @samp{DF}. The color
14228 components are specified as integer arguments between 0 and 65536.
14229 The number of color components and their meaning vary for the
14230 different color schemes. These commands are generated by
14231 @code{gtroff}'s escape sequence @code{\m}. No position changing.
14232 These commands are a @code{gtroff} extension.
14235 @item mc @var{cyan} @var{magenta} @var{yellow}
14236 Set color using the CMY color scheme, having the 3@tie{}color components
14237 @var{cyan}, @var{magenta}, and @var{yellow}.
14240 Set color to the default color value (black in most cases).
14241 No component arguments.
14243 @item mg @var{gray}
14244 Set color to the shade of gray given by the argument, an integer
14245 between 0 (black) and 65536 (white).
14247 @item mk @var{cyan} @var{magenta} @var{yellow} @var{black}
14248 Set color using the CMYK color scheme, having the 4@tie{}color components
14249 @var{cyan}, @var{magenta}, @var{yellow}, and @var{black}.
14251 @item mr @var{red} @var{green} @var{blue}
14252 Set color using the RGB color scheme, having the 3@tie{}color components
14253 @var{red}, @var{green}, and @var{blue}.
14257 Print glyph with index@tie{}@var{n} (a non-negative integer) of the
14258 current font. This command is a @code{gtroff} extension.
14260 @item n @var{b} @var{a}
14261 Inform the device about a line break, but no positioning is done by
14262 this command. In @acronym{AT&T} @code{troff}, the integer arguments
14263 @var{b} and@tie{}@var{a} informed about the space before and after the
14264 current line to make the intermediate output more human readable
14265 without performing any action. In @code{groff}, they are just ignored, but
14266 they must be provided for compatibility reasons.
14269 Begin a new page in the outprint. The page number is set
14270 to@tie{}@var{n}. This page is completely independent of pages formerly
14271 processed even if those have the same page number. The vertical
14272 position on the outprint is automatically set to@tie{}0. All
14273 positioning, writing, and drawing is always done relative to a page,
14274 so a @samp{p} command must be issued before any of these commands.
14277 Set point size to @var{n}@tie{}scaled points (this is unit @samp{z}).
14278 @acronym{AT&T} @code{troff} used the unit points (@samp{p}) instead.
14279 @xref{Output Language Compatibility}.
14281 @item t @var{xxx}@angles{whitespace}
14282 @itemx t @var{xxx} @var{dummy-arg}@angles{whitespace}
14283 Print a word, i.e., a sequence of characters @var{xxx} representing
14284 output glyphs which names are single characters, terminated by
14285 a space character or a line break; an optional second integer argument
14286 is ignored (this allows the formatter to generate an even number of
14287 arguments). The first glyph should be printed at the current
14288 position, the current horizontal position should then be increased by
14289 the width of the first glyph, and so on for each glyph.
14290 The widths of the glyphs are read from the font file, scaled for the
14291 current point size, and rounded to a multiple of the horizontal
14292 resolution. Special characters cannot be printed using this command
14293 (use the @samp{C} command for special characters). This command is a
14294 @code{gtroff} extension; it is only used for devices whose @file{DESC}
14295 file contains the @code{tcommand} keyword (@pxref{DESC File Format}).
14297 @item u @var{n} @var{xxx}@angles{whitespace}
14298 Print word with track kerning. This is the same as the @samp{t}
14299 command except that after printing each glyph, the current
14300 horizontal position is increased by the sum of the width of that
14301 glyph and@tie{}@var{n} (an integer in basic units @samp{u}).
14302 This command is a @code{gtroff} extension; it is only used for devices
14303 whose @file{DESC} file contains the @code{tcommand} keyword
14304 (@pxref{DESC File Format}).
14307 Move down to the absolute vertical position@tie{}@var{n} (a
14308 non-negative integer in basic units @samp{u}) relative to upper edge
14312 Move @var{n}@tie{}basic units @samp{u} down (@var{n} is a non-negative
14313 integer). The original @acronym{UNIX} troff manual allows negative
14314 values for @var{n} also, but @code{gtroff} doesn't use this.
14317 Informs about a paddable white space to increase readability.
14318 The spacing itself must be performed explicitly by a move command.
14321 @node Graphics Commands, Device Control Commands, Simple Commands, Command Reference
14322 @subsubsection Graphics Commands
14324 Each graphics or drawing command in the intermediate output starts
14325 with the letter @samp{D}, followed by one or two characters that
14326 specify a subcommand; this is followed by a fixed or variable number
14327 of integer arguments that are separated by a single space character.
14328 A @samp{D} command may not be followed by another command on the same line
14329 (apart from a comment), so each @samp{D} command is terminated by a
14330 syntactical line break.
14332 @code{gtroff} output follows the classical spacing rules (no space
14333 between command and subcommand, all arguments are preceded by a
14334 single space character), but the parser allows optional space between
14335 the command letters and makes the space before the first argument
14336 optional. As usual, each space can be any sequence of tab and space
14339 Some graphics commands can take a variable number of arguments.
14340 In this case, they are integers representing a size measured in basic
14341 units @samp{u}. The arguments called @var{h1}, @var{h2}, @dots{},
14342 @var{hn} stand for horizontal distances where positive means right,
14343 negative left. The arguments called @var{v1}, @var{v2}, @dots{},
14344 @var{vn} stand for vertical distances where positive means down,
14345 negative up. All these distances are offsets relative to the current
14348 Each graphics command directly corresponds to a similar @code{gtroff}
14349 @code{\D} escape sequence. @xref{Drawing Requests}.
14351 Unknown @samp{D} commands are assumed to be device-specific.
14352 Its arguments are parsed as strings; the whole information is then
14353 sent to the postprocessor.
14355 In the following command reference, the syntax element
14356 @angles{line break} means a syntactical line break as defined above.
14359 @item D~ @var{h1} @var{v1} @var{h2} @var{v2} @dots{} @var{hn} @var{vn}@angles{line break}
14360 Draw B-spline from current position to offset (@var{h1},@var{v1}),
14361 then to offset (@var{h2},@var{v2}), if given, etc.@: up to
14362 (@var{hn},@var{vn}). This command takes a variable number of argument
14363 pairs; the current position is moved to the terminal point of the drawn
14366 @item Da @var{h1} @var{v1} @var{h2} @var{v2}@angles{line break}
14367 Draw arc from current position to
14368 (@var{h1},@var{v1})@math{+}(@var{h2},@var{v2}) with center at
14369 (@var{h1},@var{v1}); then move the current position to the final point
14372 @item DC @var{d}@angles{line break}
14373 @itemx DC @var{d} @var{dummy-arg}@angles{line break}
14374 Draw a solid circle using the current fill color with
14375 diameter@tie{}@var{d} (integer in basic units @samp{u}) with leftmost
14376 point at the current position; then move the current position to the
14377 rightmost point of the circle. An optional second integer argument is
14378 ignored (this allows the formatter to generate an even number of
14379 arguments). This command is a @code{gtroff} extension.
14381 @item Dc @var{d}@angles{line break}
14382 Draw circle line with diameter@tie{}@var{d} (integer in basic units
14383 @samp{u}) with leftmost point at the current position; then move the
14384 current position to the rightmost point of the circle.
14386 @item DE @var{h} @var{v}@angles{line break}
14387 Draw a solid ellipse in the current fill color with a horizontal
14388 diameter of@tie{}@var{h} and a vertical diameter of@tie{}@var{v} (both
14389 integers in basic units @samp{u}) with the leftmost point at the
14390 current position; then move to the rightmost point of the ellipse.
14391 This command is a @code{gtroff} extension.
14393 @item De @var{h} @var{v}@angles{line break}
14394 Draw an outlined ellipse with a horizontal diameter of@tie{}@var{h}
14395 and a vertical diameter of@tie{}@var{v} (both integers in basic units
14396 @samp{u}) with the leftmost point at current position; then move to
14397 the rightmost point of the ellipse.
14399 @item DF @var{color-scheme} @r{[}@var{component} @dots{}@r{]}@angles{line break}
14400 Set fill color for solid drawing objects using different color
14401 schemes; the analoguous command for setting the color of text, line
14402 graphics, and the outline of graphic objects is @samp{m}.
14403 The color components are specified as integer arguments between 0 and
14404 65536. The number of color components and their meaning vary for the
14405 different color schemes. These commands are generated by @code{gtroff}'s
14406 escape sequences @w{@code{\D'F @dots{}'}} and @code{\M} (with no other
14407 corresponding graphics commands). No position changing. This command
14408 is a @code{gtroff} extension.
14411 @item DFc @var{cyan} @var{magenta} @var{yellow}@angles{line break}
14412 Set fill color for solid drawing objects using the CMY color scheme,
14413 having the 3@tie{}color components @var{cyan}, @var{magenta}, and
14416 @item DFd@angles{line break}
14417 Set fill color for solid drawing objects to the default fill color value
14418 (black in most cases). No component arguments.
14420 @item DFg @var{gray}@angles{line break}
14421 Set fill color for solid drawing objects to the shade of gray given by
14422 the argument, an integer between 0 (black) and 65536 (white).
14424 @item DFk @var{cyan} @var{magenta} @var{yellow} @var{black}@angles{line break}
14425 Set fill color for solid drawing objects using the CMYK color scheme,
14426 having the 4@tie{}color components @var{cyan}, @var{magenta}, @var{yellow},
14429 @item DFr @var{red} @var{green} @var{blue}@angles{line break}
14430 Set fill color for solid drawing objects using the RGB color scheme,
14431 having the 3@tie{}color components @var{red}, @var{green}, and @var{blue}.
14434 @item Df @var{n}@angles{line break}
14435 The argument@tie{}@var{n} must be an integer in the range @math{-32767}
14439 @item @math{0 @LE @var{n} @LE 1000}
14440 Set the color for filling solid drawing objects to a shade of gray,
14441 where 0 corresponds to solid white, 1000 (the default) to solid black,
14442 and values in between to intermediate shades of gray; this is
14443 obsoleted by command @samp{DFg}.
14445 @item @math{@var{n} < 0} or @math{@var{n} > 1000}
14446 Set the filling color to the color that is currently being used for
14447 the text and the outline, see command @samp{m}. For example, the
14456 sets all colors to blue.
14460 No position changing. This command is a @code{gtroff} extension.
14462 @item Dl @var{h} @var{v}@angles{line break}
14463 Draw line from current position to offset (@var{h},@var{v}) (integers
14464 in basic units @samp{u}); then set current position to the end of the
14467 @item Dp @var{h1} @var{v1} @var{h2} @var{v2} @dots{} @var{hn} @var{vn}@angles{line break}
14468 Draw a polygon line from current position to offset (@var{h1},@var{v1}),
14469 from there to offset (@var{h2},@var{v2}), etc.@: up to offset
14470 (@var{hn},@var{vn}), and from there back to the starting position.
14471 For historical reasons, the position is changed by adding the sum of
14472 all arguments with odd index to the actual horizontal position and the
14473 even ones to the vertical position. Although this doesn't make sense
14474 it is kept for compatibility.
14476 As the polygon is closed, the end of drawing is the starting point, so
14477 the position doesn't change.
14479 This command is a @code{gtroff} extension.
14481 @item Dp @var{h1} @var{v1} @var{h2} @var{v2} @dots{} @var{hn} @var{vn}@angles{line break}
14482 Draw a solid polygon in the current fill color rather than an outlined
14483 polygon, using the same arguments and positioning as the corresponding
14486 No position changing.
14488 This command is a @code{gtroff} extension.
14490 @item Dt @var{n}@angles{line break}
14491 Set the current line thickness to@tie{}@var{n} (an integer in basic
14492 units @samp{u}) if @math{@var{n}>0}; if @math{@var{n}=0} select the
14493 smallest available line thickness; if @math{@var{n}<0} set the line
14494 thickness proportional to the point size (this is the default before
14495 the first @samp{Dt} command was specified). For historical reasons,
14496 the horizontal position is changed by adding the argument to the actual
14497 horizontal position, while the vertical position is not changed.
14498 Although this doesn't make sense it is kept for compatibility.
14500 No position changing.
14502 This command is a @code{gtroff} extension.
14505 @node Device Control Commands, Obsolete Command, Graphics Commands, Command Reference
14506 @subsubsection Device Control Commands
14508 Each device control command starts with the letter @samp{x},
14509 followed by a space character (optional or arbitrary space or tab in
14510 @code{gtroff}) and a subcommand letter or word; each argument (if any)
14511 must be preceded by a syntactical space. All @samp{x} commands are
14512 terminated by a syntactical line break; no device control command can
14513 be followed by another command on the same line (except a comment).
14515 The subcommand is basically a single letter, but to increase
14516 readability, it can be written as a word, i.e., an arbitrary sequence
14517 of characters terminated by the next tab, space, or newline character.
14518 All characters of the subcommand word but the first are simply ignored.
14519 For example, @code{gtroff} outputs the initialization command
14520 @w{@samp{x i}} as @w{@samp{x init}} and the resolution command
14521 @w{@samp{x r}} as @w{@samp{x res}}.
14523 In the following, the syntax element @angles{line break} means a
14524 syntactical line break (@pxref{Separation}).
14527 @item xF @var{name}@angles{line break}
14528 The @samp{F} stands for @var{Filename}.
14530 Use @var{name} as the intended name for the current file in error
14531 reports. This is useful for remembering the original file name when
14532 @code{gtroff} uses an internal piping mechanism. The input file is
14533 not changed by this command. This command is a @code{gtroff} extension.
14535 @item xf @var{n} @var{s}@angles{line break}
14536 The @samp{f} stands for @var{font}.
14538 Mount font position@tie{}@var{n} (a non-negative integer) with font
14539 named@tie{}@var{s} (a text word). @xref{Font Positions}.
14541 @item xH @var{n}@angles{line break}
14542 The @samp{H} stands for @var{Height}.
14544 Set glyph height to@tie{}@var{n} (a positive integer in scaled
14545 points @samp{z}). @acronym{AT&T} @code{troff} uses the unit points
14546 (@samp{p}) instead. @xref{Output Language Compatibility}.
14548 @item xi@angles{line break}
14549 The @samp{i} stands for @var{init}.
14551 Initialize device. This is the third command of the prologue.
14553 @item xp@angles{line break}
14554 The @samp{p} stands for @var{pause}.
14556 Parsed but ignored. The original @acronym{UNIX} troff manual writes
14559 pause device, can be restarted
14562 @item xr @var{n} @var{h} @var{v}@angles{line break}
14563 The @samp{r} stands for @var{resolution}.
14565 Resolution is@tie{}@var{n}, while @var{h} is the minimal horizontal
14566 motion, and @var{v} the minimal vertical motion possible with this
14567 device; all arguments are positive integers in basic units @samp{u}
14568 per inch. This is the second command of the prologue.
14570 @item xS @var{n}@angles{line break}
14571 The @samp{S} stands for @var{Slant}.
14573 Set slant to@tie{}@var{n} (an integer in basic units @samp{u}).
14575 @item xs@angles{line break}
14576 The @samp{s} stands for @var{stop}.
14578 Terminates the processing of the current file; issued as the last
14579 command of any intermediate troff output.
14581 @item xt@angles{line break}
14582 The @samp{t} stands for @var{trailer}.
14584 Generate trailer information, if any. In @var{gtroff}, this is
14585 actually just ignored.
14587 @item xT @var{xxx}@angles{line break}
14588 The @samp{T} stands for @var{Typesetter}.
14590 Set name of device to word @var{xxx}, a sequence of characters ended
14591 by the next white space character. The possible device names coincide
14592 with those from the @code{groff} @option{-T} option. This is the first
14593 command of the prologue.
14595 @item xu @var{n}@angles{line break}
14596 The @samp{u} stands for @var{underline}.
14598 Configure underlining of spaces. If @var{n} is@tie{}1, start
14599 underlining of spaces; if @var{n} is@tie{}0, stop underlining of spaces.
14600 This is needed for the @code{cu} request in nroff mode and is ignored
14601 otherwise. This command is a @code{gtroff} extension.
14603 @item xX @var{anything}@angles{line break}
14604 The @samp{x} stands for @var{X-escape}.
14606 Send string @var{anything} uninterpreted to the device. If the line
14607 following this command starts with a @samp{+} character this line is
14608 interpreted as a continuation line in the following sense. The
14609 @samp{+} is ignored, but a newline character is sent instead to the
14610 device, the rest of the line is sent uninterpreted. The same applies
14611 to all following lines until the first character of a line is not a
14612 @samp{+} character. This command is generated by the @code{gtroff}
14613 escape sequence @code{\X}. The line-continuing feature is a
14614 @code{gtroff} extension.
14617 @node Obsolete Command, , Device Control Commands, Command Reference
14618 @subsubsection Obsolete Command
14619 In @acronym{AT&T} @code{troff} output, the writing of a single
14620 glyph is mostly done by a very strange command that combines a
14621 horizontal move and a single character giving the glyph name. It
14622 doesn't have a command code, but is represented by a 3-character
14623 argument consisting of exactly 2@tie{}digits and a character.
14626 @item @var{dd}@var{g}
14627 Move right @var{dd} (exactly two decimal digits) basic units @samp{u},
14628 then print glyph@tie{}@var{g} (represented as a single character).
14630 In @code{gtroff}, arbitrary syntactical space around and within this
14631 command is allowed to be added. Only when a preceding command on the
14632 same line ends with an argument of variable length a separating space
14633 is obligatory. In @acronym{AT&T} @code{troff}, large clusters of these
14634 and other commands are used, mostly without spaces; this made such output
14638 For modern high-resolution devices, this command does not make sense
14639 because the width of the glyphs can become much larger than two
14640 decimal digits. In @code{gtroff}, this is only used for the devices
14641 @code{X75}, @code{X75-12}, @code{X100}, and @code{X100-12}. For other
14642 devices, the commands @samp{t} and @samp{u} provide a better
14645 @c ---------------------------------------------------------------------
14647 @node Intermediate Output Examples, Output Language Compatibility, Command Reference, gtroff Output
14648 @subsection Intermediate Output Examples
14650 This section presents the intermediate output generated from the same
14651 input for three different devices. The input is the sentence
14652 @samp{hell world} fed into @code{gtroff} on the command line.
14655 @item High-resolution device @code{ps}
14657 This is the standard output of @code{gtroff} if no @option{-T} option
14662 shell> echo "hell world" | groff -Z -T ps
14688 This output can be fed into @code{grops} to get its representation as
14691 @item Low-resolution device @code{latin1}
14693 This is similar to the high-resolution device except that the
14694 positioning is done at a minor scale. Some comments (lines starting
14695 with @samp{#}) were added for clarification; they were not generated
14700 shell> echo "hell world" | groff -Z -T latin1
14713 # initial positioning on the page
14716 # write text `hell'
14718 # inform about space, and issue a horizontal jump
14720 # write text `world'
14722 # announce line break, but do nothing because ...
14725 # ... the end of the document has been reached
14733 This output can be fed into @code{grotty} to get a formatted text
14736 @item @acronym{AT&T} @code{troff} output
14737 Since a computer monitor has a very low resolution compared to modern
14738 printers the intermediate output for the X@tie{}Window devices can use
14739 the jump-and-write command with its 2-digit displacements.
14743 shell> echo "hell world" | groff -Z -T X100
14755 # write text with jump-and-write commands
14756 ch07e07l03lw06w11o07r05l03dh7
14766 This output can be fed into @code{xditview} or @code{gxditview}
14767 for displaying in@tie{}X.
14769 Due to the obsolete jump-and-write command, the text clusters in the
14770 @acronym{AT&T} @code{troff} output are almost unreadable.
14773 @c ---------------------------------------------------------------------
14775 @node Output Language Compatibility, , Intermediate Output Examples, gtroff Output
14776 @subsection Output Language Compatibility
14778 The intermediate output language of @acronym{AT&T} @code{troff}
14779 was first documented in the @acronym{UNIX} troff manual, with later
14780 additions documented in @cite{A Typesetter-indenpendent TROFF},
14781 written by Brian Kernighan.
14783 The @code{gtroff} intermediate output format is compatible with this
14784 specification except for the following features.
14788 The classical quasi device independence is not yet implemented.
14791 The old hardware was very different from what we use today. So the
14792 @code{groff} devices are also fundamentally different from the ones in
14793 @acronym{AT&T} @code{troff}. For example, the @acronym{AT&T}
14794 PostScript device is called @code{post} and has a resolution of only
14795 720 units per inch, suitable for printers 20 years ago, while
14796 @code{groff}'s @code{ps} device has a resolution of
14797 72000 units per inch. Maybe, by implementing some rescaling
14798 mechanism similar to the classical quasi device independence,
14799 @code{groff} could emulate @acronym{AT&T}'s @code{post} device.
14802 The B-spline command @samp{D~} is correctly handled by the
14803 intermediate output parser, but the drawing routines aren't
14804 implemented in some of the postprocessor programs.
14807 The argument of the commands @samp{s} and @w{@samp{x H}} has the
14808 implicit unit scaled point @samp{z} in @code{gtroff}, while
14809 @acronym{AT&T} @code{troff} has point (@samp{p}). This isn't an
14810 incompatibility but a compatible extension, for both units coincide
14811 for all devices without a @code{sizescale} parameter in the @file{DESC}
14812 file, including all postprocessors from @acronym{AT&T} and
14813 @code{groff}'s text devices. The few @code{groff} devices with
14814 a @code{sizescale} parameter either do not exist for @acronym{AT&T}
14815 @code{troff}, have a different name, or seem to have a different
14816 resolution. So conflicts are very unlikely.
14819 The position changing after the commands @samp{Dp}, @samp{DP}, and
14820 @samp{Dt} is illogical, but as old versions of @code{gtroff} used this
14821 feature it is kept for compatibility reasons.
14824 Temporarily, there existed some confusion on the positioning after the
14825 @samp{D} commands that are groff extensions. This has been clarified
14826 by establishing the classical rule for all @code{groff} drawing commands:
14830 The position after a graphic object has been drawn is at its end;
14831 for circles and ellipses, the `end' is at the right side.
14834 From this, the positionings specified for the drawing commands above
14835 follow quite naturally.
14842 @c =====================================================================
14844 @node Font Files, , gtroff Output, File formats
14845 @section Font Files
14847 @cindex files, font
14849 The @code{gtroff} font format is roughly a superset of the
14850 @code{ditroff} font format (as used in later versions of @acronym{AT&T}
14851 @code{troff} and its descendants). Unlike the @code{ditroff} font
14852 format, there is no associated binary format; all files are text
14853 files.@footnote{Plan@tie{}9 @code{troff} has also abandoned the binary
14854 format.} The font files for device @var{name} are stored in a directory
14855 @file{dev@var{name}}. There are two types of file: a device description
14856 file called @file{DESC} and for each font@tie{}@var{f} a font file
14857 called@tie{}@file{@var{f}}.
14860 * DESC File Format::
14861 * Font File Format::
14864 @c ---------------------------------------------------------------------
14866 @node DESC File Format, Font File Format, Font Files, Font Files
14867 @subsection @file{DESC} File Format
14868 @cindex @file{DESC} file, format
14869 @cindex font description file, format
14870 @cindex format of font description file
14871 @pindex DESC@r{ file format}
14873 The @file{DESC} file can contain the following types of line. Except
14874 for the @code{charset} keyword which must comes last (if at all), the
14875 order of the lines is not important.
14880 @cindex device resolution
14881 @cindex resolution, device
14882 There are @var{n}@tie{}machine units per inch.
14886 @cindex horizontal resolution
14887 @cindex resolution, horizontal
14888 The horizontal resolution is @var{n}@tie{}machine units. All horizontal
14889 quantities are rounded to be multiples of this value.
14893 @cindex vertical resolution
14894 @cindex resolution, vertical
14895 The vertical resolution is @var{n}@tie{}machine units. All vertical
14896 quantities are rounded to be multiples of this value.
14898 @item sizescale @var{n}
14900 The scale factor for point sizes. By default this has a value of@tie{}1.
14901 One scaled point is equal to one point/@var{n}. The arguments to the
14902 @code{unitwidth} and @code{sizes} commands are given in scaled points.
14903 @xref{Fractional Type Sizes}, for more information.
14905 @item unitwidth @var{n}
14907 Quantities in the font files are given in machine units for fonts whose
14908 point size is @var{n}@tie{}scaled points.
14910 @item prepro @var{program}
14912 Call @var{program} as a preprocessor. Currently, this keyword is used
14913 by @code{groff} with option @option{-Thtml} only.
14915 @item postpro @var{program}
14917 Call @var{program} as a postprocessor. For example, the line
14924 in the file @file{devdvi/DESC} makes @code{groff} call @code{grodvi}
14925 if option @option{-Tdvi} is given (and @option{-Z} isn't used).
14929 This means that the postprocessor can handle the @samp{t} and @samp{u}
14930 intermediate output commands.
14932 @item sizes @var{s1} @var{s2} @dots{} @var{sn} 0
14934 This means that the device has fonts at @var{s1}, @var{s2}, @dots{}
14935 @var{sn} scaled points. The list of sizes must be terminated by@tie{}0
14936 (this is digit zero). Each @var{si} can also be a range of sizes
14937 @var{m}-@var{n}. The list can extend over more than one line.
14939 @item styles @var{S1} @var{S2} @dots{} @var{Sm}
14941 The first @var{m}@tie{}font positions are associated with styles
14942 @var{S1} @dots{} @var{Sm}.
14944 @item fonts @var{n} @var{F1} @var{F2} @var{F3} @dots{} @var{Fn}
14946 Fonts @var{F1} @dots{} @var{Fn} are mounted in the font positions
14947 @var{m}+1, @dots{}, @var{m}+@var{n} where @var{m} is the number of
14948 styles. This command may extend over more than one line. A font name
14949 of@tie{}0 means no font is mounted on the corresponding font position.
14951 @item family @var{fam}
14953 The default font family is @var{fam}.
14955 @item use_charnames_in_special
14956 @kindex use_charnames_in_special
14957 This command indicates that @code{gtroff} should encode special
14958 characters inside special commands. Currently, this is only used
14959 by the @acronym{HTML} output device. @xref{Postprocessor Access}.
14961 @item papersize @var{string} @dots{}
14963 Select a paper size. Valid values for @var{string} are the ISO paper
14964 types @code{A0}-@code{A7}, @code{B0}-@code{B7}, @code{C0}-@code{C7},
14965 @code{D0}-@code{D7}, @code{DL}, and the US paper types @code{letter},
14966 @code{legal}, @code{tabloid}, @code{ledger}, @code{statement},
14967 @code{executive}, @code{com10}, and @code{monarch}. Case is not significant
14968 for @var{string} if it holds predefined paper types. Alternatively,
14969 @var{string} can be a file name (e.g.@: @file{/etc/papersize}); if the file
14970 can be opened, @code{groff} reads the first line and tests for the above
14971 paper sizes. Finally, @var{string} can be a custom paper size in the format
14972 @code{@var{length},@var{width}} (no spaces before and after the comma).
14973 Both @var{length} and @var{width} must have a unit appended; valid values
14974 are @samp{i} for inches, @samp{C} for centimeters, @samp{p} for points, and
14975 @samp{P} for picas. Example: @code{12c,235p}. An argument which starts
14976 with a digit is always treated as a custom paper format. @code{papersize}
14977 sets both the vertical and horizontal dimension of the output medium.
14979 More than one argument can be specified; @code{groff} scans from left to
14980 right and uses the first valid paper specification.
14982 @item pass_filenames
14983 @kindex pass_filenames
14984 Tell @code{gtroff} to emit the name of the source file currently
14985 being processed. This is achieved by the intermediate output command
14986 @samp{F}. Currently, this is only used by the @acronym{HTML} output
14989 @item print @var{program}
14991 Use @var{program} as a spooler program for printing. If omitted,
14992 the @option{-l} and @option{-L} options of @code{groff} are ignored.
14996 This line and everything following in the file are ignored. It is
14997 allowed for the sake of backwards compatibility.
15000 The @code{res}, @code{unitwidth}, @code{fonts}, and @code{sizes} lines
15001 are mandatory. Other commands are ignored by @code{gtroff} but may be
15002 used by postprocessors to store arbitrary information about the device
15003 in the @file{DESC} file.
15007 @kindex biggestfont
15008 Here a list of obsolete keywords which are recognized by @code{groff}
15009 but completely ignored: @code{spare1}, @code{spare2},
15010 @code{biggestfont}.
15012 @c ---------------------------------------------------------------------
15014 @node Font File Format, , DESC File Format, Font Files
15015 @subsection Font File Format
15016 @cindex font file, format
15017 @cindex font description file, format
15018 @cindex format of font files
15019 @cindex format of font description files
15021 A @dfn{font file}, also (and probably better) called a @dfn{font
15022 description file}, has two sections. The first section is a sequence
15023 of lines each containing a sequence of blank delimited words; the first
15024 word in the line is a key, and subsequent words give a value for that
15030 The name of the font is@tie{}@var{f}.
15032 @item spacewidth @var{n}
15034 The normal width of a space is@tie{}@var{n}.
15036 @item slant @var{n}
15038 The glyphs of the font have a slant of @var{n}@tie{}degrees.
15039 (Positive means forward.)
15041 @item ligatures @var{lig1} @var{lig2} @dots{} @var{lign} [0]
15043 Glyphs @var{lig1}, @var{lig2}, @dots{}, @var{lign} are ligatures;
15044 possible ligatures are @samp{ff}, @samp{fi}, @samp{fl}, @samp{ffi} and
15045 @samp{ffl}. For backwards compatibility, the list of ligatures may be
15046 terminated with a@tie{}0. The list of ligatures may not extend over more
15050 @cindex special fonts
15052 The font is @dfn{special}; this means that when a glyph is requested
15053 that is not present in the current font, it is searched for in any
15054 special fonts that are mounted.
15057 Other commands are ignored by @code{gtroff} but may be used by
15058 postprocessors to store arbitrary information about the font in the font
15061 @cindex comments in font files
15062 @cindex font files, comments
15064 The first section can contain comments which start with the @samp{#}
15065 character and extend to the end of a line.
15067 The second section contains one or two subsections. It must contain a
15068 @code{charset} subsection and it may also contain a @code{kernpairs}
15069 subsection. These subsections can appear in any order. Each
15070 subsection starts with a word on a line by itself.
15073 The word @code{charset} starts the character set
15074 subsection.@footnote{This keyword is misnamed since it starts a list
15075 of ordered glyphs, not characters.} The @code{charset} line is
15076 followed by a sequence of lines. Each line gives information for one
15077 glyph. A line comprises a number of fields separated by blanks or
15078 tabs. The format is
15081 @var{name} @var{metrics} @var{type} @var{code}
15082 [@var{entity-name}] [@code{--} @var{comment}]
15085 @cindex 8-bit input
15086 @cindex input, 8-bit
15087 @cindex accessing unnamed glyphs with @code{\N}
15088 @cindex unnamed glyphs, accessing with @code{\N}
15089 @cindex characters, unnamed, accessing with @code{\N}
15090 @cindex glyphs, unnamed, accessing with @code{\N}
15093 @var{name} identifies the glyph name@footnote{The distinction between
15094 input, characters, and output, glyphs, is not clearly separated in the
15095 terminology of @code{groff}; for example, the @code{char} request
15096 should be called @code{glyph} since it defines an output entity.}:
15097 If @var{name} is a single character@tie{}@var{c} then it corresponds
15098 to the @code{gtroff} input character@tie{}@var{c}; if it is of the form
15099 @samp{\@var{c}} where @var{c} is a single character, then it
15100 corresponds to the special character @code{\[@var{c}]}; otherwise it
15101 corresponds to the special character @samp{\[@var{name}]}. If it
15102 is exactly two characters @var{xx} it can be entered as
15103 @samp{\(@var{xx}}. Note that single-letter special characters can't
15104 be accessed as @samp{\@var{c}}; the only exception is @samp{\-} which
15105 is identical to @code{\[-]}.
15107 @code{gtroff} supports 8-bit input characters; however some utilities
15108 have difficulties with eight-bit characters. For this reason, there is
15109 a convention that the entity name @samp{char@var{n}} is equivalent to
15110 the single input character whose code is@tie{}@var{n}. For example,
15111 @samp{char163} would be equivalent to the character with code@tie{}163
15112 which is the pounds sterling sign in the ISO@tie{}@w{Latin-1} character set.
15113 You shouldn't use @samp{char@var{n}} entities in font description files
15114 since they are related to input, not output. Otherwise, you get
15115 hard-coded connections between input and output encoding which
15116 prevents use of different (input) character sets.
15118 The name @samp{---} is special and indicates that the glyph is
15119 unnamed; such glyphs can only be used by means of the @code{\N}
15120 escape sequence in @code{gtroff}.
15122 The @var{type} field gives the glyph type:
15126 the glyph has a descender, for example, @samp{p};
15129 the glyph has an ascender, for example, @samp{b};
15132 the glyph has both an ascender and a descender, for example, @samp{(}.
15135 The @var{code} field gives the code which the postprocessor uses to
15136 print the glyph. The glyph can also be input to @code{gtroff}
15137 using this code by means of the @code{\N} escape sequence. @var{code}
15138 can be any integer. If it starts with @samp{0} it is interpreted as
15139 octal; if it starts with @samp{0x} or @samp{0X} it is interpreted as
15140 hexadecimal. Note, however, that the @code{\N} escape sequence only
15141 accepts a decimal integer.
15143 The @var{entity-name} field gives an @acronym{ASCII} string
15144 identifying the glyph which the postprocessor uses to print the
15145 @code{gtroff} glyph @var{name}. This field is optional and has been
15146 introduced so that the @acronym{HTML} device driver can encode its
15147 character set. For example, the glyph @samp{\[Po]} is
15148 represented as @samp{£} in @acronym{HTML} 4.0.
15150 Anything on the line after the @var{entity-name} field resp.@: after
15151 @samp{--} will be ignored.
15153 The @var{metrics} field has the form:
15157 @var{width}[@code{,}@var{height}[@code{,}@var{depth}[@code{,}@var{italic-correction}
15158 [@code{,}@var{left-italic-correction}[@code{,}@var{subscript-correction}]]]]]
15163 There must not be any spaces between these subfields (it has been split
15164 here into two lines for better legibility only). Missing subfields are
15165 assumed to be@tie{}0. The subfields are all decimal integers. Since
15166 there is no associated binary format, these values are not required to
15167 fit into a variable of type @samp{char} as they are in @code{ditroff}.
15168 The @var{width} subfield gives the width of the glyph. The @var{height}
15169 subfield gives the height of the glyph (upwards is positive); if a
15170 glyph does not extend above the baseline, it should be given a zero
15171 height, rather than a negative height. The @var{depth} subfield gives
15172 the depth of the glyph, that is, the distance from the baseline to the
15173 lowest point below the baseline to which the glyph extends (downwards is
15174 positive); if a glyph does not extend below the baseline, it should be
15175 given a zero depth, rather than a negative depth. The
15176 @var{italic-correction} subfield gives the amount of space that should
15177 be added after the glyph when it is immediately to be followed by a
15178 glyph from a roman font. The @var{left-italic-correction} subfield
15179 gives the amount of space that should be added before the glyph when it
15180 is immediately to be preceded by a glyph from a roman font. The
15181 @var{subscript-correction} gives the amount of space that should be
15182 added after a glyph before adding a subscript. This should be less
15183 than the italic correction.
15185 A line in the @code{charset} section can also have the format
15192 This indicates that @var{name} is just another name for the glyph
15193 mentioned in the preceding line.
15196 The word @code{kernpairs} starts the kernpairs section. This contains a
15197 sequence of lines of the form:
15200 @var{c1} @var{c2} @var{n}
15204 This means that when glyph @var{c1} appears next to glyph @var{c2}
15205 the space between them should be increased by@tie{}@var{n}. Most
15206 entries in the kernpairs section have a negative value for@tie{}@var{n}.
15210 @c =====================================================================
15211 @c =====================================================================
15213 @node Installation, Copying This Manual, File formats, Top
15214 @chapter Installation
15215 @cindex installation
15221 @c =====================================================================
15222 @c =====================================================================
15224 @node Copying This Manual, Request Index, Installation, Top
15225 @appendix Copying This Manual
15228 * GNU Free Documentation License:: License for copying this manual.
15235 @c =====================================================================
15236 @c =====================================================================
15238 @node Request Index, Escape Index, Copying This Manual, Top
15239 @appendix Request Index
15241 Requests appear without the leading control character (normally either
15242 @samp{.} or @samp{'}).
15248 @c =====================================================================
15249 @c =====================================================================
15251 @node Escape Index, Operator Index, Request Index, Top
15252 @appendix Escape Index
15254 Any escape sequence @code{\@var{X}} with @var{X} not in the list below
15255 emits a warning, printing glyph @var{X}.
15261 @c =====================================================================
15262 @c =====================================================================
15264 @node Operator Index, Register Index, Escape Index, Top
15265 @appendix Operator Index
15271 @c =====================================================================
15272 @c =====================================================================
15274 @node Register Index, Macro Index, Operator Index, Top
15275 @appendix Register Index
15277 The macro package or program a specific register belongs to is appended in
15280 A register name@tie{}@code{x} consisting of exactly one character can be
15281 accessed as @samp{\nx}. A register name @code{xx} consisting of exactly
15282 two characters can be accessed as @samp{\n(xx}. Register names @code{xxx}
15283 of any length can be accessed as @samp{\n[xxx]}.
15289 @c =====================================================================
15290 @c =====================================================================
15292 @node Macro Index, String Index, Register Index, Top
15293 @appendix Macro Index
15295 The macro package a specific macro belongs to is appended in brackets.
15296 They appear without the leading control character (normally @samp{.}).
15302 @c =====================================================================
15303 @c =====================================================================
15305 @node String Index, Glyph Name Index, Macro Index, Top
15306 @appendix String Index
15308 The macro package or program a specific string belongs to is appended in
15311 A string name@tie{}@code{x} consisting of exactly one character can be
15312 accessed as @samp{\*x}. A string name @code{xx} consisting of exactly
15313 two characters can be accessed as @samp{\*(xx}. String names @code{xxx}
15314 of any length can be accessed as @samp{\*[xxx]}.
15321 @c =====================================================================
15322 @c =====================================================================
15324 @node Glyph Name Index, Font File Keyword Index, String Index, Top
15325 @appendix Glyph Name Index
15327 A glyph name @code{xx} consisting of exactly two characters can be
15328 accessed as @samp{\(xx}. Glyph names @code{xxx} of any length can be
15329 accessed as @samp{\[xxx]}.
15335 @c =====================================================================
15336 @c =====================================================================
15338 @node Font File Keyword Index, Program and File Index, Glyph Name Index, Top
15339 @appendix Font File Keyword Index
15345 @c =====================================================================
15346 @c =====================================================================
15348 @node Program and File Index, Concept Index, Font File Keyword Index, Top
15349 @appendix Program and File Index
15355 @c =====================================================================
15356 @c =====================================================================
15358 @node Concept Index, , Program and File Index, Top
15359 @appendix Concept Index