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.3 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
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
374 @subtitle Spring 2003
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.
920 Suppress output from @code{gtroff}. Only error messages are printed.
923 Do not postprocess the output of @code{gtroff}. Normally @code{groff}
924 automatically runs the appropriate postprocessor.
927 Pass @var{arg} to the postprocessor. Each argument should be passed
928 with a separate @option{-P} option. Note that @code{groff} does not
929 prepend @samp{-} to @var{arg} before passing it to the postprocessor.
932 Send the output to a spooler for printing. The command used for this is
933 specified by the @code{print} command in the device description file
934 (see @ref{Font Files}, for more info). If not present, @option{-l} is
938 Pass @var{arg} to the spooler. Each argument should be passed with a
939 separate @option{-L} option. Note that @code{groff} does not prepend
940 a @samp{-} to @var{arg} before passing it to the postprocessor.
941 If the @code{print} keyword in the device description file is missing,
942 @option{-L} is ignored.
945 Prepare output for device @var{dev}. The default device is @samp{ps},
946 unless changed when @code{groff} was configured and built. The
947 following are the output devices currently available:
951 For @sc{PostScript} printers and previewers.
954 For @TeX{} DVI format.
957 For a 75@dmn{dpi} X11 previewer.
960 For a 75@dmn{dpi} X11 previewer with a 12@dmn{pt} base font in the
964 For a 100@dmn{dpi} X11 previewer.
967 For a 100@dmn{dpi} X11 previewer with a 12@dmn{pt} base font in the
971 @cindex encoding, output, @acronym{ASCII}
972 @cindex @acronym{ASCII}, output encoding
973 @cindex output encoding, @acronym{ASCII}
974 For typewriter-like devices using the (7-bit) @acronym{ASCII}
978 @cindex encoding, output, @w{latin-1} (ISO @w{8859-1})
979 @cindex @w{latin-1} (ISO @w{8859-1}), output encoding
980 @cindex ISO @w{8859-1} (@w{latin-1}), output encoding
981 @cindex output encoding, @w{latin-1} (ISO @w{8859-1})
982 For typewriter-like devices that support the @w{Latin-1}
983 (ISO@tie{}@w{8859-1}) character set.
986 @cindex encoding, output, @w{utf-8}
987 @cindex @w{utf-8}, output encoding
988 @cindex output encoding, @w{utf-8}
989 For typewriter-like devices which use the Unicode (ISO@tie{}10646)
990 character set with @w{UTF-8} encoding.
993 @cindex encoding, output, @acronym{EBCDIC}
994 @cindex @acronym{EBCDIC}, output encoding
995 @cindex output encoding, @acronym{EBCDIC}
996 @cindex encoding, output, cp1047
997 @cindex cp1047, output encoding
998 @cindex output encoding, cp1047
999 @cindex IBM cp1047 output encoding
1000 For typewriter-like devices which use the @acronym{EBCDIC} encoding IBM
1004 For HP LaserJet4-compatible (or other PCL5-compatible) printers.
1007 For Canon @acronym{CAPSL} printers (@w{LBP-4} and @w{LBP-8} series laser
1011 @pindex post-grohtml
1012 @cindex @code{grohtml}, the program
1014 To produce @acronym{HTML} output. Note that the @acronym{HTML} driver
1015 consists of two parts, a preprocessor (@code{pre-grohtml}) and a
1016 postprocessor (@code{post-grohtml}).
1019 @cindex output device name string register (@code{.T})
1020 @cindex output device usage number register (@code{.T})
1021 The predefined @code{gtroff} string register @code{.T} contains the
1022 current output device; the read-only number register @code{.T} is set
1023 to@tie{}1 if this option is used (which is always true if @code{groff} is
1024 used to call @code{gtroff}). @xref{Built-in Registers}.
1026 The postprocessor to be used for a device is specified by the
1027 @code{postpro} command in the device description file. (@xref{Font
1028 Files}, for more info.) This can be overridden with the @option{-X}
1032 Preview with @code{gxditview} instead of using the usual postprocessor.
1033 This is unlikely to produce good results except with @option{-Tps}.
1035 Note that this is not the same as using @option{-TX75} or
1036 @option{-TX100} to view a document with @code{gxditview}: The former
1037 uses the metrics of the specified device, whereas the latter uses
1038 X-specific fonts and metrics.
1041 Don't allow newlines with @code{eqn} delimiters. This is the same as
1042 the @option{-N} option in @code{geqn}.
1045 @cindex @code{open} request, and safer mode
1046 @cindex @code{opena} request, and safer mode
1047 @cindex @code{pso} request, and safer mode
1048 @cindex @code{sy} request, and safer mode
1049 @cindex @code{pi} request, and safer mode
1052 Safer mode. Pass the @option{-S} option to @code{gpic} and disable the
1053 @code{open}, @code{opena}, @code{pso}, @code{sy}, and @code{pi}
1054 requests. For security reasons, this is enabled by default.
1057 @cindex mode, unsafe
1059 Unsafe mode. This enables the @code{open}, @code{opena}, @code{pso},
1060 @code{sy}, and @code{pi} requests.
1063 @cindex @acronym{ASCII} approximation output register (@code{.A})
1064 Generate an @acronym{ASCII} approximation of the typeset output. The
1065 read-only register @code{.A} is then set to@tie{}1. @xref{Built-in
1066 Registers}. A typical example is
1069 groff -a -man -Tdvi troff.man | less
1073 which shows how lines are broken for the DVI device. Note that this
1074 option is rather useless today since graphic output devices are
1075 available virtually everywhere.
1078 Print a backtrace with each warning or error message. This backtrace
1079 should help track down the cause of the error. The line numbers given
1080 in the backtrace may not always be correct: @code{gtroff} can get
1081 confused by @code{as} or @code{am} requests while counting line numbers.
1084 Read the standard input after all the named input files have been
1088 Enable warning @var{name}. Available warnings are described in
1089 @ref{Debugging}. Multiple @option{-w} options are allowed.
1092 Inhibit warning @var{name}. Multiple @option{-W} options are allowed.
1095 Inhibit all error messages.
1098 Enable compatibility mode. @xref{Implementation Differences}, for the
1099 list of incompatibilities between @code{groff} and @acronym{AT&T}
1102 @item -d@var{c}@var{s}
1103 @itemx -d@var{name}=@var{s}
1104 Define @var{c} or @var{name} to be a string@tie{}@var{s}. @var{c}@tie{}must
1105 be a one-letter name; @var{name} can be of arbitrary length. All string
1106 assignments happen before loading any macro file (including the start-up
1110 Use @var{fam} as the default font family. @xref{Font Families}.
1113 Read in the file @file{@var{name}.tmac}. Normally @code{groff} searches
1114 for this in its macro directories. If it isn't found, it tries
1115 @file{tmac.@var{name}} (searching in the same directories).
1118 Number the first page @var{num}.
1121 @cindex print current page register (@code{.P})
1122 Output only pages in @var{list}, which is a comma-separated list of page
1123 ranges; @samp{@var{n}} means print page@tie{}@var{n}, @samp{@var{m}-@var{n}}
1124 means print every page between @var{m} and@tie{}@var{n}, @samp{-@var{n}}
1125 means print every page up to@tie{}@var{n}, @samp{@var{n}-} means print every
1126 page beginning with@tie{}@var{n}. @code{gtroff} exits after printing the
1127 last page in the list. All the ranges are inclusive on both ends.
1129 Within @code{gtroff}, this information can be extracted with the
1130 @samp{.P} register. @xref{Built-in Registers}.
1132 If your document restarts page numbering at the beginning of each
1133 chapter, then @code{gtroff} prints the specified page range for each
1136 @item -r@var{c}@var{n}
1137 @itemx -r@var{name}=@var{n}
1138 Set number register@tie{}@var{c} or @var{name} to the value@tie{}@var{n}.
1139 @var{c}@tie{}must be a one-letter name; @var{name} can be of arbitrary
1140 length. @var{n}@tie{}can be any @code{gtroff} numeric expression. All
1141 register assignments happen before loading any macro file (including
1145 Search @file{@var{dir}} for subdirectories @file{dev@var{name}}
1146 (@var{name} is the name of the device), for the @file{DESC} file, and
1147 for font files before looking in the standard directories (@pxref{Font
1148 Directories}). This option is passed to all pre- and postprocessors
1149 using the @env{GROFF_FONT_PATH} environment variable.
1152 Search directory @file{@var{dir}} for macro files before the standard
1153 directories (@pxref{Macro Directories}).
1156 This option is as described in @ref{gsoelim}. It implies the
1161 @c =====================================================================
1163 @node Environment, Macro Directories, Groff Options, Invoking groff
1164 @section Environment
1165 @cindex environment variables
1166 @cindex variables in environment
1168 There are also several environment variables (of the operating system,
1169 not within @code{gtroff}) which can modify the behavior of @code{groff}.
1172 @item GROFF_COMMAND_PREFIX
1173 @tindex GROFF_COMMAND_PREFIX@r{, environment variable}
1174 @cindex command prefix
1175 @cindex prefix, for commands
1176 If this is set to@tie{}@var{X}, then @code{groff} runs @code{@var{X}troff}
1177 instead of @code{gtroff}. This also applies to @code{tbl}, @code{pic},
1178 @code{eqn}, @code{grn}, @code{refer}, and @code{soelim}. It does not
1179 apply to @code{grops}, @code{grodvi}, @code{grotty}, @code{pre-grohtml},
1180 @code{post-grohtml}, @code{grolj4}, and @code{gxditview}.
1182 The default command prefix is determined during the installation process.
1183 If a non-GNU troff system is found, prefix @samp{g} is used, none
1186 @item GROFF_TMAC_PATH
1187 @tindex GROFF_TMAC_PATH@r{, environment variable}
1188 A colon-separated list of directories in which to search for macro files
1189 (before the default directories are tried). @xref{Macro Directories}.
1191 @item GROFF_TYPESETTER
1192 @tindex GROFF_TYPESETTER@r{, environment variable}
1193 The default output device.
1195 @item GROFF_FONT_PATH
1196 @tindex GROFF_FONT_PATH@r{, environment variable}
1197 A colon-separated list of directories in which to search for the
1198 @code{dev}@var{name} directory (before the default directories are
1199 tried). @xref{Font Directories}.
1201 @item GROFF_BIN_PATH
1202 @tindex GROFF_BIN_PATH@r{, environment variable}
1203 This search path, followed by @code{PATH}, is used for commands executed
1207 @tindex GROFF_TMPDIR@r{, environment variable}
1208 @tindex TMPDIR@r{, environment variable}
1209 The directory in which @code{groff} creates temporary files. If this is
1210 not set and @env{TMPDIR} is set, temporary files are created in that
1211 directory. Otherwise temporary files are created in a system-dependent
1212 default directory (on Unix and GNU/Linux systems, this is usually
1213 @file{/tmp}). @code{grops}, @code{grefer}, @code{pre-grohtml}, and
1214 @code{post-grohtml} can create temporary files in this directory.
1217 Note that MS-DOS and MS-Windows ports of @code{groff} use semi-colons,
1218 rather than colons, to separate the directories in the lists described
1222 @c =====================================================================
1224 @node Macro Directories, Font Directories, Environment, Invoking groff
1225 @section Macro Directories
1226 @cindex macro directories
1227 @cindex directories for macros
1228 @cindex searching macros
1229 @cindex macros, searching
1231 All macro file names must be named @code{@var{name}.tmac} or
1232 @code{tmac.@var{name}} to make the @option{-m@var{name}} command line
1233 option work. The @code{mso} request doesn't have this restriction; any
1234 file name can be used, and @code{gtroff} won't try to append or prepend
1235 the @samp{tmac} string.
1237 @cindex tmac, directory
1238 @cindex directory, for tmac files
1240 @cindex path, for tmac files
1241 @cindex searching macro files
1242 @cindex macro files, searching
1243 @cindex files, macro, searching
1244 Macro files are kept in the @dfn{tmac directories}, all of which
1245 constitute the @dfn{tmac path}. The elements of the search path for
1246 macro files are (in that order):
1250 The directories specified with @code{gtroff}'s or @code{groff}'s
1251 @option{-M} command line option.
1254 @tindex GROFF_TMAC_PATH@r{, environment variable}
1255 The directories given in the @env{GROFF_TMAC_PATH} environment
1262 @cindex mode, unsafe
1263 @cindex current directory
1264 @cindex directory, current
1265 The current directory (only if in unsafe mode using the @option{-U}
1266 command line switch).
1269 @cindex home directory
1270 @cindex directory, home
1274 @cindex site-specific directory
1275 @cindex directory, site-specific
1276 @cindex platform-specific directory
1277 @cindex directory, platform-specific
1278 A platform-dependent directory, a site-specific (platform-independent)
1279 directory, and the main tmac directory; the default locations are
1282 /usr/local/lib/groff/site-tmac
1283 /usr/local/share/groff/site-tmac
1284 /usr/local/share/groff/1.18.2/tmac
1288 assuming that the version of @code{groff} is 1.18.2, and the installation
1289 prefix was @file{/usr/local}. It is possible to fine-tune those
1290 directories during the installation process.
1294 @c =====================================================================
1296 @node Font Directories, Paper Size, Macro Directories, Invoking groff
1297 @section Font Directories
1298 @cindex font directories
1299 @cindex directories for fonts
1300 @cindex searching fonts
1301 @cindex fonts, searching
1303 Basically, there is no restriction how font files for @code{groff} are
1304 named and how long font names are; however, to make the font family
1305 mechanism work (@pxref{Font Families}), fonts within a family should
1306 start with the family name, followed by the shape. For example, the
1307 Times family uses @samp{T} for the family name and @samp{R}, @samp{B},
1308 @samp{I}, and @samp{BI} to indicate the shapes `roman', `bold',
1309 `italic', and `bold italic', respectively. Thus the final font names
1310 are @samp{TR}, @samp{TB}, @samp{TI}, and @samp{TBI}.
1313 @cindex path, for font files
1314 All font files are kept in the @dfn{font directories} which constitute
1315 the @dfn{font path}. The file search functions will always append the
1316 directory @code{dev}@var{name}, where @var{name} is the name of the
1317 output device. Assuming, say, DVI output, and @file{/foo/bar} as a
1318 font directory, the font files for @code{grodvi} must be in
1319 @file{/foo/bar/devdvi}.
1321 The elements of the search path for font files are (in that order):
1325 The directories specified with @code{gtroff}'s or @code{groff}'s
1326 @option{-F} command line option. All device drivers and some
1327 preprocessors also have this option.
1330 @tindex GROFF_FONT_PATH@r{, environment variable}
1331 The directories given in the @env{GROFF_FONT_PATH} environment
1335 @cindex site-specific directory
1336 @cindex directory, site-specific
1337 A site-specific directory and the main font directory; the default
1341 /usr/local/share/groff/site-font
1342 /usr/local/share/groff/1.18.2/font
1346 assuming that the version of @code{groff} is 1.18.2, and the installation
1347 prefix was @file{/usr/local}. It is possible to fine-tune those
1348 directories during the installation process.
1352 @c =====================================================================
1354 @node Paper Size, Invocation Examples, Font Directories, Invoking groff
1358 @cindex landscape page orientation
1359 @cindex orientation, landscape
1360 @cindex page orientation, landscape
1362 In groff, the page size for @code{gtroff} and for output devices are
1363 handled separately. @xref{Page Layout}, for vertical manipulation of
1364 the page size. @xref{Line Layout}, for horizontal changes.
1366 A default paper size can be set in the device's @file{DESC} file. Most
1367 output devices also have a command line option @option{-p} to override
1368 the default paper size and option @option{-l} to use landscape
1369 orientation. @xref{DESC File Format}, for a description of the
1370 @code{papersize} keyword which takes the same argument as @option{-p}.
1372 @pindex papersize.tmac
1374 A convenient shorthand to set a particular paper size for @code{gtroff}
1375 is command line option @option{-dpaper=@var{size}}. This defines string
1376 @code{paper} which is processed in file @file{papersize.tmac} (loaded in
1377 the start-up file @file{troffrc} by default). Possible values for
1378 @var{size} are the same as the predefined values for the
1379 @code{papersize} keyword (but only in lowercase) except
1380 @code{a7}-@code{d7}. An appended @samp{l} (ell) character denotes
1381 landscape orientation.
1383 For example, use the following for PS output on A4 paper in landscape
1387 groff -Tps -dpaper=a4l -P-pa4 -P-l -ms foo.ms > foo.ps
1390 Note that it is up to the particular macro package to respect default
1391 page dimensions set in this way (most do).
1394 @c =====================================================================
1396 @node Invocation Examples, , Paper Size, Invoking groff
1397 @section Invocation Examples
1398 @cindex invocation examples
1399 @cindex examples of invocation
1401 This section lists several common uses of @code{groff} and the
1402 corresponding command lines.
1409 This command processes @file{file} without a macro package or a
1410 preprocessor. The output device is the default, @samp{ps}, and the
1411 output is sent to @code{stdout}.
1414 groff -t -mandoc -Tascii file | less
1418 This is basically what a call to the @code{man} program does.
1419 @code{gtroff} processes the manual page @file{file} with the
1420 @file{mandoc} macro file (which in turn either calls the @file{man} or
1421 the @file{mdoc} macro package), using the @code{tbl} preprocessor and
1422 the @acronym{ASCII} output device. Finally, the @code{less} pager
1423 displays the result.
1430 Preview @file{file} with @code{gxditview}, using the @file{me} macro
1431 package. Since no @option{-T} option is specified, use the default
1432 device (@samp{ps}). Note that you can either say @w{@samp{-m me}} or
1433 @w{@samp{-me}}; the latter is an anachronism from the early days of
1434 @acronym{UNIX}.@footnote{The same is true for the other main macro
1435 packages that come with @code{groff}: @file{man}, @file{mdoc},
1436 @file{ms}, @file{mm}, and @file{mandoc}. This won't work in general;
1437 for example, to load @file{trace.tmac}, either @samp{-mtrace} or
1438 @w{@samp{-m trace}} must be used.}
1441 groff -man -rD1 -z file
1445 Check @file{file} with the @file{man} macro package, forcing
1446 double-sided printing -- don't produce any output.
1452 @c ---------------------------------------------------------------------
1454 @node grog, , Invocation Examples, Invocation Examples
1455 @subsection @code{grog}
1458 @code{grog} reads files, guesses which of the @code{groff} preprocessors
1459 and/or macro packages are required for formatting them, and prints the
1460 @code{groff} command including those options on the standard output. It
1461 generates one or more of the options @option{-e}, @option{-man},
1462 @option{-me}, @option{-mm}, @option{-mom}, @option{-ms}, @option{-mdoc},
1463 @option{-mdoc-old}, @option{-p}, @option{-R}, @option{-g}, @option{-G},
1464 @option{-s}, and @option{-t}.
1466 A special file name@tie{}@file{-} refers to the standard input. Specifying
1467 no files also means to read the standard input. Any specified options
1468 are included in the printed command. No space is allowed between
1469 options and their arguments. The only options recognized are
1470 @option{-C} (which is also passed on) to enable compatibility mode, and
1471 @option{-v} to print the version number and exit.
1480 guesses the appropriate command to print @file{paper.ms} and then prints
1481 it to the command line after adding the @option{-Tdvi} option. For
1482 direct execution, enclose the call to @code{grog} in backquotes at the
1483 @acronym{UNIX} shell prompt:
1486 `grog -Tdvi paper.ms` > paper.dvi
1490 As seen in the example, it is still necessary to redirect the output to
1491 something meaningful (i.e.@: either a file or a pager program like
1496 @c =====================================================================
1497 @c =====================================================================
1499 @node Tutorial for Macro Users, Macro Packages, Invoking groff, Top
1500 @chapter Tutorial for Macro Users
1501 @cindex tutorial for macro users
1502 @cindex macros, tutorial for users
1503 @cindex user's tutorial for macros
1504 @cindex user's macro tutorial
1506 Most users tend to use a macro package to format their papers. This
1507 means that the whole breadth of @code{groff} is not necessary for most
1508 people. This chapter covers the material needed to efficiently use a
1517 @c =====================================================================
1519 @node Basics, Common Features, Tutorial for Macro Users, Tutorial for Macro Users
1521 @cindex basics of macros
1522 @cindex macro basics
1524 This section covers some of the basic concepts necessary to understand
1525 how to use a macro package.@footnote{This section is derived from
1526 @cite{Writing Papers with nroff using -me} by Eric P.@tie{}Allman.}
1527 References are made throughout to more detailed information, if desired.
1529 @code{gtroff} reads an input file prepared by the user and outputs a
1530 formatted document suitable for publication or framing. The input
1531 consists of text, or words to be printed, and embedded commands
1532 (@dfn{requests} and @dfn{escapes}), which tell @code{gtroff} how to
1533 format the output. For more detail on this, see @ref{Embedded
1536 The word @dfn{argument} is used in this chapter to mean a word or number
1537 which appears on the same line as a request, and which modifies the
1538 meaning of that request. For example, the request
1545 spaces one line, but
1552 spaces four lines. The number@tie{}4 is an argument to the @code{sp}
1553 request which says to space four lines instead of one. Arguments are
1554 separated from the request and from each other by spaces (@emph{no}
1555 tabs). More details on this can be found in @ref{Request and Macro
1558 The primary function of @code{gtroff} is to collect words from input
1559 lines, fill output lines with those words, justify the right-hand margin
1560 by inserting extra spaces in the line, and output the result. For
1568 Four score and seven
1573 is read, packed onto output lines, and justified to produce:
1576 Now is the time for all good men to come to the aid of their party.
1577 Four score and seven years ago, etc.
1582 Sometimes a new output line should be started even though the current
1583 line is not yet full; for example, at the end of a paragraph. To do
1584 this it is possible to cause a @dfn{break}, which starts a new output
1585 line. Some requests cause a break automatically, as normally do blank
1586 input lines and input lines beginning with a space.
1588 Not all input lines are text to be formatted. Some input lines are
1589 requests which describe how to format the text. Requests always have a
1590 period (@samp{.}) or an apostrophe (@samp{'}) as the first character of
1593 The text formatter also does more complex things, such as automatically
1594 numbering pages, skipping over page boundaries, putting footnotes in the
1595 correct place, and so forth.
1597 Here are a few hints for preparing text for input to @code{gtroff}.
1601 First, keep the input lines short. Short input lines are easier to
1602 edit, and @code{gtroff} packs words onto longer lines anyhow.
1605 In keeping with this, it is helpful to begin a new line after every
1606 comma or phrase, since common corrections are to add or delete sentences
1610 End each sentence with two spaces -- or better, start each sentence on a
1611 new line. @code{gtroff} recognizes characters that usually end a
1612 sentence, and inserts sentence space accordingly.
1615 Do not hyphenate words at the end of lines -- @code{gtroff} is smart
1616 enough to hyphenate words as needed, but is not smart enough to take
1617 hyphens out and join a word back together. Also, words such as
1618 ``mother-in-law'' should not be broken over a line, since then a space
1619 can occur where not wanted, such as ``@w{mother- in}-law''.
1622 @cindex double-spacing (@code{ls})
1624 @code{gtroff} double-spaces output text automatically if you use the
1625 request @w{@samp{.ls 2}}. Reactivate single-spaced mode by typing
1626 @w{@samp{.ls 1}}.@footnote{If you need finer granularity of the
1627 vertical space, use the @code{pvs} request (@pxref{Changing Type
1630 A number of requests allow to change the way the output looks,
1631 sometimes called the @dfn{layout} of the output page. Most of these
1632 requests adjust the placing of @dfn{whitespace} (blank lines or
1635 @cindex new page (@code{bp})
1636 The @code{bp} request starts a new page, causing a line break.
1638 @cindex blank line (@code{sp})
1639 @cindex empty line (@code{sp})
1640 @cindex line, empty (@code{sp})
1641 The request @w{@samp{.sp @var{N}}} leaves @var{N}@tie{}lines of blank
1642 space. @var{N}@tie{}can be omitted (meaning skip a single line) or can
1643 be of the form @var{N}i (for @var{N}@tie{}inches) or @var{N}c (for
1644 @var{N}@tie{}centimeters). For example, the input:
1648 My thoughts on the subject
1653 leaves one and a half inches of space, followed by the line ``My
1654 thoughts on the subject'', followed by a single blank line (more
1655 measurement units are available, see @ref{Measurements}).
1657 @cindex centering lines (@code{ce})
1658 @cindex lines, centering (@code{ce})
1659 Text lines can be centered by using the @code{ce} request. The line
1660 after @code{ce} is centered (horizontally) on the page. To center more
1661 than one line, use @w{@samp{.ce @var{N}}} (where @var{N} is the number
1662 of lines to center), followed by the @var{N}@tie{}lines. To center many
1663 lines without counting them, type:
1672 The @w{@samp{.ce 0}} request tells @code{groff} to center zero more
1673 lines, in other words, stop centering.
1675 @cindex line break (@code{br})
1676 @cindex break (@code{br})
1677 All of these requests cause a break; that is, they always start a new
1678 line. To start a new line without performing any other action, use
1682 @c =====================================================================
1684 @node Common Features, , Basics, Tutorial for Macro Users
1685 @section Common Features
1686 @cindex common features
1687 @cindex features, common
1689 @code{gtroff} provides very low-level operations for formatting a
1690 document. There are many common routine operations which are done in
1691 all documents. These common operations are written into @dfn{macros}
1692 and collected into a @dfn{macro package}.
1694 All macro packages provide certain common capabilities which fall into
1695 the following categories.
1699 * Sections and Chapters::
1700 * Headers and Footers::
1701 * Page Layout Adjustment::
1703 * Footnotes and Annotations::
1704 * Table of Contents::
1707 * Multiple Columns::
1708 * Font and Size Changes::
1709 * Predefined Strings::
1710 * Preprocessor Support::
1711 * Configuration and Customization::
1714 @c ---------------------------------------------------------------------
1716 @node Paragraphs, Sections and Chapters, Common Features, Common Features
1717 @subsection Paragraphs
1720 One of the most common and most used capability is starting a
1721 paragraph. There are a number of different types of paragraphs, any
1722 of which can be initiated with macros supplied by the macro package.
1723 Normally, paragraphs start with a blank line and the first line
1724 indented, like the text in this manual. There are also block style
1725 paragraphs, which omit the indentation:
1728 Some men look at constitutions with sanctimonious
1729 reverence, and deem them like the ark of the covenant, too
1730 sacred to be touched.
1734 And there are also indented paragraphs which begin with a tag or label
1735 at the margin and the remaining text indented.
1738 one This is the first paragraph. Notice how the first
1739 line of the resulting paragraph lines up with the
1740 other lines in the paragraph.
1744 This paragraph had a long label. The first
1745 character of text on the first line does not line up
1746 with the text on second and subsequent lines,
1747 although they line up with each other.
1750 A variation of this is a bulleted list.
1753 . Bulleted lists start with a bullet. It is possible
1754 to use other glyphs instead of the bullet. In nroff
1755 mode using the ASCII character set for output, a dot
1756 is used instead of a real bullet.
1759 @c ---------------------------------------------------------------------
1761 @node Sections and Chapters, Headers and Footers, Paragraphs, Common Features
1762 @subsection Sections and Chapters
1764 Most macro packages supply some form of section headers. The simplest
1765 kind is simply the heading on a line by itself in bold type. Others
1766 supply automatically numbered section heading or different heading
1767 styles at different levels. Some, more sophisticated, macro packages
1768 supply macros for starting chapters and appendices.
1770 @c ---------------------------------------------------------------------
1772 @node Headers and Footers, Page Layout Adjustment, Sections and Chapters, Common Features
1773 @subsection Headers and Footers
1775 Every macro package gives some way to manipulate the @dfn{headers} and
1776 @dfn{footers} (also called @dfn{titles}) on each page. This is text
1777 put at the top and bottom of each page, respectively, which contain
1778 data like the current page number, the current chapter title, and so
1779 on. Its appearance is not affected by the running text. Some packages
1780 allow for different ones on the even and odd pages (for material printed
1783 The titles are called @dfn{three-part titles}, that is, there is a
1784 left-justified part, a centered part, and a right-justified part. An
1785 automatically generated page number may be put in any of these fields
1786 with the @samp{%} character (see @ref{Page Layout}, for more details).
1788 @c ---------------------------------------------------------------------
1790 @node Page Layout Adjustment, Displays, Headers and Footers, Common Features
1791 @subsection Page Layout
1793 Most macro packages let the user specify top and bottom margins and
1794 other details about the appearance of the printed pages.
1796 @c ---------------------------------------------------------------------
1798 @node Displays, Footnotes and Annotations, Page Layout Adjustment, Common Features
1799 @subsection Displays
1802 @dfn{Displays} are sections of text to be set off from the body of
1803 the paper. Major quotes, tables, and figures are types of displays, as
1804 are all the examples used in this document.
1806 @cindex quotes, major
1807 @cindex major quotes
1808 @dfn{Major quotes} are quotes which are several lines long, and hence
1809 are set in from the rest of the text without quote marks around them.
1812 A @dfn{list} is an indented, single-spaced, unfilled display. Lists
1813 should be used when the material to be printed should not be filled and
1814 justified like normal text, such as columns of figures or the examples
1818 A @dfn{keep} is a display of lines which are kept on a single page if
1819 possible. An example for a keep might be a diagram. Keeps differ from
1820 lists in that lists may be broken over a page boundary whereas keeps are
1823 @cindex keep, floating
1824 @cindex floating keep
1825 @dfn{Floating keeps} move relative to the text. Hence, they are good for
1826 things which are referred to by name, such as ``See figure@tie{}3''. A
1827 floating keep appears at the bottom of the current page if it fits;
1828 otherwise, it appears at the top of the next page. Meanwhile, the
1829 surrounding text `flows' around the keep, thus leaving no blank areas.
1831 @c ---------------------------------------------------------------------
1833 @node Footnotes and Annotations, Table of Contents, Displays, Common Features
1834 @subsection Footnotes and Annotations
1838 There are a number of requests to save text for later printing.
1840 @dfn{Footnotes} are printed at the bottom of the current page.
1842 @cindex delayed text
1843 @dfn{Delayed text} is very similar to a footnote except that it is
1844 printed when called for explicitly. This allows a list of references to
1845 appear (for example) at the end of each chapter, as is the convention in
1848 Most macro packages which supply this functionality also supply a means
1849 of automatically numbering either type of annotation.
1851 @c ---------------------------------------------------------------------
1853 @node Table of Contents, Indices, Footnotes and Annotations, Common Features
1854 @subsection Table of Contents
1855 @cindex table of contents
1856 @cindex contents, table of
1858 @dfn{Tables of contents} are a type of delayed text having a tag
1859 (usually the page number) attached to each entry after a row of dots.
1860 The table accumulates throughout the paper until printed, usually after
1861 the paper has ended. Many macro packages provide the ability to have
1862 several tables of contents (e.g.@: a standard table of contents, a list
1865 @c ---------------------------------------------------------------------
1867 @node Indices, Paper Formats, Table of Contents, Common Features
1869 @cindex index, in macro package
1871 While some macro packages use the term @dfn{index}, none actually
1872 provide that functionality. The facilities they call indices are
1873 actually more appropriate for tables of contents.
1876 To produce a real index in a document, external tools like the
1877 @code{makeindex} program are necessary.
1879 @c ---------------------------------------------------------------------
1881 @node Paper Formats, Multiple Columns, Indices, Common Features
1882 @subsection Paper Formats
1883 @cindex paper formats
1885 Some macro packages provide stock formats for various kinds of
1886 documents. Many of them provide a common format for the title and
1887 opening pages of a technical paper. The @file{mm} macros in particular
1888 provide formats for letters and memoranda.
1890 @c ---------------------------------------------------------------------
1892 @node Multiple Columns, Font and Size Changes, Paper Formats, Common Features
1893 @subsection Multiple Columns
1895 Some macro packages (but not @file{man}) provide the ability to have two
1896 or more columns on a page.
1898 @c ---------------------------------------------------------------------
1900 @node Font and Size Changes, Predefined Strings, Multiple Columns, Common Features
1901 @subsection Font and Size Changes
1903 The built-in font and size functions are not always intuitive, so all
1904 macro packages provide macros to make these operations simpler.
1906 @c ---------------------------------------------------------------------
1908 @node Predefined Strings, Preprocessor Support, Font and Size Changes, Common Features
1909 @subsection Predefined Strings
1911 Most macro packages provide various predefined strings for a variety of
1912 uses; examples are sub- and superscripts, printable dates, quotes and
1913 various special characters.
1915 @c ---------------------------------------------------------------------
1917 @node Preprocessor Support, Configuration and Customization, Predefined Strings, Common Features
1918 @subsection Preprocessor Support
1920 All macro packages provide support for various preprocessors and may
1921 extend their functionality.
1923 For example, all macro packages mark tables (which are processed with
1924 @code{gtbl}) by placing them between @code{TS} and @code{TE} macros.
1925 The @file{ms} macro package has an option, @samp{.TS@tie{}H}, that prints
1926 a caption at the top of a new page (when the table is too long to fit on
1929 @c ---------------------------------------------------------------------
1931 @node Configuration and Customization, , Preprocessor Support, Common Features
1932 @subsection Configuration and Customization
1934 Some macro packages provide means of customizing many of the details of
1935 how the package behaves. This ranges from setting the default type size
1936 to changing the appearance of section headers.
1940 @c =====================================================================
1941 @c =====================================================================
1943 @node Macro Packages, gtroff Reference, Tutorial for Macro Users, Top
1944 @chapter Macro Packages
1945 @cindex macro packages
1946 @cindex packages, macros
1948 This chapter documents the main macro packages that come with
1951 Different main macro packages can't be used at the same time; for example
1954 groff -m man foo.man -m ms bar.doc
1958 doesn't work. Note that option arguments are processed before non-option
1959 arguments; the above (failing) sample is thus reordered to
1962 groff -m man -m ms foo.man bar.doc
1974 @c =====================================================================
1976 @node man, mdoc, Macro Packages, Macro Packages
1978 @cindex manual pages
1982 @pindex man-old.tmac
1984 This is the most popular and probably the most important macro package
1985 of @code{groff}. It is easy to use, and a vast majority of manual pages
1992 * Miscellaneous man macros::
1993 * Predefined man strings::
1994 * Preprocessors in man pages::
1995 * Optional man extensions::
1998 @c ---------------------------------------------------------------------
2000 @node Man options, Man usage, man, man
2003 The command line format for using the @file{man} macros with
2007 groff -m man [ -rLL=@var{length} ] [ -rLT=@var{length} ] [ -rFT=@var{dist} ]
2008 [ -rcR=1 ] [ -rC1 ] [ -rD1 ] [-rHY=@var{flags} ]
2009 [ -rP@var{nnn} ] [ -rS@var{xx} ] [ -rX@var{nnn} ]
2010 [ -rIN=@var{length} ] [ -rSN=@var{length} ] [ @var{files}@dots{} ]
2014 It is possible to use @samp{-man} instead of @w{@samp{-m man}}.
2018 This option (the default if a TTY output device is used) creates a
2019 single, very long page instead of multiple pages. Use @code{-rcR=0}
2023 If more than one manual page is given on the command line, number the
2024 pages continuously, rather than starting each at@tie{}1.
2027 Double-sided printing. Footers for even and odd pages are formatted
2030 @item -rFT=@var{dist}
2031 Set the position of the footer text to @var{dist}. If positive, the
2032 distance is measured relative to the top of the page, otherwise it is
2033 relative to the bottom. The default is @minus{}0.5@dmn{i}.
2035 @item -rHY=@var{flags}
2036 Set hyphenation flags. Possible values are 1@tie{}to hyphenate without
2037 restrictions, 2@tie{} to not hyphenate the last word on a page,
2038 4@tie{}to not hyphenate the last two characters of a word, and
2039 8@tie{}to not hyphenate the first two characters of a word. These
2040 values are additive; the default is@tie{}14.
2042 @item -rIN=@var{length}
2043 Set the body text indent to @var{length}.
2044 If not specified, the indent defaults to 7@dmn{n}
2045 (7@tie{}characters) in nroff mode and 7.2@dmn{n} otherwise.
2046 For nroff, this value should always be an integer multiple of unit @samp{n}
2047 to get consistent indentation.
2049 @item -rLL=@var{length}
2050 Set line length to @var{length}. If not specified, the line length
2051 defaults to 78@tie{}en in nroff mode (this is 78@tie{}characters per
2052 line) and 6.5@tie{}inch otherwise.
2054 @item -rLT=@var{length}
2055 Set title length to @var{length}. If not specified, the title length
2056 defaults to the line length.
2059 Page numbering starts with @var{nnn} rather than with@tie{}1.
2062 Use @var{xx} (which can be 10, 11, or@tie{}12@dmn{pt}) as the base
2063 document font size instead of the default value of@tie{}10@dmn{pt}.
2065 @item -rSN=@var{length}
2066 Set the indent for sub-subheadings to @var{length}.
2067 If not specified, the indent defaults to 3@dmn{n}.
2070 After page @var{nnn}, number pages as @var{nnn}a, @var{nnn}b,
2071 @var{nnn}c, etc. For example, the option @option{-rX2} produces the
2072 following page numbers: 1, 2, 2a, 2b, 2c, etc.
2075 @c ---------------------------------------------------------------------
2077 @node Man usage, Man font macros, Man options, man
2079 @cindex @code{man} macros
2080 @cindex macros for manual pages [@code{man}]
2083 This section describes the available macros for manual pages. For
2084 further customization, put additional macros and requests into the file
2085 @file{man.local} which is loaded immediately after the @file{man}
2088 @Defmac {TH, title section [@Var{extra1} [@Var{extra2} [@Var{extra3}]]], man}
2089 Set the title of the man page to @var{title} and the section to
2090 @var{section}, which must have a value between 1 and@tie{}8. The value
2091 of @var{section} may also have a string appended, e.g.@: @samp{.pm},
2092 to indicate a specific subsection of the man pages.
2094 Both @var{title} and @var{section} are positioned at the left and right
2095 in the header line (with @var{section} in parentheses immediately
2096 appended to @var{title}. @var{extra1} is positioned in the middle of
2097 the footer line. @var{extra2} is positioned at the left in the footer
2098 line (or at the left on even pages and at the right on odd pages if
2099 double-sided printing is active). @var{extra3} is centered in the
2102 For @acronym{HTML} output, headers and footers are completely suppressed.
2104 Additionally, this macro starts a new page; the new line number is@tie{}1
2105 again (except if the @option{-rC1} option is given on the command line)
2106 -- this feature is intended only for formatting multiple man pages; a
2107 single man page should contain exactly one @code{TH} macro at the
2108 beginning of the file.
2111 @Defmac {SH, [@Var{heading}], man}
2112 Set up an unnumbered section heading sticking out to the left. Prints
2113 out all the text following @code{SH} up to the end of the line (or the
2114 text in the next line if there is no argument to @code{SH}) in bold
2115 face (or the font specified by the string @code{HF}), one size larger than
2116 the base document size. Additionally, the left margin and the indentation
2117 for the following text is reset to its default value.
2120 @Defmac {SS, [@Var{heading}], man}
2121 Set up an unnumbered (sub)section heading. Prints out all the text
2122 following @code{SS} up to the end of the line (or the text in the next
2123 line if there is no argument to @code{SS}) in bold face (or the font
2124 specified by the string @code{HF}), at the same size as the base document
2125 size. Additionally, the left margin and the indentation for the
2126 following text is reset to its default value.
2129 @Defmac {TP, [@Var{nnn}], man}
2130 Set up an indented paragraph with label. The indentation is set to
2131 @var{nnn} if that argument is supplied (the default unit is @samp{n}
2132 if omitted), otherwise it is set to the previous indentation value
2133 specified with @code{TP}, @code{IP}, or @code{HP} (or to the default
2134 value if none of them have been used yet).
2136 The first line of text following this macro is interpreted as a string
2137 to be printed flush-left, as it is appropriate for a label. It is not
2138 interpreted as part of a paragraph, so there is no attempt to fill the
2139 first line with text from the following input lines. Nevertheless, if
2140 the label is not as wide as the indentation the paragraph starts
2141 at the same line (but indented), continuing on the following lines.
2142 If the label is wider than the indentation the descriptive part
2143 of the paragraph begins on the line following the label, entirely
2144 indented. Note that neither font shape nor font size of the label is
2145 set to a default value; on the other hand, the rest of the text has
2146 default font settings.
2149 @DefmacList {LP, , man}
2150 @DefmacItem {PP, , man}
2151 @DefmacListEnd {P, , man}
2152 These macros are mutual aliases. Any of them causes a line break at
2153 the current position, followed by a vertical space downwards by the
2154 amount specified by the @code{PD} macro. The font size and shape are
2155 reset to the default value (10@dmn{pt} roman if no @option{-rS} option
2156 is given on the command line). Finally, the current left margin and the
2157 indentation is restored.
2160 @Defmac {IP, [@Var{designator} [@Var{nnn}]], man}
2161 Set up an indented paragraph, using @var{designator} as a tag to mark
2162 its beginning. The indentation is set to @var{nnn} if that argument
2163 is supplied (default unit is @samp{n}), otherwise it is set to the
2164 previous indentation value specified with @code{TP}, @code{IP}, or
2165 @code{HP} (or the default value if none of them have been used yet).
2166 Font size and face of the paragraph (but not the designator) are reset
2167 to their default values.
2169 To start an indented paragraph with a particular indentation but without
2170 a designator, use @samp{""} (two double quotes) as the first argument of
2173 For example, to start a paragraph with bullets as the designator and
2174 4@tie{}en indentation, write
2181 @Defmac {HP, [@Var{nnn}], man}
2182 @cindex hanging indentation [@code{man}]
2183 @cindex @code{man} macros, hanging indentation
2184 Set up a paragraph with hanging left indentation. The indentation is
2185 set to @var{nnn} if that argument is supplied (default unit is
2186 @samp{n}), otherwise it is set to the previous indentation value
2187 specified with @code{TP}, @code{IP}, or @code{HP} (or the default
2188 value if non of them have been used yet). Font size and face are reset
2189 to their default values.
2192 @Defmac {RS, [@Var{nnn}], man}
2193 @cindex left margin, how to move [@code{man}]
2194 @cindex @code{man} macros, moving left margin
2195 Move the left margin to the right by the value @var{nnn} if specified
2196 (default unit is @samp{n}); otherwise it is set to the previous
2197 indentation value specified with @code{TP}, @code{IP}, or @code{HP}
2198 (or to the default value if none of them have been used yet). The
2199 indentation value is then set to the default.
2201 Calls to the @code{RS} macro can be nested.
2204 @Defmac {RE, [@Var{nnn}], man}
2205 Move the left margin back to level @var{nnn}, restoring the previous left
2206 margin. If no argument is given, it moves one level back. The first
2207 level (i.e., no call to @code{RS} yet) has number@tie{}1, and each call
2208 to @code{RS} increases the level by@tie{}1.
2211 @cindex line breaks, with vertical space [@code{man}]
2212 @cindex @code{man} macros, line breaks with vertical space
2213 To summarize, the following macros cause a line break with the insertion
2214 of vertical space (which amount can be changed with the @code{PD}
2215 macro): @code{SH}, @code{SS}, @code{TP}, @code{LP} (@code{PP},
2216 @code{P}), @code{IP}, and @code{HP}.
2218 @cindex line breaks, without vertical space [@code{man}]
2219 @cindex @code{man} macros, line breaks without vertical space
2220 The macros @code{RS} and @code{RE} also cause a break but do not insert
2223 @cindex default indentation, resetting [@code{man}]
2224 @cindex indentaion, resetting to default [@code{man}]
2225 @cindex @code{man} macros, resetting default indentation
2226 Finally, the macros @code{SH}, @code{SS}, @code{LP} (@code{PP}, @code{P}),
2227 and @code{RS} reset the indentation to its default value.
2229 @c ---------------------------------------------------------------------
2231 @node Man font macros, Miscellaneous man macros, Man usage, man
2232 @subsection Macros to set fonts
2233 @cindex font selection [@code{man}]
2234 @cindex @code{man} macros, how to set fonts
2236 The standard font is roman; the default text size is 10@tie{}point.
2237 If command line option @option{-rS=@var{n}} is given, use
2238 @var{n}@dmn{pt} as the default text size.
2240 @Defmac {SM, [@Var{text}], man}
2241 Set the text on the same line or the text on the next line in a font
2242 that is one point size smaller than the default font.
2245 @Defmac {SB, [@Var{text}], man}
2246 @cindex bold face [@code{man}]
2247 @cindex @code{man} macros, bold face
2248 Set the text on the same line or the text on the next line in bold face
2249 font, one point size smaller than the default font.
2252 @Defmac {BI, text, man}
2253 Set its arguments alternately in bold face and italic, without a space
2254 between the arguments. Thus,
2257 .BI this "word and" that
2261 produces ``thisword andthat'' with ``this'' and ``that'' in bold face,
2262 and ``word and'' in italics.
2265 @Defmac {IB, text, man}
2266 Set its arguments alternately in italic and bold face, without a space
2267 between the arguments.
2270 @Defmac {RI, text, man}
2271 Set its arguments alternately in roman and italic, without a space between
2275 @Defmac {IR, text, man}
2276 Set its arguments alternately in italic and roman, without a space between
2280 @Defmac {BR, text, man}
2281 Set its arguments alternately in bold face and roman, without a space
2282 between the arguments.
2285 @Defmac {RB, text, man}
2286 Set its arguments alternately in roman and bold face, without a space
2287 between the arguments.
2290 @Defmac {B, [@Var{text}], man}
2291 Set @var{text} in bold face. If no text is present on the line where
2292 the macro is called, then the text of the next line appears in bold
2296 @Defmac {I, [@Var{text}], man}
2297 @cindex italic fonts [@code{man}]
2298 @cindex @code{man} macros, italic fonts
2299 Set @var{text} in italic. If no text is present on the line where the
2300 macro is called, then the text of the next line appears in italic.
2303 @c ---------------------------------------------------------------------
2305 @node Miscellaneous man macros, Predefined man strings, Man font macros, man
2306 @subsection Miscellaneous macros
2309 @cindex @code{man} macros, default indentation
2310 @cindex default indentation [@code{man}]
2311 The default indentation is 7.2@dmn{n} in troff mode and 7@dmn{n} in
2312 nroff mode except for @code{grohtml} which ignores indentation.
2315 @cindex tab stops [@code{man}]
2316 @cindex @code{man} macros, tab stops
2317 Set tabs every 0.5@tie{}inches. Since this macro is always executed
2318 during a call to the @code{TH} macro, it makes sense to call it only if
2319 the tab positions have been changed.
2322 @Defmac {PD, [@Var{nnn}], man}
2323 @cindex empty space before a paragraph [@code{man}]
2324 @cindex @code{man} macros, empty space before a paragraph
2325 Adjust the empty space before a new paragraph (or section). The
2326 optional argument gives the amount of space (default unit is
2327 @samp{v}); without parameter, the value is reset to its default value
2328 (1@tie{}line in nroff mode, 0.4@dmn{v}@tie{}otherwise).
2330 This affects the macros @code{SH}, @code{SS}, @code{TP}, @code{LP} (as
2331 well as @code{PP} and @code{P}), @code{IP}, and @code{HP}.
2334 The following two macros are included for
2337 @Defmac {AT, [@Var{system} [@Var{release}]], man}
2338 @cindex @code{man}macros, BSD compatibility
2339 Alter the footer for use with @acronym{AT&T} manpages.
2340 This command exists only for compatibility; don't use it.
2341 The first argument @var{system} can be:
2345 7th Edition (the default)
2354 An optional second argument @var{release} to @code{AT} specifies the
2355 release number (such as ``System V Release 3'').
2358 @Defmac {UC, [@Var{version}], man}
2359 @cindex @code{man}macros, BSD compatibility
2360 Alters the footer for use with @acronym{BSD} manpages.
2361 This command exists only for compatibility; don't use it.
2362 The argument can be:
2366 3rd Berkeley Distribution (the default)
2369 4th Berkeley Distribution
2372 4.2 Berkeley Distribution
2375 4.3 Berkeley Distribution
2378 4.4 Berkeley Distribution
2382 @c ---------------------------------------------------------------------
2384 @node Predefined man strings, Preprocessors in man pages, Miscellaneous man macros, man
2385 @subsection Predefined strings
2387 The following strings are defined:
2390 Switch back to the default font size.
2394 The typeface used for headings.
2395 The default is @samp{B}.
2399 The `registered' sign.
2403 The `trademark' sign.
2406 @DefstrList {lq, man}
2407 @DefstrListEnd {rq, man}
2408 @cindex @code{lq} glyph, and @code{lq} string [@code{man}]
2409 @cindex @code{rq} glyph, and @code{rq} string [@code{man}]
2410 Left and right quote. This is equal to @code{\(lq} and @code{\(rq},
2414 @c ---------------------------------------------------------------------
2416 @node Preprocessors in man pages, Optional man extensions, Predefined man strings, man
2417 @subsection Preprocessors in @file{man} pages
2419 @cindex preprocessor, calling convention
2420 @cindex calling convention of preprocessors
2421 If a preprocessor like @code{gtbl} or @code{geqn} is needed, it has
2422 become common usage to make the first line of the man page look like
2429 @pindex geqn@r{, invocation in manual pages}
2430 @pindex grefer@r{, invocation in manual pages}
2431 @pindex gtbl@r{, invocation in manual pages}
2432 @pindex man@r{, invocation of preprocessors}
2434 Note the single space character after the double quote. @var{word}
2435 consists of letters for the needed preprocessors: @samp{e} for
2436 @code{geqn}, @samp{r} for @code{grefer}, @samp{t} for @code{gtbl}.
2437 Modern implementations of the @code{man} program read this first line
2438 and automatically call the right preprocessor(s).
2440 @c ---------------------------------------------------------------------
2442 @node Optional man extensions, , Preprocessors in man pages, man
2443 @subsection Optional @file{man} extensions
2446 Use the file @file{man.local} for local extensions
2447 to the @code{man} macros or for style changes.
2449 @unnumberedsubsubsec Custom headers and footers
2450 @cindex @code{man} macros, custom headers and footers
2452 In groff versions 1.18.2 and later, you can specify custom
2453 headers and footers by redefining the following macros in
2457 Control the content of the headers.
2458 Normally, the header prints the command name
2459 and section number on either side, and the
2460 optional fifth argument to @code{TH} in the center.
2464 Control the content of the footers.
2465 Normally, the footer prints the page number
2466 and the third and fourth arguments to @code{TH}.
2468 Use the @code{FT} number register to specify the
2470 The default is @minus{}0.5@dmn{i}.
2473 @unnumberedsubsubsec Ultrix-specific man macros
2474 @cindex Ultrix-specific @code{man} macros
2475 @cindex @code{man} macros, Ultrix-specific
2478 The @code{groff} source distribution includes
2479 a file named @file{man.ultrix}, containing
2480 macros compatible with the Ultrix variant of
2482 Copy this file into @file{man.local} (or use the @code{mso} request to
2483 load it) to enable the following macros.
2485 @Defmac {CT, @Var{key}, man}
2486 Print @samp{<CTRL/@var{key}>}.
2490 Print subsequent text using the constant width (Courier) typeface.
2494 Begin a non-filled display.
2498 End a non-filled display started with @code{Ds}.
2501 @Defmac {EX, [@Var{indent}], man}
2502 Begins a non-filled display
2503 using the constant width (Courier) typeface.
2504 Use the optional @var{indent} argument to
2509 End a non-filled display started with @code{EX}.
2512 @Defmac {G, [@Var{text}], man}
2513 Sets @var{text} in Helvetica.
2514 If no text is present on the line where
2515 the macro is called, then the text of the
2516 next line appears in Helvetica.
2519 @Defmac {GL, [@Var{text}], man}
2520 Sets @var{text} in Helvetica Oblique.
2521 If no text is present on the line where
2522 the macro is called, then the text of the
2523 next line appears in Helvetica Oblique.
2526 @Defmac {HB, [@Var{text}], man}
2527 Sets @var{text} in Helvetica Bold.
2528 If no text is present on the line where
2529 the macro is called, then all text up to
2530 the next @code{HB} appears in Helvetica Bold.
2533 @Defmac {TB, [@Var{text}], man}
2534 Identical to @code{HB}.
2537 @Defmac {MS, @Var{title} @Var{sect} [@Var{punct}], man}
2538 Set a manpage reference in Ultrix format.
2539 The @var{title} is in Courier instead of italic.
2540 Optional punctuation follows the section number without
2541 an intervening space.
2544 @Defmac {NT, [@code{C}] [@Var{title}], man}
2546 Print the optional @Var{title}, or the word ``Note'',
2547 centered on the page.
2548 Text following the macro makes up the body of the note,
2549 and is indented on both sides.
2550 If the first argument is @code{C}, the body of the
2551 note is printed centered (the second argument replaces
2552 the word ``Note'' if specified).
2556 End a note begun with @code{NT}.
2559 @Defmac {PN, @Var{path} [@Var{punct}], man}
2560 Set the path name in constant width (Courier),
2561 followed by optional punctuation.
2564 @Defmac {Pn, [@Var{punct}] @Var{path} [@Var{punct}], man}
2565 When called with two arguments, identical to @code{PN}.
2566 When called with three arguments,
2567 set the second argument in constant width (Courier),
2568 bracketed by the first and third arguments in the current font.
2572 Switch to roman font and turn off any underlining in effect.
2576 Print the string @samp{<RETURN>}.
2579 @Defmac {VS, [@code{4}], man}
2580 Start printing a change bar in the margin if
2581 the number @code{4} is specified.
2582 Otherwise, this macro does nothing.
2586 End printing the change bar begun by @code{VS}.
2589 @unnumberedsubsubsec Simple example
2591 The following example @file{man.local} file
2592 alters the @code{SH} macro to add some extra
2593 vertical space before printing the heading.
2594 Headings are printed in Helvetica Bold.
2597 .\" Make the heading fonts Helvetica
2600 .\" Put more whitespace in front of headings.
2603 . if t .sp (u;\\n[PD]*2)
2608 @c =====================================================================
2610 @node mdoc, ms, man, Macro Packages
2611 @section @file{mdoc}
2612 @cindex @code{mdoc} macros
2614 @c XXX documentation
2615 @c XXX this is a placeholder until we get stuff knocked into shape
2616 See the @cite{groff_mdoc(7)} man page (type @command{man groff_mdoc}
2617 at the command line).
2620 @c =====================================================================
2622 @node ms, me, mdoc, Macro Packages
2624 @cindex @code{ms} macros
2627 macros are suitable for reports, letters, books,
2628 user manuals, and so forth.
2629 The package provides macros for cover pages, section headings,
2630 paragraphs, lists, footnotes, pagination,
2631 and a table of contents.
2635 * General ms Structure::
2636 * ms Document Control Registers::
2637 * ms Cover Page Macros::
2640 * Differences from AT&T ms::
2643 @c ---------------------------------------------------------------------
2645 @node ms Intro, General ms Structure, ms, ms
2646 @subsection Introduction to @file{ms}
2648 The original @file{-ms} macros were included with
2649 @acronym{AT&T} @code{troff} as well as the
2651 While the @file{man} package is intended for brief documents
2652 that can be read on-line as well as printed, the @file{ms}
2653 macros are suitable for longer documents that are meant to be
2654 printed rather than read on-line.
2656 The @file{ms} macro package included with @code{groff}
2657 is a complete, bottom-up re-implementation.
2658 Several macros (specific to @acronym{AT&T}
2659 or Berkeley) are not included, while several new commands are.
2660 @xref{Differences from AT&T ms}, for more information.
2662 @c ---------------------------------------------------------------------
2664 @node General ms Structure, ms Document Control Registers, ms Intro, ms
2665 @subsection General structure of an @file{ms} document
2666 @cindex @code{ms} macros, general structure
2668 The @file{ms} macro package expects a certain amount of structure,
2669 but not as much as packages such as @file{man} or @file{mdoc}.
2671 The simplest documents can begin with a paragraph macro
2672 (such as @code{LP} or @code{PP}),
2673 and consist of text separated by paragraph macros
2674 or even blank lines.
2675 Longer documents have a structure as follows:
2679 If you invoke the @code{RP}
2680 (report) macro on the first line of the document,
2681 @code{groff} prints the cover page information on its own page;
2682 otherwise it prints the information on the
2683 first page with your document text immediately following.
2684 Other document formats found in @acronym{AT&T} @code{troff}
2685 are specific to @acronym{AT&T} or Berkeley, and are not supported in
2688 @item Format and layout
2689 By setting number registers,
2690 you can change your document's type (font and size),
2691 margins, spacing, headers and footers, and footnotes.
2692 @xref{ms Document Control Registers}, for more details.
2695 A cover page consists of a title, the author's name and institution,
2696 an abstract, and the date.
2697 @footnote{Actually, only the title is required.}
2698 @xref{ms Cover Page Macros}, for more details.
2701 Following the cover page is your document.
2702 You can use the @file{ms}
2703 macros to write reports, letters, books, and so forth.
2704 The package is designed for structured documents,
2705 consisting of paragraphs interspersed with headings
2706 and augmented by lists, footnotes, tables, and other
2708 @xref{ms Body Text}, for more details.
2710 @item Table of contents
2711 Longer documents usually include a table of contents,
2712 which you can invoke by placing the
2714 macro at the end of your document.
2716 macros have minimal indexing facilities, consisting of the
2717 @code{IX} macro, which prints an entry on standard error.
2718 Printing the table of contents at the end is necessary since
2719 @code{groff} is a single-pass text formatter,
2720 thus it cannot determine the page number of each section
2721 until that section has actually been set and printed.
2722 Since @file{ms} output is intended for hardcopy,
2723 you can manually relocate the pages containing
2724 the table of contents between the cover page and the
2725 body text after printing.
2728 @c ---------------------------------------------------------------------
2730 @node ms Document Control Registers, ms Cover Page Macros, General ms Structure, ms
2731 @subsection Document control registers
2732 @cindex @code{ms} macros, document control registers
2734 The following is a list of document control number registers.
2735 For the sake of consistency,
2736 set registers related to margins at the beginning of your document,
2737 or just after the @code{RP} macro.
2738 You can set other registers later in your document,
2739 but you should keep them together at the beginning
2740 to make them easy to find and edit as necessary.
2742 @unnumberedsubsubsec Margin Settings
2745 Defines the page offset (i.e.@: the left margin).
2746 There is no explicit right margin setting; the combination of
2747 the @code{PO} and @code{LL} registers implicitly define the
2750 Effective: next page.
2752 Default value: 1@dmn{i}.
2756 Defines the line length (i.e.@: the width of the body text).
2758 Effective: next paragraph.
2764 Defines the title length (i.e.@: the header and footer width).
2765 This is usually the same as @code{LL}, but not necessarily.
2767 Effective: next paragraph.
2773 Defines the header margin height at the top of the page.
2775 Effective: next page.
2781 Defines the footer margin height at the bottom of the page.
2783 Effective: next page.
2788 @unnumberedsubsubsec Text Settings
2791 Defines the point size of the body text.
2793 Effective: next paragraph.
2799 Defines the space between lines (line height plus leading).
2801 Effective: next paragraph.
2806 @unnumberedsubsubsec Paragraph Settings
2809 Defines the initial indent of a @code{.PP} paragraph.
2811 Effective: next paragraph.
2817 Defines the space between paragraphs.
2819 Effective: next paragraph.
2821 Default: 0.3@dmn{v}.
2825 Defines the indent on both sides of a quoted (@code{.QP}) paragraph.
2827 Effective: next paragraph.
2832 @unnumberedsubsubsec Footnote Settings
2835 Defines the length of a footnote.
2837 Effective: next footnote.
2839 Default: @math{@code{@\n[LL]} * 5 / 6}.
2843 Defines the footnote indent.
2845 Effective: next footnote.
2851 The footnote format:
2854 Prints the footnote number as a superscript; indents the footnote (default).
2857 Prints the number followed by a period (like 1.)
2858 and indents the footnote.
2861 Like 1, without an indent.
2864 Like 1, but prints the footnote number as a hanging paragraph.
2867 Effective: next footnote.
2873 Defines the footnote point size.
2875 Effective: next footnote.
2877 Default: @math{@code{@\n[PS]} - 2}.
2881 Defines the footnote vertical spacing.
2883 Effective: next footnote.
2885 Default: @math{@code{@\n[FPS]} + 2}.
2889 Defines the footnote paragraph spacing.
2891 Effective: next footnote.
2893 Default: @math{@code{@\n[PD]} / 2}.
2896 @unnumberedsubsubsec Miscellaneous Number Registers
2898 @Defmpreg {MINGW, ms}
2899 Defines the minimum width between columns in a multi-column document.
2901 Effective: next page.
2906 @c ---------------------------------------------------------------------
2908 @node ms Cover Page Macros, ms Body Text, ms Document Control Registers, ms
2909 @subsection Cover page macros
2910 @cindex @code{ms} macros, cover page
2911 @cindex cover page macros, [@code{ms}]
2913 Use the following macros to create a cover page for your document
2916 @Defmac {RP, [@code{no}], ms}
2917 Specifies the report format for your document.
2918 The report format creates a separate cover page.
2919 The default action (no @code{.RP}
2920 macro) is to print a subset of the
2921 cover page on page 1 of your document.
2923 If you use the word @code{no} as an optional argument,
2924 @code{groff} prints a title page but
2925 does not repeat any of the title page information
2926 (title, author, abstract, etc.)
2927 on page 1 of the document.
2930 @Defmac {DA, [@dots{}], ms}
2931 (optional) Print the current date, or the arguments to the macro if any,
2932 on the title page (if specified) and in the footers.
2933 This is the default for @code{nroff}.
2936 @Defmac {ND, [@dots{}], ms}
2937 (optional) Print the current date, or the arguments to the macro if any,
2938 on the title page (if specified) but not in the footers.
2939 This is the default for @code{troff}.
2943 Specifies the document title.
2944 @code{groff} collects text following the @code{.TL}
2945 macro into the title, until reaching the author name or abstract.
2949 Specifies the author's name, which appears on the
2950 line (or lines) immediately following.
2951 You can specify multiple authors as follows:
2957 University of West Bumblefuzz
2961 Monolithic Corporation
2968 Specifies the author's institution.
2969 You can specify multiple institutions in the same way
2970 that you specify multiple authors.
2973 @Defmac {AB, [@code{no}], ms}
2974 Begins the abstract.
2975 The default is to print the word @acronym{ABSTRACT},
2976 centered and in italics, above the text of the abstract.
2977 The word @code{no} as an optional argument suppresses this heading.
2984 The following is example mark-up for a title page.
2985 @cindex title page, example markup
2986 @cindex example markup, title page
2992 The Inevitability of Code Bloat
2993 in Commercial and Free Software
2997 University of West Bumblefuzz
2999 This report examines the long-term growth
3000 of the code bases in two large, popular software
3001 packages; the free Emacs and the commercial
3003 While differences appear in the type or order
3004 of features added, due to the different
3005 methodologies used, the results are the same
3008 The free software approach is shown to be
3009 superior in that while free software can
3010 become as bloated as commercial offerings,
3011 free software tends to have fewer serious
3012 bugs and the added features are in line with
3016 ... the rest of the paper follows ...
3020 @c ---------------------------------------------------------------------
3022 @node ms Body Text, ms Page Layout, ms Cover Page Macros, ms
3023 @subsection Body text
3024 @cindex @code{ms} macros, body text
3026 This section describes macros used to mark up the body of your document.
3027 Examples include paragraphs, sections, and other groups.
3030 * Paragraphs in ms::
3032 * Highlighting in ms::
3036 * ms Displays and Keeps::
3038 * Example multi-page table::
3042 @c ---------------------------------------------------------------------
3044 @node Paragraphs in ms, Headings in ms, ms Body Text, ms Body Text
3045 @subsubsection Paragraphs
3046 @cindex @code{ms} macros, paragraph handling
3048 The following paragraph types are available.
3051 Sets a paragraph with an initial indent.
3055 Sets a paragraph with no initial indent.
3059 Sets a paragraph that is indented at both left and right margins.
3060 The effect is identical to the @acronym{HTML} @code{<BLOCKQUOTE>} element.
3061 The next paragraph or heading returns margins to normal.
3065 Sets a paragraph whose lines are indented,
3066 except for the first line.
3067 This is a Berkeley extension.
3070 The following markup uses all four paragraph macros.
3075 Cases used in the study
3077 The following software and versions were
3078 considered for this report.
3080 For commercial software, we chose
3081 .B "Microsoft Word for Windows" ,
3082 starting with version 1.0 through the
3083 current version (Word 2000).
3085 For free software, we chose
3087 from its first appearance as a standalone
3088 editor through the current version (v20).
3089 See [Bloggs 2002] for details.
3091 Franklin's Law applied to software:
3092 software expands to outgrow both
3093 RAM and disk space over time.
3098 .I "Everyone's a Critic" ,
3099 Underground Press, March 2002.
3100 A definitive work that answers all questions
3101 and criticisms about the quality and usability of
3107 @c ---------------------------------------------------------------------
3109 @node Headings in ms, Highlighting in ms, Paragraphs in ms, ms Body Text
3110 @subsubsection Headings
3111 @cindex @code{ms} macros, headings
3113 Use headings to create a hierarchical structure for your document.
3114 The @file{ms} macros print headings in @strong{bold},
3115 using the same font family and point size as the body text.
3117 The following describes the heading macros:
3119 @DefmacList {NH, @Var{curr-level}, ms}
3120 @DefmacListEnd {NH, @t{S} @Var{level0} @dots{}, ms}
3122 The argument is either a numeric argument to indicate the
3123 level of the heading, or the letter@tie{}@code{S} followed by numeric
3124 arguments to set the heading level explicitly.
3126 If you specify heading levels out of sequence, such as invoking
3127 @samp{.NH 3} after @samp{.NH 1}, @code{groff}
3128 prints a warning on standard error.
3132 Unnumbered subheading.
3135 @c ---------------------------------------------------------------------
3137 @node Highlighting in ms, Lists in ms, Headings in ms, ms Body Text
3138 @subsubsection Highlighting
3139 @cindex @code{ms} macros, highlighting
3141 The @file{ms} macros provide a variety of methods to highlight
3144 @Defmac {B, [@Var{txt} [@Var{post} [@Var{pre}]]], ms}
3145 Sets its first argument in @strong{bold type}.
3146 If you specify a second argument, @code{groff} prints it in the
3147 previous font after the bold text, with no intervening space
3148 (this allows you to set punctuation after the highlighted text
3149 without highlighting the punctuation).
3150 Similarly, it prints the third argument (if any) in the previous
3151 font @strong{before} the first argument.
3158 prints (@strong{foo}).
3160 If you give this macro no arguments, @code{groff}
3161 prints all text following in bold until
3162 the next highlighting, paragraph, or heading macro.
3165 @Defmac {R, [@Var{txt} [@Var{post} [@Var{pre}]]], ms}
3166 Sets its first argument in roman (or regular) type.
3167 It operates similarly to the @code{B}@tie{}macro otherwise.
3170 @Defmac {I, [@Var{txt} [@Var{post} [@Var{pre}]]], ms}
3171 Sets its first argument in @emph{italic type}.
3172 It operates similarly to the @code{B}@tie{}macro otherwise.
3175 @Defmac {CW, [@Var{txt} [@Var{post} [@Var{pre}]]], ms}
3176 Sets its first argument in a @code{constant width face}.
3177 It operates similarly to the @code{B}@tie{}macro otherwise.
3180 @Defmac {BI, [@Var{txt} [@Var{post} [@Var{pre}]]], ms}
3181 Sets its first argument in bold italic type.
3182 It operates similarly to the @code{B}@tie{}macro otherwise.
3185 @Defmac {BX, [@Var{txt}], ms}
3186 Prints its argument and draws a box around it.
3187 If you want to box a string that contains spaces,
3188 use a digit-width space (@code{\0}).
3191 @Defmac {UL, [@Var{txt} [@Var{post}]], ms}
3192 Prints its first argument with an underline.
3193 If you specify a second argument, @code{groff}
3194 prints it in the previous font after
3195 the underlined text, with no intervening space.
3199 Prints all text following in larger type
3200 (two points larger than the current point size) until
3201 the next font size, highlighting, paragraph, or heading macro.
3202 You can specify this macro multiple times
3203 to enlarge the point size as needed.
3207 Prints all text following in smaller type
3208 (two points smaller than the current point size) until
3209 the next type size, highlighting, paragraph, or heading macro.
3210 You can specify this macro multiple times
3211 to reduce the point size as needed.
3215 Prints all text following in the normal point size
3216 (that is, the value of the @code{PS} register).
3219 @c ---------------------------------------------------------------------
3221 @node Lists in ms, Indents in ms, Highlighting in ms, ms Body Text
3222 @subsubsection Lists
3223 @cindex @code{ms} macros, lists
3225 The @code{.IP} macro handles duties for all lists.
3227 @Defmac {IP, [@Var{marker} [@Var{width}]], ms}
3228 The @var{marker} is usually a bullet glyph (@code{\[bu]})
3229 for unordered lists, a number (or auto-incrementing number
3230 register) for numbered lists, or a word or phrase for indented
3231 (glossary-style) lists.
3233 The @var{width} specifies the indent for the body of each list item;
3234 its default unit is @samp{n}.
3235 Once specified, the indent remains the same for all
3236 list items in the document until specified again.
3239 The following is an example of a bulleted list.
3240 @cindex example markup, bulleted list [@code{ms}]
3241 @cindex bulleted list, example markup [@code{ms}]
3267 The following is an example of a numbered list.
3268 @cindex example markup, numbered list [@code{ms}]
3269 @cindex numbered list, example markup [@code{ms}]
3294 Note the use of the auto-incrementing number
3295 register in this example.
3298 The following is an example of a glossary-style list.
3299 @cindex example markup, glossary-style list [@code{ms}]
3300 @cindex glossary-style list, example markup [@code{ms}]
3303 A glossary-style list:
3305 Two or more attorneys.
3307 Firearms, preferably
3317 A glossary-style list:
3320 Two or more attorneys.
3322 guns Firearms, preferably large-caliber.
3325 Gotta pay for those lawyers and guns!
3328 In the last example, the @code{IP} macro places the definition
3329 on the same line as the term if it has enough space; otherwise,
3330 it breaks to the next line and starts the definition below the
3332 This may or may not be the effect you want, especially if some
3333 of the definitions break and some do not.
3334 The following examples show two possible ways to force a break.
3336 The first workaround uses the @code{br}
3337 request to force a break after printing the term or label.
3341 A glossary-style list:
3343 Two or more attorneys.
3346 Firearms, preferably large-caliber.
3348 Gotta pay for those lawyers and guns!
3353 The second workaround uses the @code{\p} escape to force the break.
3354 Note the space following the escape; this is important.
3355 If you omit the space, @code{groff} prints the first word on
3356 the same line as the term or label (if it fits) @strong{then}
3361 A glossary-style list:
3363 Two or more attorneys.
3365 \p Firearms, preferably large-caliber.
3367 Gotta pay for those lawyers and guns!
3372 To set nested lists, use the @code{RS} and @code{RE} macros.
3373 @xref{Indents in ms}, for more information.
3374 @cindex @code{ms} macros, nested lists
3375 @cindex nested lists [@code{ms}]
3410 @c ---------------------------------------------------------------------
3412 @node Indents in ms, Tabstops in ms, Lists in ms, ms Body Text
3413 @subsubsection Indents
3416 you may need to indent a section of text
3417 while still wrapping and filling.
3419 for an example of nested lists.
3421 @DefmacList {RS, , ms}
3422 @DefmacListEnd {RE, , ms}
3423 These macros begin and end an indented section.
3424 The @code{PI} register controls the amount of indent,
3425 allowing the indented text to line up under hanging
3426 and indented paragraphs.
3429 @xref{ms Displays and Keeps},
3430 for macros to indent and turn off filling.
3432 @c ---------------------------------------------------------------------
3434 @node Tabstops in ms, ms Displays and Keeps, Indents in ms, ms Body Text
3435 @subsubsection Tab Stops
3437 Use the @code{ta} request to define tab stops as needed.
3438 @xref{Tabs and Fields}.
3441 Use this macro to reset the tab stops to the default for @file{ms}
3443 You can redefine the @code{TA} macro to create a different set
3444 of default tab stops.
3447 @c ---------------------------------------------------------------------
3449 @node ms Displays and Keeps, ms Insertions, Tabstops in ms, ms Body Text
3450 @subsubsection Displays and keeps
3451 @cindex @code{ms} macros, displays
3452 @cindex @code{ms} macros, keeps
3453 @cindex keeps [@code{ms}]
3454 @cindex displays [@code{ms}]
3456 Use displays to show text-based examples or figures
3457 (such as code listings).
3459 Displays turn off filling, so lines of code are displayed
3460 as-is without inserting @code{br} requests in between each line.
3461 Displays can be @dfn{kept} on a single page, or allowed
3462 to break across pages.
3464 @DefmacList {DS, @t{L}, ms}
3465 @DefmacItem {LD, , ms}
3466 @DefmacListEnd {DE, , ms}
3467 Left-justified display.
3468 The @samp{.DS L} call generates a page break, if necessary,
3469 to keep the entire display on one page.
3470 The @code{LD} macro allows the display to break across pages.
3471 The @code{DE} macro ends the display.
3474 @DefmacList {DS, @t{I}, ms}
3475 @DefmacItem {ID, , ms}
3476 @DefmacListEnd {DE, , ms}
3477 Indents the display as defined by the @code{DI} register.
3478 The @samp{.DS I} call generates a page break, if necessary,
3479 to keep the entire display on one page.
3480 The @code{ID} macro allows the display to break across pages.
3481 The @code{DE} macro ends the display.
3484 @DefmacList {DS, @t{B}, ms}
3485 @DefmacItem {BD, , ms}
3486 @DefmacListEnd {DE, , ms}
3487 Sets a block-centered display: the entire display is left-justified,
3488 but indented so that the longest line in the display is centered
3490 The @samp{.DS B} call generates a page break, if necessary,
3491 to keep the entire display on one page.
3492 The @code{BD} macro allows the display to break across pages.
3493 The @code{DE} macro ends the display.
3496 @DefmacList {DS, @t{C}, ms}
3497 @DefmacItem {CD, , ms}
3498 @DefmacListEnd {DE, , ms}
3499 Sets a centered display: each line in the display is centered.
3500 The @samp{.DS C} call generates a page break, if necessary,
3501 to keep the entire display on one page.
3502 The @code{CD} macro allows the display to break across pages.
3503 The @code{DE} macro ends the display.
3506 @DefmacList {DS, @t{R}, ms}
3507 @DefmacItem {RD, , ms}
3508 @DefmacListEnd {DE, , ms}
3509 Right-justifies each line in the display.
3510 The @samp{.DS R} call generates a page break, if necessary,
3511 to keep the entire display on one page.
3512 The @code{RD} macro allows the display to break across pages.
3513 The @code{DE} macro ends the display.
3516 @DefmacList {Ds, , ms}
3517 @DefmacListEnd {De, , ms}
3518 These two macros are aliases for @code{DS} and @code{DE}, respectively.
3522 On occasion, you may want to @dfn{keep} other text together on a page.
3523 For example, you may want to keep two paragraphs together, or
3524 a paragraph that refers to a table (or list, or other item)
3525 immediately following.
3526 The @file{ms} macros provide the @code{KS} and @code{KE}
3527 macros for this purpose.
3529 @DefmacList {KS, , ms}
3530 @DefmacListEnd {KE, , ms}
3531 The @code{KS} macro begins a block of text to be kept on a
3532 single page, and the @code{KE} macro ends the block.
3535 @DefmacList {KF, , ms}
3536 @DefmacListEnd {KE, , ms}
3537 Specifies a @dfn{floating keep};
3538 if the keep cannot fit on the current page, @code{groff}
3539 holds the contents of the keep and allows text following
3540 the keep (in the source file) to fill in the remainder of
3542 When the page breaks, whether by an explicit @code{bp}
3543 request or by reaching the end of the page, @code{groff}
3544 prints the floating keep at the top of the new page.
3545 This is useful for printing large graphics or tables
3546 that do not need to appear exactly where specified.
3549 You can also use the @code{ne} request to force a page break if
3550 there is not enough vertical space remaining on the page.
3553 Use the following macros to draw a box around a section of
3554 text (such as a display).
3556 @DefmacList {B1, , ms}
3557 @DefmacListEnd {B2, , ms}
3558 Marks the beginning and ending of text that is to have a
3559 box drawn around it.
3560 The @code{B1} macro begins the box; the @code{B2} macro ends it.
3561 Text in the box is automatically placed in a diversion (keep).
3564 @c ---------------------------------------------------------------------
3566 @node ms Insertions, Example multi-page table, ms Displays and Keeps, ms Body Text
3567 @subsubsection Tables, figures, equations, and references
3568 @cindex @code{ms} macros, tables
3569 @cindex @code{ms} macros, figures
3570 @cindex @code{ms} macros, equations
3571 @cindex @code{ms} macros, references
3572 @cindex tables [@code{ms}]
3573 @cindex figures [@code{ms}]
3574 @cindex equations [@code{ms}]
3575 @cindex references [@code{ms}]
3577 The @file{ms} macros support the standard
3578 @code{groff} preprocessors:
3579 @code{tbl}, @code{pic}, @code{eqn}, and @code{refer}.
3584 You mark text meant for preprocessors by enclosing it
3585 in pairs of tags as follows.
3587 @DefmacList {TS, [@code{H}], ms}
3588 @DefmacListEnd {TE, , ms}
3589 Denotes a table, to be processed by the @code{tbl} preprocessor.
3590 The optional argument@tie{}@code{H} to @code{TS} instructs @code{groff}
3591 to create a running header with the information
3592 up to the @code{TH} macro.
3593 @code{groff} prints the header at the beginning of the
3594 table; if the table runs onto another page, @code{groff}
3595 prints the header on the next page as well.
3598 @DefmacList {PS, , ms}
3599 @DefmacListEnd {PE, , ms}
3600 Denotes a graphic, to be processed by the @code{pic} preprocessor.
3601 You can create a @code{pic} file by hand, using the @acronym{AT&T}
3602 @code{pic} manual available on the Web as a reference, or by using
3603 a graphics program such as @code{xfig}.
3606 @DefmacList {EQ, [@Var{align}], ms}
3607 @DefmacListEnd {EN, , ms}
3608 Denotes an equation, to be processed by the @code{eqn} preprocessor.
3609 The optional @var{align} argument can be @code{C}, @code{L},
3610 or@tie{}@code{I} to center (the default), left-justify, or indent the
3614 @DefmacList {[, , ms}
3615 @DefmacListEnd {], , ms}
3616 Denotes a reference, to be processed by the @code{refer} preprocessor.
3617 The @acronym{GNU} @cite{refer(1)} man page provides a comprehensive
3618 reference to the preprocessor and the format of the bibliographic
3623 * Example multi-page table::
3626 @c ---------------------------------------------------------------------
3628 @node Example multi-page table, ms Footnotes, ms Insertions, ms Body Text
3629 @subsubsection An example multi-page table
3630 @cindex example markup, multi-page table [@code{ms}]
3631 @cindex multi-page table, example markup [@code{ms}]
3633 The following is an example of how to set up a
3634 table that may print across two or more pages.
3641 Text ...of heading...
3646 ... the rest of the table follows...
3652 @c ---------------------------------------------------------------------
3654 @node ms Footnotes, , Example multi-page table, ms Body Text
3655 @subsubsection Footnotes
3656 @cindex @code{ms} macros, footnotes
3657 @cindex footnotes [@code{ms}]
3659 The @file{ms} macro package has a flexible footnote system.
3660 You can specify either numbered footnotes or symbolic footnotes
3661 (that is, using a marker such as a dagger symbol).
3664 Specifies the location of a numbered footnote marker in the text.
3667 @DefmacList {FS, , ms}
3668 @DefmacListEnd {FE, , ms}
3669 Specifies the text of the footnote.
3670 The default action is to create a numbered footnote;
3671 you can create a symbolic footnote by specifying
3673 (such as @code{\[dg]} for the dagger glyph)
3674 in the body text and as an argument to the @code{FS} macro,
3675 followed by the text of the footnote
3676 and the @code{FE} macro.
3679 You can control how @code{groff}
3680 prints footnote numbers by changing the value of the
3681 @code{FF} register. @xref{ms Document Control Registers}.
3683 @c ---------------------------------------------------------------------
3685 @node ms Page Layout, Differences from AT&T ms, ms Body Text, ms
3686 @subsection Page layout
3687 @cindex @code{ms} macros, page layout
3688 @cindex page layout [@code{ms}]
3690 The default output from the @file{ms}
3691 macros provides a minimalist page layout:
3692 it prints a single column, with the page number centered at the top
3694 It prints no footers.
3696 You can change the layout by setting
3697 the proper number registers and strings.
3700 * ms Headers and Footers::
3702 * ms Multiple Columns::
3704 * ms Strings and Special Characters::
3707 @c ---------------------------------------------------------------------
3709 @node ms Headers and Footers, ms Margins, ms Page Layout, ms Page Layout
3710 @subsubsection Headers and footers
3711 @cindex @code{ms} macros, headers
3712 @cindex @code{ms} macros, footers
3713 @cindex headers [@code{ms}]
3714 @cindex footers [@code{ms}]
3716 For documents that do not distinguish between odd and even pages,
3717 set the following strings:
3719 @DefstrList {LH, ms}
3720 @DefstrItem {CH, ms}
3721 @DefstrListEnd {RH, ms}
3722 Sets the left, center, and right headers.
3725 @DefstrList {LF, ms}
3726 @DefstrItem {CF, ms}
3727 @DefstrListEnd {RF, ms}
3728 Sets the left, center, and right footers.
3732 For documents that need different information printed in the
3733 even and odd pages, use the following macros:
3735 @DefmacList {OH, @t{'}@Var{left}@t{'}@Var{center}@t{'}@Var{right}@t{'}, ms}
3736 @DefmacItem {EH, @t{'}@Var{left}@t{'}@Var{center}@t{'}@Var{right}@t{'}, ms}
3737 @DefmacItem {OF, @t{'}@Var{left}@t{'}@Var{center}@t{'}@Var{right}@t{'}, ms}
3738 @DefmacListEnd {EF, @t{'}@Var{left}@t{'}@Var{center}@t{'}@Var{right}@t{'}, ms}
3739 The @code{OH} and @code{EH} macros define headers for the odd and even pages;
3740 the @code{OF} and @code{EF} macros define footers for the odd and even pages.
3741 This is more flexible than defining the individual strings.
3743 You can replace the quote (@code{'}) marks with any character not
3744 appearing in the header or footer text.
3747 @c ---------------------------------------------------------------------
3749 @node ms Margins, ms Multiple Columns, ms Headers and Footers, ms Page Layout
3750 @subsubsection Margins
3751 @cindex @code{ms} macros, margins
3753 You control margins using a set of number registers.
3754 @xref{ms Document Control Registers}, for details.
3756 @c ---------------------------------------------------------------------
3758 @node ms Multiple Columns, ms TOC, ms Margins, ms Page Layout
3759 @subsubsection Multiple columns
3760 @cindex @code{ms} macros, multiple columns
3761 @cindex multiple columns [@code{ms}]
3763 The @file{ms} macros can set text in as many columns as will
3764 reasonably fit on the page.
3765 The following macros are available;
3766 all of them force a page break if a multi-column mode is already set.
3767 However, if the current mode is single-column, starting a multi-column
3768 mode does @strong{not} force a page break.
3778 @Defmac {MC, [@Var{width} [@Var{gutter}]], ms}
3780 If you specify no arguments, it is equivalent to the
3782 Otherwise, @var{width} is the width of each column and
3783 @var{gutter} is the space between columns.
3784 The @code{MINGW} number register controls the default gutter width.
3787 @c ---------------------------------------------------------------------
3789 @node ms TOC, ms Strings and Special Characters, ms Multiple Columns, ms Page Layout
3790 @subsubsection Creating a table of contents
3791 @cindex @code{ms} macros, creating table of contents
3792 @cindex table of contents, creating [@code{ms}]
3794 The facilities in the @file{ms} macro package for creating
3795 a table of contents are semi-automated at best.
3796 Assuming that you want the table of contents to consist of
3797 the document's headings, you need to repeat those headings
3798 wrapped in @code{XS} and @code{XE} macros.
3800 @DefmacList {XS, [@Var{page}], ms}
3801 @DefmacItem {XA, [@Var{page}], ms}
3802 @DefmacListEnd {XE, , ms}
3803 These macros define a table of contents
3804 or an individual entry in the table of contents,
3805 depending on their use.
3806 The macros are very simple; they cannot indent a heading based on its level.
3807 The easiest way to work around this is to add tabs
3808 to the table of contents string.
3809 The following is an example:
3831 You can manually create a table of contents
3832 by beginning with the @code{XS} macro for the first entry,
3833 specifying the page number for that entry as the argument to @code{XS}.
3834 Add subsequent entries using the @code{XA} macro,
3835 specifying the page number for that entry as the argument to @code{XA}.
3836 The following is an example:
3843 A Brief History of the Universe
3845 Details of Galactic Formation
3852 @Defmac {TC, [@code{no}], ms}
3853 Prints the table of contents on a new page,
3854 setting the page number to@tie{}@strong{i} (Roman numeral one).
3855 You should usually place this macro at the end of the
3856 file, since @code{groff} is a single-pass formatter and
3857 can only print what has been collected up to the point
3858 that the @code{TC} macro appears.
3860 The optional argument @code{no} suppresses printing
3861 the title specified by the string register @code{TOC}.
3864 @Defmac{PX, [@code{no}], ms}
3865 Prints the table of contents on a new page,
3866 using the current page numbering sequence.
3867 Use this macro to print a manually-generated table of contents
3868 at the beginning of your document.
3870 The optional argument @code{no} suppresses printing
3871 the title specified by the string register @code{TOC}.
3874 The @cite{Groff and Friends HOWTO}
3875 includes a @code{sed} script that automatically inserts
3876 @code{XS} and @code{XE} macro entries after each heading in a document.
3878 Altering the @code{NH} macro to automatically build the table
3879 of contents is perhaps initially more difficult, but would save
3880 a great deal of time in the long run if you use @file{ms} regularly.
3882 @c ---------------------------------------------------------------------
3884 @node ms Strings and Special Characters, , ms TOC, ms Page Layout
3885 @subsubsection Strings and Special Characters
3886 @cindex @code{ms} macros, strings
3887 @cindex @code{ms} macros, special characters
3888 @cindex @code{ms} macros, accent marks
3889 @cindex accent marks [@code{ms}]
3890 @cindex special characters [@code{ms}]
3891 @cindex strings [@code{ms}]
3893 The @file{ms} macros provide the following predefined strings.
3894 You can change the string definitions to help in creating
3895 documents in languages other than English.
3897 @Defstr {REFERENCES, ms}
3898 Contains the string printed at the beginning of the
3899 references (bibliography) page.
3900 The default is @samp{References}.
3903 @Defstr {ABSTRACT, ms}
3904 Contains the string printed at the beginning of the abstract.
3905 The default is @samp{ABSTRACT}.
3909 Contains the string printed at the beginning of the table of contents.
3912 @DefstrList {MONTH1, ms}
3913 @DefstrItem {MONTH2, ms}
3914 @DefstrItem {MONTH3, ms}
3915 @DefstrItem {MONTH4, ms}
3916 @DefstrItem {MONTH5, ms}
3917 @DefstrItem {MONTH6, ms}
3918 @DefstrItem {MONTH7, ms}
3919 @DefstrItem {MONTH8, ms}
3920 @DefstrItem {MONTH9, ms}
3921 @DefstrItem {MONTH10, ms}
3922 @DefstrItem {MONTH11, ms}
3923 @DefstrListEnd {MONTH12, ms}
3924 Prints the full name of the month in dates.
3925 The default is @samp{January}, @samp{February}, etc.
3928 The following special characters are available@footnote{For an
3929 explanation what special characters are see @ref{Special Characters}.}:
3935 @DefstrList {*Q, ms}
3936 @DefstrListEnd {*U, ms}
3937 Prints typographer's quotes in troff,
3938 plain quotes in nroff.
3939 @code{*Q} is the left quote and @code{*U} is the right quote.
3942 Improved accent marks are available in the @file{ms} macros.
3945 Specify this macro at the beginning of your document
3946 to enable extended accent marks and special characters.
3947 This is a Berkeley extension.
3949 To use the accent marks, place them @strong{after}
3950 the character being accented.
3953 The following accent marks are available
3954 after invoking the @code{AM} macro:
3976 @deffn String @t{\*[:]}
3978 @stindex : @r{[}ms@r{]}
3981 @stindex \*[@r{<colon>}] @r{[}ms@r{]}
4002 The following are standalone characters
4003 available after invoking the @code{AM} macro:
4006 Upside-down question mark.
4010 Upside-down exclamation point.
4014 German @ss{} ligature.
4042 Lowercase @ae{} ligature.
4046 Uppercase @AE{} ligature.
4049 @c ---------------------------------------------------------------------
4051 @node Differences from AT&T ms, , ms Page Layout, ms
4052 @subsection Differences from @acronym{AT&T} @file{ms}
4053 @cindex @code{ms} macros, differences from @acronym{AT&T}
4054 @cindex @acronym{AT&T} @code{troff}, @code{ms} macro package differences
4056 This section lists the (minor) differences between the
4057 @code{groff -ms} macros and @acronym{AT&T}
4058 @code{troff -ms} macros.
4061 * Missing ms Macros::
4062 * Additional ms Macros::
4065 @c ---------------------------------------------------------------------
4067 @node Missing ms Macros, Additional ms Macros, Differences from AT&T ms, Differences from AT&T ms
4068 @subsubsection @code{troff} macros not appearing in @code{groff}
4070 Macros missing from @code{groff -ms}
4071 are cover page macros specific to Bell Labs.
4072 The macros known to be missing are:
4076 Technical memorandum; a cover sheet style
4079 Internal memorandum; a cover sheet style
4082 Memo for record; a cover sheet style
4085 Memo for file; a cover sheet style
4088 Engineer's notes; a cover sheet style
4091 Computing Science Tech Report; a cover sheet style
4097 Cover sheet information
4103 @c ---------------------------------------------------------------------
4105 @node Additional ms Macros, , Missing ms Macros, Differences from AT&T ms
4106 @subsubsection @code{groff} macros not appearing in @acronym{AT&T} @code{troff}
4108 The @code{groff -ms} macros have a few minor extensions
4109 compared to the @acronym{AT&T} @code{troff -ms} macros.
4112 Improved accent marks.
4113 @xref{ms Strings and Special Characters}, for details.
4116 @Defmac {DS, @t{I}, ms}
4118 The default behavior of @acronym{AT&T} @code{troff -ms}
4119 was to indent; the @code{groff} default prints displays
4120 flush left with the body text.
4124 Print text in @code{constant width} (Courier) font.
4128 Indexing term (printed on standard error).
4129 You can write a script to capture and process an index
4130 generated in this manner.
4134 The following additional number registers
4135 appear in @code{groff -ms}:
4137 @Defmpreg {MINGW, ms}
4138 Specifies a minimum space
4139 between columns (for multi-column output); this takes the
4140 place of the @code{GW} register that was documented but apparently
4141 not implemented in @acronym{AT&T} @code{troff}.
4145 Several new string registers are available as well.
4146 You can change these to handle (for example) the local language.
4147 @xref{ms Strings and Special Characters}, for details.
4150 @c =====================================================================
4152 @node me, mm, ms, Macro Packages
4154 @cindex @code{me} macro package
4156 @c XXX documentation
4157 @c XXX this is a placeholder until we get stuff knocked into shape
4158 See the @file{meintro.me} and @file{meref.me} documents in
4159 groff's @file{doc} directory.
4162 @c =====================================================================
4164 @node mm, , me, Macro Packages
4166 @cindex @code{mm} macro package
4168 @c XXX documentation
4169 @c XXX this is a placeholder until we get stuff knocked into shape
4170 See the @cite{groff_mm(7)} man page (type @command{man groff_mm} at
4174 @c =====================================================================
4175 @c =====================================================================
4177 @node gtroff Reference, Preprocessors, Macro Packages, Top
4178 @chapter @code{gtroff} Reference
4179 @cindex reference, @code{gtroff}
4180 @cindex @code{gtroff}, reference
4182 This chapter covers @strong{all} of the facilities of @code{gtroff}.
4183 Users of macro packages may skip it if not interested in details.
4191 * Embedded Commands::
4193 * Manipulating Filling and Adjusting::
4194 * Manipulating Hyphenation::
4195 * Manipulating Spacing::
4197 * Character Translations::
4198 * Troff and Nroff Mode::
4203 * Fonts and Symbols::
4206 * Conditionals and Loops::
4209 * Drawing Requests::
4213 * Suppressing output::
4216 * Postprocessor Access::
4218 * Gtroff Internals::
4220 * Implementation Differences::
4224 @c =====================================================================
4226 @node Text, Measurements, gtroff Reference, gtroff Reference
4228 @cindex text, @code{gtroff} processing
4230 @code{gtroff} input files contain text with control commands
4231 interspersed throughout. But, even without control codes, @code{gtroff}
4232 still does several things with the input text:
4236 filling and adjusting
4239 adding additional space after sentences
4245 inserting implicit line breaks
4249 * Filling and Adjusting::
4253 * Implicit Line Breaks::
4254 * Input Conventions::
4258 @c ---------------------------------------------------------------------
4260 @node Filling and Adjusting, Hyphenation, Text, Text
4261 @subsection Filling and Adjusting
4265 When @code{gtroff} reads text, it collects words from the input and fits
4266 as many of them together on one output line as it can. This is known as
4269 @cindex leading spaces
4270 @cindex spaces, leading and trailing
4271 @cindex extra spaces
4272 @cindex trailing spaces
4273 Once @code{gtroff} has a @dfn{filled} line, it tries to @dfn{adjust}
4274 it. This means it widens the spacing between words until the text
4275 reaches the right margin (in the default adjustment mode). Extra spaces
4276 between words are preserved, but spaces at the end of lines are ignored.
4277 Spaces at the front of a line cause a @dfn{break} (breaks are
4278 explained in @ref{Implicit Line Breaks}).
4280 @xref{Manipulating Filling and Adjusting}.
4282 @c ---------------------------------------------------------------------
4284 @node Hyphenation, Sentences, Filling and Adjusting, Text
4285 @subsection Hyphenation
4288 Since the odds are not great for finding a set of words, for every
4289 output line, which fit nicely on a line without inserting excessive
4290 amounts of space between words, @code{gtroff} hyphenates words so
4291 that it can justify lines without inserting too much space between
4292 words. It uses an internal hyphenation algorithm (a simplified version
4293 of the algorithm used within @TeX{}) to indicate which words can be
4294 hyphenated and how to do so. When a word is hyphenated, the first part
4295 of the word is added to the current filled line being output (with
4296 an attached hyphen), and the other portion is added to the next
4299 @xref{Manipulating Hyphenation}.
4301 @c ---------------------------------------------------------------------
4303 @node Sentences, Tab Stops, Hyphenation, Text
4304 @subsection Sentences
4307 Although it is often debated, some typesetting rules say there should be
4308 different amounts of space after various punctuation marks. For
4309 example, the @cite{Chicago typsetting manual} says that a period at the
4310 end of a sentence should have twice as much space following it as would
4311 a comma or a period as part of an abbreviation.
4313 @c XXX exact citation of Chicago manual
4315 @cindex sentence space
4316 @cindex space between sentences
4317 @cindex french-spacing
4318 @code{gtroff} does this by flagging certain characters (normally
4319 @samp{!}, @samp{?}, and @samp{.}) as @dfn{end-of-sentence} characters.
4320 When @code{gtroff} encounters one of these characters at the end of a
4321 line, it appends a normal space followed by a @dfn{sentence space} in
4322 the formatted output. (This justifies one of the conventions mentioned
4323 in @ref{Input Conventions}.)
4325 @cindex transparent characters
4326 @cindex character, transparent
4327 @cindex @code{dg} glyph, at end of sentence
4328 @cindex @code{rq} glyph, at end of sentence
4329 @cindex @code{"}, at end of sentence
4330 @cindex @code{'}, at end of sentence
4331 @cindex @code{)}, at end of sentence
4332 @cindex @code{]}, at end of sentence
4333 @cindex @code{*}, at end of sentence
4334 In addition, the following characters and symbols are treated
4335 transparently while handling end-of-sentence characters: @samp{"},
4336 @samp{'}, @samp{)}, @samp{]}, @samp{*}, @code{\[dg]}, and @code{\[rq]}.
4338 See the @code{cflags} request in @ref{Using Symbols}, for more details.
4340 @cindex @code{\&}, at end of sentence
4341 To prevent the insertion of extra space after an end-of-sentence
4342 character (at the end of a line), append @code{\&}.
4344 @c ---------------------------------------------------------------------
4346 @node Tab Stops, Implicit Line Breaks, Sentences, Text
4347 @subsection Tab Stops
4349 @cindex stops, tabulator
4350 @cindex tab character
4351 @cindex character, tabulator
4353 @cindex @acronym{EBCDIC} encoding
4354 @cindex encoding, @acronym{EBCDIC}
4355 @code{gtroff} translates @dfn{tabulator characters}, also called
4356 @dfn{tabs} (normally code point @acronym{ASCII} @code{0x09} or
4357 @acronym{EBCDIC} @code{0x05}), in the input into movements to the next
4358 tabulator stop. These tab stops are initially located every half inch
4359 across the page. Using this, simple tables can be made easily.
4360 However, it can often be deceptive as the appearance (and width) of the
4361 text on a terminal and the results from @code{gtroff} can vary greatly.
4363 Also, a possible sticking point is that lines beginning with tab
4364 characters are still filled, again producing unexpected results.
4365 For example, the following input
4367 @multitable {12345678} {12345678} {12345678} {12345678}
4369 @tab 1 @tab 2 @tab 3
4377 @multitable {12345678} {12345678} {12345678} {12345678} {12345678} {12345678} {12345678}
4379 @tab 1 @tab 2 @tab 3 @tab @tab 4 @tab 5
4382 @xref{Tabs and Fields}.
4384 @c ---------------------------------------------------------------------
4386 @node Implicit Line Breaks, Input Conventions, Tab Stops, Text
4387 @subsection Implicit Line Breaks
4388 @cindex implicit line breaks
4389 @cindex implicit breaks of lines
4390 @cindex line, implicit breaks
4391 @cindex break, implicit
4394 An important concept in @code{gtroff} is the @dfn{break}. When a break
4395 occurs, @code{gtroff} outputs the partially filled line
4396 (unjustified), and resumes collecting and filling text on the next output
4402 @cindex blank line macro (@code{blm})
4403 There are several ways to cause a break in @code{gtroff}. A blank
4404 line not only causes a break, but it also outputs a one-line vertical
4405 space (effectively a blank line). Note that this behaviour can be
4406 modified with the blank line macro request @code{blm}.
4407 @xref{Blank Line Traps}.
4411 A line that begins with a space causes a break and the space is
4412 output at the beginning of the next line. Note that this space isn't
4413 adjusted, even in fill mode.
4415 The end of file also causes a break -- otherwise the last line of
4416 the document may vanish!
4418 Certain requests also cause breaks, implicitly or explicitly. This is
4419 discussed in @ref{Manipulating Filling and Adjusting}.
4421 @c ---------------------------------------------------------------------
4423 @node Input Conventions, Input Encodings, Implicit Line Breaks, Text
4424 @subsection Input Conventions
4425 @cindex input conventions
4426 @cindex conventions for input
4428 Since @code{gtroff} does filling automatically, it is traditional in
4429 @code{groff} not to try and type things in as nicely formatted
4430 paragraphs. These are some conventions commonly used when typing
4435 Break lines after punctuation, particularly at the end of a sentence
4436 and in other logical places. Keep separate phrases on lines by
4437 themselves, as entire phrases are often added or deleted when editing.
4440 Try to keep lines less than 40-60@tie{}characters, to allow space for
4441 inserting more text.
4444 Do not try to do any formatting in a @acronym{WYSIWYG} manner (i.e.,
4445 don't try using spaces to get proper indentation).
4448 @c ---------------------------------------------------------------------
4450 @node Input Encodings, , Input Conventions, Text
4451 @subsection Input Encodings
4453 Currently, the following input encodings are available.
4457 @cindex encoding, input, @acronym{EBCDIC}
4458 @cindex @acronym{EBCDIC}, input encoding
4459 @cindex input encoding, @acronym{EBCDIC}
4460 @cindex encoding, input, cp1047
4461 @cindex cp1047, input encoding
4462 @cindex input encoding, cp1047
4463 @cindex IBM cp1047 input encoding
4465 This input encoding works only on @acronym{EBCDIC} platforms (and vice
4466 versa, the other input encodings don't work with @acronym{EBCDIC}); the
4467 file @file{cp1047.tmac} is by default loaded at start-up.
4470 @cindex encoding, input, @w{latin-1} (ISO @w{8859-1})
4471 @cindex @w{latin-1} (ISO @w{8859-1}), input encoding
4472 @cindex ISO @w{8859-1} (@w{latin-1}), input encoding
4473 @cindex input encoding, @w{latin-1} (ISO @w{8859-1})
4475 This is the default input encoding on non-@acronym{EBCDIC} platforms;
4476 the file @file{latin1.tmac} is loaded at start-up.
4479 @cindex encoding, input, @w{latin-2} (ISO @w{8859-2})
4480 @cindex @w{latin-2} (ISO @w{8859-2}), input encoding
4481 @cindex ISO @w{8859-2} (@w{latin-2}), input encoding
4482 @cindex input encoding, @w{latin-2} (ISO @w{8859-2})
4484 To use this encoding, either say @w{@samp{.mso latin2.tmac}} at the very
4485 beginning of your document or use @samp{-mlatin2} as a command line
4486 argument for @code{groff}.
4488 @item latin-9 (latin-0)
4489 @cindex encoding, input, @w{latin-9} (@w{latin-0}, ISO @w{8859-15})
4490 @cindex @w{latin-9} (@w{latin-0}, ISO @w{8859-15}), input encoding
4491 @cindex ISO @w{8859-15} (@w{latin-9}, @w{latin-0}), input encoding
4492 @cindex input encoding, @w{latin-9} (@w{latin-9}, ISO @w{8859-15})
4494 This encoding is intended (at least in Europe) to replace @w{latin-1}
4495 encoding. The main difference to @w{latin-1} is that @w{latin-9}
4496 contains the Euro character. To use this encoding, either say
4497 @w{@samp{.mso latin9.tmac}} at the very beginning of your document or
4498 use @samp{-mlatin9} as a command line argument for @code{groff}.
4501 Note that it can happen that some input encoding characters are not
4502 available for a particular output device. For example, saying
4505 groff -Tlatin1 -mlatin9 ...
4509 will fail if you use the Euro character in the input. Usually, this
4510 limitation is present only for devices which have a limited set of
4511 output glyphs (e.g.@: @option{-Tascii} and @option{-Tlatin1}); for other
4512 devices it is usually sufficient to install proper fonts which contain
4513 the necessary glyphs.
4515 @pindex freeeuro.pfa
4517 Due to the importance of the Euro glyph in Europe, the groff package now
4518 comes with a @sc{PostScript} font called @file{freeeuro.pfa} which
4519 provides various glyph shapes for the Euro. With other words,
4520 @w{latin-9} encoding is supported for the @option{-Tps} device out of
4521 the box (@w{latin-2} isn't).
4523 By its very nature, @option{-Tutf8} supports all input encodings;
4524 @option{-Tdvi} has support for both @w{latin-2} and @w{latin-9} if the
4525 command line @option{-mec} is used also to load the file @file{ec.tmac}
4526 (which flips to the EC fonts).
4529 @c =====================================================================
4531 @node Measurements, Expressions, Text, gtroff Reference
4532 @section Measurements
4533 @cindex measurements
4535 @cindex units of measurement
4536 @cindex basic unit (@code{u})
4537 @cindex machine unit (@code{u})
4538 @cindex measurement unit
4539 @cindex @code{u} unit
4540 @cindex unit, @code{u}
4541 @code{gtroff} (like many other programs) requires numeric parameters to
4542 specify various measurements. Most numeric parameters@footnote{those
4543 that specify vertical or horizontal motion or a type size} may have a
4544 @dfn{measurement unit} attached. These units are specified as a single
4545 character which immediately follows the number or expression. Each of
4546 these units are understood, by @code{gtroff}, to be a multiple of its
4547 @dfn{basic unit}. So, whenever a different measurement unit is
4548 specified @code{gtroff} converts this into its @dfn{basic units}. This
4549 basic unit, represented by a @samp{u}, is a device dependent measurement
4550 which is quite small, ranging from 1/75@dmn{th} to 1/72000@dmn{th} of an
4551 inch. The values may be given as fractional numbers; however,
4552 fractional basic units are always rounded to integers.
4554 Some of the measurement units are completely independent of any of the
4555 current settings (e.g.@: type size) of @code{gtroff}.
4559 @cindex inch unit (@code{i})
4560 @cindex @code{i} unit
4561 @cindex unit, @code{i}
4562 Inches. An antiquated measurement unit still in use in certain
4563 backwards countries with incredibly low-cost computer equipment. One
4564 inch is equal to@tie{}2.54@dmn{cm}.
4567 @cindex centimeter unit (@code{c})
4568 @cindex @code{c} unit
4569 @cindex unit, @code{c}
4570 Centimeters. One centimeter is equal to@tie{}0.3937@dmn{in}.
4573 @cindex point unit (@code{p})
4574 @cindex @code{p} unit
4575 @cindex unit, @code{p}
4576 Points. This is a typesetter's measurement used for measure type size.
4577 It is 72@tie{}points to an inch.
4580 @cindex pica unit (@code{P})
4581 @cindex @code{P} unit
4582 @cindex unit, @code{P}
4583 Pica. Another typesetting measurement. 6@tie{}Picas to an inch (and
4584 12@tie{}points to a pica).
4588 @cindex @code{s} unit
4589 @cindex unit, @code{s}
4590 @cindex @code{z} unit
4591 @cindex unit, @code{z}
4592 @xref{Fractional Type Sizes}, for a discussion of these units.
4595 @cindex @code{f} unit
4596 @cindex unit, @code{f}
4597 Fractions. Value is 65536.
4598 @xref{Colors}, for usage.
4601 The other measurements understood by @code{gtroff} depend on
4602 settings currently in effect in @code{gtroff}. These are very useful
4603 for specifying measurements which should look proper with any size of
4608 @cindex em unit (@code{m})
4609 @cindex @code{m} unit
4610 @cindex unit, @code{m}
4611 Ems. This unit is equal to the current font size in points. So called
4612 because it is @emph{approximately} the width of the letter@tie{}@samp{m}
4613 in the current font.
4616 @cindex en unit (@code{n})
4617 @cindex @code{n} unit
4618 @cindex unit, @code{n}
4619 Ens. In @code{groff}, this is half of an em.
4622 @cindex vertical space unit (@code{v})
4623 @cindex space, vertical, unit (@code{v})
4624 @cindex @code{v} unit
4625 @cindex unit, @code{v}
4626 Vertical space. This is equivalent to the current line spacing.
4627 @xref{Sizes}, for more information about this.
4630 @cindex @code{M} unit
4631 @cindex unit, @code{M}
4639 @c ---------------------------------------------------------------------
4641 @node Default Units, , Measurements, Measurements
4642 @subsection Default Units
4643 @cindex default units
4644 @cindex units, default
4646 Many requests take a default unit. While this can be helpful at times,
4647 it can cause strange errors in some expressions. For example, the line
4648 length request expects em units. Here are several attempts to get a
4649 line length of 3.5@tie{}inches and their results:
4655 (7 / 2)u @result{} 0i
4657 7i/2u @result{} 3.5i
4661 Everything is converted to basic units first. In the above example it
4662 is assumed that 1@dmn{i} equals@tie{}240@dmn{u}, and 1@dmn{m}
4663 equals@tie{}10@dmn{p} (thus 1@dmn{m} equals@tie{}33@dmn{u}). The value
4664 7@dmn{i}/2 is first handled as 7@dmn{i}/2@dmn{m}, then converted to
4665 1680@dmn{u}/66@dmn{u} which is 25@dmn{u}, and this is approximately
4666 0.1@dmn{i}. As can be seen, a scaling indicator after a closing
4667 parenthesis is simply ignored.
4669 @cindex measurements, specifying safely
4670 Thus, the safest way to specify measurements is to always
4671 attach a scaling indicator. If you want to multiply or divide by a
4672 certain scalar value, use @samp{u} as the unit for that value.
4675 @c =====================================================================
4677 @node Expressions, Identifiers, Measurements, gtroff Reference
4678 @section Expressions
4681 @code{gtroff} has most arithmetic operators common to other languages:
4685 @cindex arithmetic operators
4686 @cindex operators, arithmetic
4692 Arithmetic: @samp{+} (addition), @samp{-} (subtraction), @samp{/}
4693 (division), @samp{*} (multiplication), @samp{%} (modulo).
4695 @code{gtroff} only provides integer arithmetic. The internal type used
4696 for computing results is @samp{int}, which is usually a 32@dmn{bit}
4700 @cindex comparison operators
4701 @cindex operators, comparison
4708 Comparison: @samp{<} (less than), @samp{>} (greater than), @samp{<=}
4709 (less than or equal), @samp{>=} (greater than or equal), @samp{=}
4710 (equal), @samp{==} (the same as @samp{=}).
4713 @cindex logical operators
4714 @cindex operators, logical
4720 @opindex @r{<colon>}
4722 Logical: @samp{&} (logical and), @samp{:} (logical or).
4725 @cindex unary operators
4726 @cindex operators, unary
4730 @cindex @code{if} request, and the @samp{!} operator
4731 @cindex @code{while} request, and the @samp{!} operator
4732 Unary operators: @samp{-} (negating, i.e.@: changing the sign), @samp{+}
4733 (just for completeness; does nothing in expressions), @samp{!} (logical
4734 not; this works only within @code{if} and @code{while} requests). See
4735 below for the use of unary operators in motion requests.
4738 @cindex extremum operators (@code{>?}, @code{<?})
4739 @cindex operators, extremum (@code{>?}, @code{<?})
4742 Extrema: @samp{>?} (maximum), @samp{<?} (minimum).
4749 .nr z (\n[x] >? \n[y])
4753 The register@tie{}@code{z} now contains@tie{}5.
4756 @cindex scaling operator
4757 @cindex operator, scaling
4758 Scaling: @code{(@var{c};@var{e})}. Evaluate@tie{}@var{e} using@tie{}@var{c}
4759 as the default scaling indicator. If @var{c} is missing, ignore scaling
4760 indicators in the evaluation of@tie{}@var{e}.
4764 @cindex order of evaluation in expressions
4765 @cindex expression, order of evaluation
4768 Parentheses may be used as in any other language. However, in
4769 @code{gtroff} they are necessary to ensure order of evaluation.
4770 @code{gtroff} has no operator precedence; expressions are evaluated left
4771 to right. This means that @code{gtroff} evaluates @samp{3+5*4} as if it were
4772 parenthesized like @samp{(3+5)*4}, not as @samp{3+(5*4)}, as might be
4775 @cindex @code{+}, and page motion
4776 @cindex @code{-}, and page motion
4777 @cindex motion operators
4778 @cindex operators, motion
4779 For many requests which cause a motion on the page, the unary operators
4780 @samp{+} and @samp{-} work differently if leading an expression. They
4781 then indicate a motion relative to the current position (down or up,
4784 @cindex @code{|}, and page motion
4785 @cindex absolute position operator (@code{|})
4786 @cindex position, absolute, operator (@code{|})
4787 Similarly, a leading @samp{|} operator indicates an absolute position.
4788 For vertical movements, it specifies the distance from the top of the
4789 page; for horizontal movements, it gives the distance from the beginning
4790 of the @emph{input} line.
4792 @cindex @code{bp} request, using @code{+} and@tie{}@code{-}
4793 @cindex @code{in} request, using @code{+} and@tie{}@code{-}
4794 @cindex @code{ll} request, using @code{+} and@tie{}@code{-}
4795 @cindex @code{lt} request, using @code{+} and@tie{}@code{-}
4796 @cindex @code{nm} request, using @code{+} and@tie{}@code{-}
4797 @cindex @code{nr} request, using @code{+} and@tie{}@code{-}
4798 @cindex @code{pl} request, using @code{+} and@tie{}@code{-}
4799 @cindex @code{pn} request, using @code{+} and@tie{}@code{-}
4800 @cindex @code{po} request, using @code{+} and@tie{}@code{-}
4801 @cindex @code{ps} request, using @code{+} and@tie{}@code{-}
4802 @cindex @code{pvs} request, using @code{+} and@tie{}@code{-}
4803 @cindex @code{rt} request, using @code{+} and@tie{}@code{-}
4804 @cindex @code{ti} request, using @code{+} and@tie{}@code{-}
4805 @cindex @code{\H}, using @code{+} and@tie{}@code{-}
4806 @cindex @code{\R}, using @code{+} and@tie{}@code{-}
4807 @cindex @code{\s}, using @code{+} and@tie{}@code{-}
4808 @samp{+} and @samp{-} are also treated differently by the following
4809 requests and escapes: @code{bp}, @code{in}, @code{ll}, @code{lt},
4810 @code{nm}, @code{nr}, @code{pl}, @code{pn}, @code{po}, @code{ps},
4811 @code{pvs}, @code{rt}, @code{ti}, @code{\H}, @code{\R}, and @code{\s}.
4812 Here, leading plus and minus signs indicate increments and decrements.
4814 @xref{Setting Registers}, for some examples.
4816 @Defesc {\\B, ', anything, '}
4817 @cindex numeric expression, valid
4818 @cindex valid numeric expression
4819 Return@tie{}1 if @var{anything} is a valid numeric expression;
4820 or@tie{}0 if @var{anything} is empty or not a valid numeric expression.
4823 @cindex space characters, in expressions
4824 @cindex expressions, and space characters
4825 Due to the way arguments are parsed, spaces are not allowed in
4826 expressions, unless the entire expression is surrounded by parentheses.
4828 @xref{Request and Macro Arguments}, and @ref{Conditionals and Loops}.
4831 @c =====================================================================
4833 @node Identifiers, Embedded Commands, Expressions, gtroff Reference
4834 @section Identifiers
4837 Like any other language, @code{gtroff} has rules for properly formed
4838 @dfn{identifiers}. In @code{gtroff}, an identifier can be made up of
4839 almost any printable character, with the exception of the following
4844 @cindex whitespace characters
4845 @cindex newline character
4846 @cindex character, whitespace
4847 Whitespace characters (spaces, tabs, and newlines).
4850 @cindex character, backspace
4851 @cindex backspace character
4852 @cindex @acronym{EBCDIC} encoding of backspace
4853 Backspace (@acronym{ASCII}@tie{}@code{0x08} or
4854 @acronym{EBCDIC}@tie{}@code{0x16}) and character code @code{0x01}.
4857 @cindex invalid input characters
4858 @cindex input characters, invalid
4859 @cindex characters, invalid input
4861 The following input characters are invalid and are ignored if
4862 @code{groff} runs on a machine based on @acronym{ASCII}, causing a
4863 warning message of type @samp{input} (see @ref{Debugging}, for more
4864 details): @code{0x00}, @code{0x0B}, @code{0x0D}-@code{0x1F},
4865 @code{0x80}-@code{0x9F}.
4867 And here are the invalid input characters if @code{groff} runs on an
4868 @acronym{EBCDIC} host: @code{0x00}, @code{0x08}, @code{0x09},
4869 @code{0x0B}, @code{0x0D}-@code{0x14}, @code{0x17}-@code{0x1F},
4870 @code{0x30}-@code{0x3F}.
4872 Currently, some of these reserved codepoints are used internally, thus
4873 making it non-trivial to extend @code{gtroff} to cover Unicode or other
4874 character sets and encodings which use characters of these ranges.
4876 Note that invalid characters are removed before parsing; an
4877 identifier @code{foo}, followed by an invalid character, followed by
4878 @code{bar} is treated as @code{foobar}.
4881 For example, any of the following is valid.
4891 @cindex @code{]}, as part of an identifier
4893 Note that identifiers longer than two characters with a closing bracket
4894 (@samp{]}) in its name can't be accessed with escape sequences which
4895 expect an identifier as a parameter. For example, @samp{\[foo]]}
4896 accesses the glyph @samp{foo}, followed by @samp{]}, whereas
4897 @samp{\C'foo]'} really asks for glyph @samp{foo]}.
4899 @cindex @code{refer}, and macro names starting with @code{[} or @code{]}
4900 @cindex @code{[}, macro names starting with, and @code{refer}
4901 @cindex @code{]}, macro names starting with, and @code{refer}
4902 @cindex macro names, starting with @code{[} or @code{]}, and @code{refer}
4903 To avoid problems with the @code{refer} preprocessor, macro names
4904 should not start with @samp{[} or @samp{]}. Due to backwards
4905 compatibility, everything after @samp{.[} and @samp{.]} is handled as
4906 a special argument to @code{refer}. For example, @samp{.[foo} makes
4907 @code{refer} to start a reference, using @samp{foo} as a parameter.
4909 @Defesc {\\A, ', ident, '}
4910 Test whether an identifier @var{ident} is valid in @code{gtroff}. It
4911 expands to the character@tie{}1 or@tie{}0 according to whether its
4912 argument (usually delimited by quotes) is or is not acceptable as the
4913 name of a string, macro, diversion, number register, environment, or
4914 font. It returns@tie{}0 if no argument is given. This is useful for
4915 looking up user input in some sort of associative table.
4923 @xref{Escapes}, for details on parameter delimiting characters.
4925 Identifiers in @code{gtroff} can be any length, but, in some contexts,
4926 @code{gtroff} needs to be told where identifiers end and text begins
4927 (and in different ways depending on their length):
4933 @cindex @code{(}, starting a two-character identifier
4935 Two characters. Must be prefixed with @samp{(} in some situations.
4937 @cindex @code{[}, starting an identifier
4938 @cindex @code{]}, ending an identifier
4940 Arbitrary length (@code{gtroff} only). Must be bracketed with @samp{[}
4941 and@tie{}@samp{]} in some situations. Any length identifier can be put
4945 @cindex undefined identifiers
4946 @cindex identifiers, undefined
4947 Unlike many other programming languages, undefined identifiers are
4948 silently ignored or expanded to nothing.
4949 When @code{gtroff} finds an undefined identifier, it emits a
4950 warning, doing the following:
4954 If the identifier is a string, macro, or diversion,
4955 @code{gtroff} defines it as empty.
4958 If the identifier is a number register, @code{gtroff}
4959 defines it with a value of@tie{}0.
4962 @xref{Warnings}., @ref{Interpolating Registers}, and @ref{Strings}.
4964 Note that macros, strings, and diversions share the same name space.
4981 As can be seen in the previous example, @code{gtroff} reuses the
4982 identifier @samp{xxx}, changing it from a macro to a diversion.
4983 No warning is emitted! The contents of the first macro definition is
4986 @xref{Interpolating Registers}, and @ref{Strings}.
4989 @c =====================================================================
4991 @node Embedded Commands, Registers, Identifiers, gtroff Reference
4992 @section Embedded Commands
4993 @cindex embedded commands
4994 @cindex commands, embedded
4996 Most documents need more functionality beyond filling, adjusting and
4997 implicit line breaking. In order to gain further functionality,
4998 @code{gtroff} allows commands to be embedded into the text, in two ways.
5000 The first is a @dfn{request} which takes up an entire line, and does
5001 some large-scale operation (e.g.@: break lines, start new pages).
5003 The other is an @dfn{escape} which can be usually embedded anywhere
5004 in the text; most requests can accept it even as an argument.
5005 Escapes generally do more minor operations like sub- and superscripts,
5006 print a symbol, etc.
5014 @c ---------------------------------------------------------------------
5016 @node Requests, Macros, Embedded Commands, Embedded Commands
5017 @subsection Requests
5020 @cindex control character (@code{.})
5021 @cindex character, control (@code{.})
5022 @cindex no-break control character (@code{'})
5023 @cindex character, no-break control (@code{'})
5024 @cindex control character, no-break (@code{'})
5025 A request line begins with a control character, which is either a single
5026 quote (@samp{'}, the @dfn{no-break control character}) or a period
5027 (@samp{.}, the normal @dfn{control character}). These can be changed;
5028 see @ref{Character Translations}, for details. After this there may be
5029 optional tabs or spaces followed by an identifier which is the name of
5030 the request. This may be followed by any number of space-separated
5031 arguments (@emph{no} tabs here).
5033 @cindex structuring source code of documents or macro packages
5034 @cindex documents, structuring the source code
5035 @cindex macro packages, structuring the source code
5036 Since a control character followed by whitespace only is ignored, it
5037 is common practice to use this feature for structuring the source code
5038 of documents or macro packages.
5052 @cindex blank line macro (@code{blm})
5053 Another possibility is to use the blank line macro request @code{blm}
5054 by assigning an empty macro to it.
5059 .blm do-nothing \" activate blank line macro
5070 .blm \" deactivate blank line macro
5073 @xref{Blank Line Traps}.
5075 @cindex zero width space character (@code{\&})
5076 @cindex character, zero width space (@code{\&})
5077 @cindex space character, zero width (@code{\&})
5078 @cindex @code{\&}, escaping control characters
5079 To begin a line with a control character without it being interpreted,
5080 precede it with @code{\&}. This represents a zero width space, which
5081 means it does not affect the output.
5083 In most cases the period is used as a control character. Several
5084 requests cause a break implicitly; using the single quote control
5085 character prevents this.
5088 * Request and Macro Arguments::
5091 @node Request and Macro Arguments, , Requests, Requests
5092 @subsubsection Request and Macro Arguments
5093 @cindex request arguments
5094 @cindex macro arguments
5095 @cindex arguments to requests and macros
5097 Arguments to requests and macros are processed much like the shell:
5098 The line is split into arguments according to
5099 spaces.@footnote{Plan@tie{}9's @code{troff} implementation also allows
5100 tabs for argument separation -- @code{gtroff} intentionally doesn't
5103 @cindex spaces, in a macro argument
5104 An argument to a macro which is intended to contain spaces can either be
5105 enclosed in double quotes, or have the spaces @dfn{escaped} with
5106 backslashes. This is @emph{not} true for requests.
5108 Here are a few examples for a hypothetical macro @code{uh}:
5111 .uh The Mouse Problem
5112 .uh "The Mouse Problem"
5113 .uh The\ Mouse\ Problem
5116 @cindex @code{\~}, difference to @code{\@key{SP}}
5117 @cindex @code{\@key{SP}}, difference to @code{\~}
5119 The first line is the @code{uh} macro being called with 3 arguments,
5120 @samp{The}, @samp{Mouse}, and @samp{Problem}. The latter two have the
5121 same effect of calling the @code{uh} macro with one argument, @samp{The
5122 Mouse Problem}.@footnote{The last solution, i.e., using escaped spaces,
5123 is ``classical'' in the sense that it can be found in most @code{troff}
5124 documents. Nevertheless, it is not optimal in all situations, since
5125 @w{@samp{\ }} inserts a fixed-width, non-breaking space character which
5126 can't stretch. @code{gtroff} provides a different command @code{\~} to
5127 insert a stretchable, non-breaking space.}
5129 @cindex @code{"}, in a macro argument
5130 @cindex double quote, in a macro argument
5131 A double quote which isn't preceded by a space doesn't start a macro
5132 argument. If not closing a string, it is printed literally.
5137 .xxx a" "b c" "de"fg"
5141 has the arguments @samp{a"}, @w{@samp{b c}}, @samp{de}, and @samp{fg"}.
5142 Don't rely on this obscure behaviour!
5144 There are two possibilities to get a double quote reliably.
5148 Enclose the whole argument with double quotes and use two consecutive double
5149 quotes to represent a single one. This traditional solution has the
5150 disadvantage that double quotes don't survive argument expansion again if
5151 called in compatibility mode (using the @option{-C} option of @code{groff}):
5155 . tm xx: `\\$1' `\\$2' `\\$3'
5157 . yy "\\$1" "\\$2" "\\$3"
5160 . tm yy: `\\$1' `\\$2' `\\$3'
5162 .xx A "test with ""quotes""" .
5163 @result{} xx: `A' `test with "quotes"' `.'
5164 @result{} yy: `A' `test with ' `quotes""'
5168 If not in compatibility mode, you get the expected result
5171 xx: `A' `test with "quotes"' `.'
5172 yy: `A' `test with "quotes"' `.'
5176 since @code{gtroff} preserves the input level.
5179 Use the double quote glyph @code{\(dq}. This works with and without
5180 compatibility mode enabled since @code{gtroff} doesn't convert @code{\(dq}
5181 back to a double quote input character.
5183 Not that this method won't work with @acronym{UNIX} @code{troff} in general
5184 since the glyph `dq' isn't defined normally.
5187 @cindex @code{ds} request, and double quotes
5188 Double quotes in the @code{ds} request are handled differently.
5189 @xref{Strings}, for more details.
5191 @c ---------------------------------------------------------------------
5193 @node Macros, Escapes, Requests, Embedded Commands
5197 @code{gtroff} has a @dfn{macro} facility for defining a series of lines
5198 which can be invoked by name. They are called in the same manner as
5199 requests -- arguments also may be passed basically in the same manner.
5201 @xref{Writing Macros}, and @ref{Request and Macro Arguments}.
5203 @c ---------------------------------------------------------------------
5205 @node Escapes, , Macros, Embedded Commands
5209 Escapes may occur anywhere in the input to @code{gtroff}. They usually
5210 begin with a backslash and are followed by a single character which
5211 indicates the function to be performed. The escape character can be
5212 changed; see @ref{Character Translations}.
5214 Escape sequences which require an identifier as a parameter accept three
5215 possible syntax forms.
5219 The next single character is the identifier.
5221 @cindex @code{(}, starting a two-character identifier
5223 If this single character is an opening parenthesis, take the following
5224 two characters as the identifier. Note that there is no closing
5225 parenthesis after the identifier.
5227 @cindex @code{[}, starting an identifier
5228 @cindex @code{]}, ending an identifier
5230 If this single character is an opening bracket, take all characters
5231 until a closing bracket as the identifier.
5243 @cindex @code{'}, delimiting arguments
5244 @cindex argument delimiting characters
5245 @cindex characters, argument delimiting
5246 @cindex delimiting characters for arguments
5247 Other escapes may require several arguments and/or some special format.
5248 In such cases the argument is traditionally enclosed in single quotes
5249 (and quotes are always used in this manual for the definitions of escape
5250 sequences). The enclosed text is then processed according to what that
5251 escape expects. Example:
5257 @cindex @code{\o}, possible quote characters
5258 @cindex @code{\b}, possible quote characters
5259 @cindex @code{\X}, possible quote characters
5260 Note that the quote character can be replaced with any other character
5261 which does not occur in the argument (even a newline or a space
5262 character) in the following escapes: @code{\o}, @code{\b}, and
5263 @code{\X}. This makes e.g.
5272 @result{} A caf@'e in Paris
5276 possible, but it is better not to use this feature to avoid confusion.
5278 @cindex @code{\%}, used as delimiter
5279 @cindex @code{\@key{SP}}, used as delimiter
5280 @cindex @code{\|}, used as delimiter
5281 @cindex @code{\^}, used as delimiter
5282 @cindex @code{\@{}, used as delimiter
5283 @cindex @code{\@}}, used as delimiter
5284 @cindex @code{\'}, used as delimiter
5285 @cindex @code{\`}, used as delimiter
5286 @cindex @code{\-}, used as delimiter
5287 @cindex @code{\_}, used as delimiter
5288 @cindex @code{\!}, used as delimiter
5289 @cindex @code{\?}, used as delimiter
5290 @cindex @code{\@@}, used as delimiter
5291 @cindex @code{\)}, used as delimiter
5292 @cindex @code{\/}, used as delimiter
5293 @cindex @code{\,}, used as delimiter
5294 @cindex @code{\&}, used as delimiter
5296 @cindex @code{\:}, used as delimiter
5299 @cindex @code{\@r{<colon>}}, used as delimiter
5301 @cindex @code{\~}, used as delimiter
5302 @cindex @code{\0}, used as delimiter
5303 @cindex @code{\a}, used as delimiter
5304 @cindex @code{\c}, used as delimiter
5305 @cindex @code{\d}, used as delimiter
5306 @cindex @code{\e}, used as delimiter
5307 @cindex @code{\E}, used as delimiter
5308 @cindex @code{\p}, used as delimiter
5309 @cindex @code{\r}, used as delimiter
5310 @cindex @code{\t}, used as delimiter
5311 @cindex @code{\u}, used as delimiter
5312 The following escapes sequences (which are handled similarly to
5313 characters since they don't take a parameter) are also allowed as
5314 delimiters: @code{\%}, @w{@samp{\ }}, @code{\|}, @code{\^}, @code{\@{},
5315 @code{\@}}, @code{\'}, @code{\`}, @code{\-}, @code{\_}, @code{\!},
5316 @code{\?}, @code{\@@}, @code{\)}, @code{\/}, @code{\,}, @code{\&},
5317 @code{\:}, @code{\~}, @code{\0}, @code{\a}, @code{\c}, @code{\d},
5318 @code{\e}, @code{\E}, @code{\p}, @code{\r}, @code{\t}, and @code{\u}.
5319 Again, don't use these if possible.
5321 @cindex @code{\A}, allowed delimiters
5322 @cindex @code{\B}, allowed delimiters
5323 @cindex @code{\Z}, allowed delimiters
5324 @cindex @code{\C}, allowed delimiters
5325 @cindex @code{\w}, allowed delimiters
5326 No newline characters as delimiters are allowed in the following
5327 escapes: @code{\A}, @code{\B}, @code{\Z}, @code{\C}, and @code{\w}.
5329 @cindex @code{\D}, allowed delimiters
5330 @cindex @code{\h}, allowed delimiters
5331 @cindex @code{\H}, allowed delimiters
5332 @cindex @code{\l}, allowed delimiters
5333 @cindex @code{\L}, allowed delimiters
5334 @cindex @code{\N}, allowed delimiters
5335 @cindex @code{\R}, allowed delimiters
5336 @cindex @code{\s}, allowed delimiters
5337 @cindex @code{\S}, allowed delimiters
5338 @cindex @code{\v}, allowed delimiters
5339 @cindex @code{\x}, allowed delimiters
5340 Finally, the escapes @code{\D}, @code{\h}, @code{\H}, @code{\l},
5341 @code{\L}, @code{\N}, @code{\R}, @code{\s}, @code{\S}, @code{\v},
5342 and @code{\x} can't use the following characters as delimiters:
5346 @cindex numbers, and delimiters
5347 @cindex digits, and delimiters
5348 The digits @code{0}-@code{9}.
5351 @cindex operators, as delimiters
5352 @cindex @code{+}, as delimiter
5353 @cindex @code{-}, as delimiter
5354 @cindex @code{/}, as delimiter
5355 @cindex @code{*}, as delimiter
5356 @cindex @code{%}, as delimiter
5357 @cindex @code{<}, as delimiter
5358 @cindex @code{>}, as delimiter
5359 @cindex @code{=}, as delimiter
5360 @cindex @code{&}, as delimiter
5362 @cindex @code{:}, as delimiter
5365 @cindex <colon>, as delimiter
5367 @cindex @code{(}, as delimiter
5368 @cindex @code{)}, as delimiter
5369 @cindex @code{.}, as delimiter
5370 The (single-character) operators @samp{+-/*%<>=&:().}.
5373 @cindex space character
5374 @cindex character, space
5375 @cindex tab character
5376 @cindex character, tab
5377 @cindex newline character
5378 @cindex character, newline
5379 The space, tab, and newline characters.
5382 @cindex @code{\%}, used as delimiter
5384 @cindex @code{\:}, used as delimiter
5387 @cindex @code{\@r{<colon>}}, used as delimiter
5389 @cindex @code{\@{}, used as delimiter
5390 @cindex @code{\@}}, used as delimiter
5391 @cindex @code{\'}, used as delimiter
5392 @cindex @code{\`}, used as delimiter
5393 @cindex @code{\-}, used as delimiter
5394 @cindex @code{\_}, used as delimiter
5395 @cindex @code{\!}, used as delimiter
5396 @cindex @code{\@@}, used as delimiter
5397 @cindex @code{\/}, used as delimiter
5398 @cindex @code{\c}, used as delimiter
5399 @cindex @code{\e}, used as delimiter
5400 @cindex @code{\p}, used as delimiter
5401 All escape sequences except @code{\%}, @code{\:}, @code{\@{}, @code{\@}},
5402 @code{\'}, @code{\`}, @code{\-}, @code{\_}, @code{\!}, @code{\@@},
5403 @code{\/}, @code{\c}, @code{\e}, and @code{\p}.
5406 @cindex printing backslash (@code{\\}, @code{\e}, @code{\E}, @code{\[rs]})
5407 @cindex backslash, printing (@code{\\}, @code{\e}, @code{\E}, @code{\[rs]})
5408 To have a backslash (actually, the current escape character) appear in the
5409 output several escapes are defined: @code{\\}, @code{\e} or @code{\E}.
5410 These are very similar, and only differ with respect to being used in
5411 macros or diversions. @xref{Character Translations}, for an exact
5412 description of those escapes.
5414 @xref{Implementation Differences}, @ref{Copy-in Mode}, and @ref{Diversions},
5415 @ref{Identifiers}, for more information.
5421 @node Comments, , Escapes, Escapes
5422 @subsubsection Comments
5425 Probably one of the most@footnote{Unfortunately, this is a lie. But
5426 hopefully future @code{gtroff} hackers will believe it @code{:-)}}
5427 common forms of escapes is the comment.
5430 Start a comment. Everything to the end of the input line is ignored.
5432 This may sound simple, but it can be tricky to keep the comments from
5433 interfering with the appearance of the final output.
5435 @cindex @code{ds}, @code{ds1} requests, and comments
5436 @cindex @code{as}, @code{as1} requests, and comments
5437 If the escape is to the right of some text or a request, that portion
5438 of the line is ignored, but the space leading up to it is noticed by
5439 @code{gtroff}. This only affects the @code{ds} and @code{as}
5440 request and its variants.
5442 @cindex tabs, before comments
5443 @cindex comments, lining up with tabs
5444 One possibly irritating idiosyncracy is that tabs must not be used to
5445 line up comments. Tabs are not treated as whitespace between the
5446 request and macro arguments.
5448 @cindex undefined request
5449 @cindex request, undefined
5450 A comment on a line by itself is treated as a blank line, because
5451 after eliminating the comment, that is all that remains:
5468 To avoid this, it is common to start the line with @code{.\"} which
5469 causes the line to be treated as an undefined request and thus ignored
5472 @cindex @code{'}, as a comment
5473 Another commenting scheme seen sometimes is three consecutive single
5474 quotes (@code{'''}) at the beginning of a line. This works, but
5475 @code{gtroff} gives a warning about an undefined macro (namely
5476 @code{''}), which is harmless, but irritating.
5480 To avoid all this, @code{gtroff} has a new comment mechanism using the
5481 @code{\#} escape. This escape works the same as @code{\"} except that
5482 the newline is also ignored:
5501 @Defreq {ig, [@Var{end}]}
5502 Ignore all input until @code{gtroff} encounters the macro named
5503 @code{.}@var{end} on a line by itself (or @code{..} if @var{end} is not
5504 specified). This is useful for commenting out large blocks of text:
5509 This is part of a large block
5510 of text that has been
5511 temporarily(?) commented out.
5513 We can restore it simply by removing
5514 the .ig request and the ".." at the
5517 More text text text...
5524 text text text@dots{} More text text text@dots{}
5528 Note that the commented-out block of text does not
5531 The input is read in copy-mode; auto-incremented registers @emph{are}
5532 affected (@pxref{Auto-increment}).
5536 @c =====================================================================
5538 @node Registers, Manipulating Filling and Adjusting, Embedded Commands, gtroff Reference
5542 Numeric variables in @code{gtroff} are called @dfn{registers}. There
5543 are a number of built-in registers, supplying anything from the date to
5544 details of formatting parameters.
5546 @xref{Identifiers}, for details on register identifiers.
5549 * Setting Registers::
5550 * Interpolating Registers::
5552 * Assigning Formats::
5553 * Built-in Registers::
5556 @c ---------------------------------------------------------------------
5558 @node Setting Registers, Interpolating Registers, Registers, Registers
5559 @subsection Setting Registers
5560 @cindex setting registers (@code{nr}, @code{\R})
5561 @cindex registers, setting (@code{nr}, @code{\R})
5563 Define or set registers using the @code{nr} request or the
5566 @DefreqList {nr, ident value}
5567 @DefescListEnd {\\R, ', ident value, '}
5568 Set number register @var{ident} to @var{value}. If @var{ident}
5569 doesn't exist, @code{gtroff} creates it.
5571 The argument to @code{\R} usually has to be enclosed in quotes.
5572 @xref{Escapes}, for details on parameter delimiting characters.
5574 The @code{\R} escape doesn't produce an input token in @code{gtroff};
5575 with other words, it vanishes completely after @code{gtroff} has
5579 For example, the following two lines are equivalent:
5582 .nr a (((17 + (3 * 4))) % 4)
5583 \R'a (((17 + (3 * 4))) % 4)'
5587 Both @code{nr} and @code{\R} have two additional special forms to
5588 increment or decrement a register.
5590 @DefreqList {nr, ident @t{+}@Var{value}}
5591 @DefreqItem {nr, ident @t{-}@Var{value}}
5592 @DefescItem {\\R, ', ident @t{+}value, '}
5593 @DefescListEnd {\\R, ', ident @t{-}value, '}
5594 Increment (decrement) register @var{ident} by @var{value}.
5603 @cindex negating register values
5604 To assign the negated value of a register to another register, some care
5605 must be taken to get the desired result:
5619 The surrounding parentheses prevent the interpretation of the minus sign
5620 as a decrementing operator. An alternative is to start the assignment
5636 @cindex removing number register (@code{rr})
5637 @cindex number register, removing (@code{rr})
5638 @cindex register, removing (@code{rr})
5639 Remove number register @var{ident}. If @var{ident} doesn't exist, the
5643 @Defreq {rnn, ident1 ident2}
5644 @cindex renaming number register (@code{rnn})
5645 @cindex number register, renaming (@code{rnn})
5646 @cindex register, renaming (@code{rnn})
5647 Rename number register @var{ident1} to @var{ident2}. If either
5648 @var{ident1} or @var{ident2} doesn't exist, the request is ignored.
5651 @Defreq {aln, ident1 ident2}
5652 @cindex alias, number register, creating (@code{aln})
5653 @cindex creating alias, for number register (@code{aln})
5654 @cindex number register, creating alias (@code{aln})
5655 @cindex register, creating alias (@code{aln})
5656 Create an alias @var{ident1} for a number register @var{ident2}. The
5657 new name and the old name are exactly equivalent. If @var{ident1} is
5658 undefined, a warning of type @samp{reg} is generated, and the request
5659 is ignored. @xref{Debugging}, for information about warnings.
5662 @c ---------------------------------------------------------------------
5664 @node Interpolating Registers, Auto-increment, Setting Registers, Registers
5665 @subsection Interpolating Registers
5666 @cindex interpolating registers (@code{\n})
5667 @cindex registers, interpolating (@code{\n})
5669 Numeric registers can be accessed via the @code{\n} escape.
5671 @DefescList {\\n, , i, }
5672 @DefescItem {\\n, @lparen{}, id, }
5673 @DefescListEnd {\\n, @lbrack{}, ident, @rbrack}
5674 @cindex nested assignments
5675 @cindex assignments, nested
5676 @cindex indirect assignments
5677 @cindex assignments, indirect
5678 Interpolate number register with name @var{ident} (one-character
5679 name@tie{}@var{i}, two-character name @var{id}). This means that the value
5680 of the register is expanded in-place while @code{gtroff} is parsing the
5681 input line. Nested assignments (also called indirect assignments) are
5703 @c ---------------------------------------------------------------------
5705 @node Auto-increment, Assigning Formats, Interpolating Registers, Registers
5706 @subsection Auto-increment
5707 @cindex auto-increment
5708 @cindex increment, automatic
5710 Number registers can also be auto-incremented and auto-decremented.
5711 The increment or decrement value can be specified with a third
5712 argument to the @code{nr} request or @code{\R} escape.
5714 @Defreq {nr, ident value incr}
5715 @cindex @code{\R}, difference to @code{nr}
5716 Set number register @var{ident} to @var{value}; the increment for
5717 auto-incrementing is set to @var{incr}. Note that the @code{\R}
5718 escape doesn't support this notation.
5721 To activate auto-incrementing, the escape @code{\n} has a special
5724 @DefescList {\\n, +, i, }
5725 @DefescItem {\\n, -, i, }
5726 @DefescItem {\\n, @lparen{}+, id, }
5727 @DefescItem {\\n, @lparen{}-, id, }
5728 @DefescItem {\\n, +@lparen{}, id, }
5729 @DefescItem {\\n, -@lparen{}, id, }
5730 @DefescItem {\\n, @lbrack{}+, ident, @rbrack{}}
5731 @DefescItem {\\n, @lbrack{}-, ident, @rbrack{}}
5732 @DefescItem {\\n, +@lbrack{}, ident, @rbrack{}}
5733 @DefescListEnd {\\n, -@lbrack{}, ident, @rbrack{}}
5734 Before interpolating, increment or decrement @var{ident}
5735 (one-character name@tie{}@var{i}, two-character name @var{id}) by the
5736 auto-increment value as specified with the @code{nr} request (or the
5737 @code{\R} escape). If no auto-increment value has been specified,
5738 these syntax forms are identical to @code{\n}.
5747 \n+a, \n+a, \n+a, \n+a, \n+a
5749 \n-(xx, \n-(xx, \n-(xx, \n-(xx, \n-(xx
5751 \n+[foo], \n+[foo], \n+[foo], \n+[foo], \n+[foo]
5759 -5, -10, -15, -20, -25
5763 @cindex increment value without changing the register
5764 @cindex value, incrementing without changing the register
5765 To change the increment value without changing the value of a register
5766 (@var{a} in the example), the following can be used:
5772 @c ---------------------------------------------------------------------
5774 @node Assigning Formats, Built-in Registers, Auto-increment, Registers
5775 @subsection Assigning Formats
5776 @cindex assigning formats (@code{af})
5777 @cindex formats, assigning (@code{af})
5779 When a register is used in the text of an input file (as opposed to
5780 part of an expression), it is textually replaced (or interpolated)
5781 with a representation of that number. This output format can be
5782 changed to a variety of formats (numbers, Roman numerals, etc.). This
5783 is done using the @code{af} request.
5785 @Defreq {af, ident format}
5786 Change the output format of a number register. The first argument
5787 @var{ident} is the name of the number register to be changed, and the
5788 second argument @var{format} is the output format. The following
5789 output formats are available:
5793 Decimal arabic numbers. This is the default format: 0, 1, 2,
5797 Decimal numbers with as many digits as specified. So, @samp{00} would
5798 result in printing numbers as 01, 02, 03,@tie{}@enddots{}
5800 In fact, any digit instead of zero will do; @code{gtroff} only counts
5801 how many digits are specified. As a consequence, @code{af}'s default
5802 format @samp{1} could be specified as @samp{0} also (and exactly this is
5803 returned by the @code{\g} escape, see below).
5806 @cindex Roman numerals
5807 @cindex numerals, Roman
5808 Upper-case Roman numerals: 0, I, II, III, IV,@tie{}@enddots{}
5811 Lower-case Roman numerals: 0, i, ii, iii, iv,@tie{}@enddots{}
5814 Upper-case letters: 0, A, B, C, @dots{},@tie{}Z, AA, AB,@tie{}@enddots{}
5817 Lower-case letters: 0, a, b, c, @dots{},@tie{}z, aa, ab,@tie{}@enddots{}
5820 Omitting the number register format causes a warning of type
5821 @samp{missing}. @xref{Debugging}, for more details. Specifying a
5822 nonexistent format causes an error.
5824 The following example produces @samp{10, X, j, 010}:
5828 .af a 1 \" the default format
5838 @cindex Roman numerals, maximum and minimum
5839 @cindex maximum values of Roman numerals
5840 @cindex minimum values of Roman numerals
5841 The largest number representable for the @samp{i} and @samp{I} formats
5842 is 39999 (or @minus{}39999); @acronym{UNIX} @code{troff} uses @samp{z}
5843 and @samp{w} to represent 10000 and 5000 in Roman numerals, and so does
5844 @code{gtroff}. Currently, the correct glyphs of Roman numeral five
5845 thousand and Roman numeral ten thousand (Unicode code points
5846 @code{U+2182} and @code{U+2181}, respectively) are not available.
5848 If @var{ident} doesn't exist, it is created.
5850 @cindex read-only register, changing format
5851 @cindex changing format, and read-only registers
5852 Changing the output format of a read-only register causes an error. It
5853 is necessary to first copy the register's value to a writeable register,
5854 then apply the @code{af} request to this other register.
5857 @DefescList {\\g, , i, }
5858 @DefescItem {\\g, @lparen{}, id, }
5859 @DefescListEnd {\\g, @lbrack{}, ident, @rbrack{}}
5860 @cindex format of register (@code{\g})
5861 @cindex register, format (@code{\g})
5862 Return the current format of the specified register @var{ident}
5863 (one-character name@tie{}@var{i}, two-character name @var{id}). For
5864 example, @samp{\ga} after the previous example would produce the
5865 string @samp{000}. If the register hasn't been defined yet, nothing
5869 @c ---------------------------------------------------------------------
5871 @node Built-in Registers, , Assigning Formats, Registers
5872 @subsection Built-in Registers
5873 @cindex built-in registers
5874 @cindex registers, built-in
5876 The following lists some built-in registers which are not described
5877 elsewhere in this manual. Any register which begins with a @samp{.} is
5878 read-only. A complete listing of all built-in registers can be found in
5879 appendix@tie{}@ref{Register Index}.
5883 @cindex current input file name register (@code{.F})
5884 @cindex input file name, current, register (@code{.F})
5886 This string-valued register returns the current input file name.
5889 @cindex horizontal resolution register (@code{.H})
5890 @cindex resolution, horizontal, register (@code{.H})
5892 Horizontal resolution in basic units.
5895 @cindex vertical resolution register (@code{.V})
5896 @cindex resolution, vertical, register (@code{.V})
5898 Vertical resolution in basic units.
5901 @cindex seconds, current time (@code{seconds})
5902 @cindex time, current, seconds (@code{seconds})
5903 @cindex current time, seconds (@code{seconds})
5905 The number of seconds after the minute, normally in the range@tie{}0
5906 to@tie{}59, but can be up to@tie{}61 to allow for leap seconds. Initialized
5907 at start-up of @code{gtroff}.
5910 @cindex minutes, current time (@code{minutes})
5911 @cindex time, current, minutes (@code{minutes})
5912 @cindex current time, minutes (@code{minutes})
5914 The number of minutes after the hour, in the range@tie{}0 to@tie{}59.
5915 Initialized at start-up of @code{gtroff}.
5918 @cindex hours, current time (@code{hours})
5919 @cindex time, current, hours (@code{hours})
5920 @cindex current time, hours (@code{hours})
5922 The number of hours past midnight, in the range@tie{}0 to@tie{}23.
5923 Initialized at start-up of @code{gtroff}.
5926 @cindex day of the week register (@code{dw})
5927 @cindex date, day of the week register (@code{dw})
5929 Day of the week (1-7).
5932 @cindex day of the month register (@code{dy})
5933 @cindex date, day of the month register (@code{dy})
5935 Day of the month (1-31).
5938 @cindex month of the year register (@code{mo})
5939 @cindex date, month of the year register (@code{mo})
5941 Current month (1-12).
5944 @cindex date, year register (@code{year}, @code{yr})
5945 @cindex year, current, register (@code{year}, @code{yr})
5951 The current year minus@tie{}1900. Unfortunately, the documentation of
5952 @acronym{UNIX} Version@tie{}7's @code{troff} had a year@tie{}2000 bug: It
5953 incorrectly claimed that @code{yr} contains the last two digits of the
5954 year. That claim has never been true of either @acronym{AT&T}
5955 @code{troff} or GNU @code{troff}. Old @code{troff} input that looks
5959 '\" The following line stopped working after 1999
5960 This document was formatted in 19\n(yr.
5964 can be corrected as follows:
5967 This document was formatted in \n[year].
5971 or, to be portable to older @code{troff} versions, as follows:
5975 This document was formatted in \n(y4.
5982 @cindex input line number register (@code{.c}, @code{c.})
5983 @cindex line number, input, register (@code{.c}, @code{c.})
5984 The current @emph{input} line number. Register @samp{.c} is read-only,
5985 whereas @samp{c.} (a @code{gtroff} extension) is writable also,
5986 affecting both @samp{.c} and @samp{c.}.
5990 @cindex output line number register (@code{ln})
5991 @cindex line number, output, register (@code{ln})
5992 The current @emph{output} line number after a call to the @code{nm}
5993 request to activate line numbering.
5995 @xref{Miscellaneous}, for more information about line numbering.
5999 @cindex major version number register (@code{.x})
6000 @cindex version number, major, register (@code{.x})
6001 The major version number. For example, if the version number
6002 is 1.03 then @code{.x} contains@tie{}@samp{1}.
6006 @cindex minor version number register (@code{.y})
6007 @cindex version number, minor, register (@code{.y})
6008 The minor version number. For example, if the version number
6009 is 1.03 then @code{.y} contains@tie{}@samp{03}.
6013 @cindex revision number register (@code{.Y})
6014 The revision number of @code{groff}.
6018 @cindex process ID of @code{gtroff} register (@code{$$})
6019 @cindex @code{gtroff}, process ID register (@code{$$})
6020 The process ID of @code{gtroff}.
6024 @cindex @code{gtroff}, identification register (@code{.g})
6025 @cindex GNU-specific register (@code{.g})
6026 Always@tie{}1. Macros should use this to determine whether they are
6027 running under GNU @code{troff}.
6031 @cindex @acronym{ASCII} approximation output register (@code{.A})
6032 If the command line option @option{-a} is used to produce an
6033 @acronym{ASCII} approximation of the output, this is set to@tie{}1, zero
6034 otherwise. @xref{Groff Options}.
6038 This register is set to@tie{}1 (and to@tie{}0 otherwise) if the current
6039 page is actually being printed, i.e., if the @option{-o} option is being
6040 used to only print selected pages. @xref{Groff Options}, for more
6045 If @code{gtroff} is called with the @option{-T} command line option, the
6046 number register @code{.T} is set to@tie{}1, and zero otherwise.
6047 @xref{Groff Options}.
6050 @cindex output device name string register (@code{.T})
6051 Additionally, @code{gtroff} predefines a single read-write string
6052 register @code{.T} which contains the current output device (for
6053 example, @samp{latin1} or @samp{ps}).
6057 @c =====================================================================
6059 @node Manipulating Filling and Adjusting, Manipulating Hyphenation, Registers, gtroff Reference
6060 @section Manipulating Filling and Adjusting
6061 @cindex manipulating filling and adjusting
6062 @cindex filling and adjusting, manipulating
6063 @cindex adjusting and filling, manipulating
6064 @cindex justifying text
6065 @cindex text, justifying
6069 @cindex @code{bp} request, causing implicit linebreak
6070 @cindex @code{ce} request, causing implicit linebreak
6071 @cindex @code{cf} request, causing implicit linebreak
6072 @cindex @code{fi} request, causing implicit linebreak
6073 @cindex @code{fl} request, causing implicit linebreak
6074 @cindex @code{in} request, causing implicit linebreak
6075 @cindex @code{nf} request, causing implicit linebreak
6076 @cindex @code{rj} request, causing implicit linebreak
6077 @cindex @code{sp} request, causing implicit linebreak
6078 @cindex @code{ti} request, causing implicit linebreak
6079 @cindex @code{trf} request, causing implicit linebreak
6080 Various ways of causing @dfn{breaks} were given in @ref{Implicit Line
6081 Breaks}. The @code{br} request likewise causes a break. Several
6082 other requests also cause breaks, but implicitly. These are
6083 @code{bp}, @code{ce}, @code{cf}, @code{fi}, @code{fl}, @code{in},
6084 @code{nf}, @code{rj}, @code{sp}, @code{ti}, and @code{trf}.
6087 Break the current line, i.e., the input collected so far is emitted
6090 If the no-break control character is used, @code{gtroff} suppresses
6101 Initially, @code{gtroff} fills and adjusts text to both margins.
6102 Filling can be disabled via the @code{nf} request and re-enabled with
6103 the @code{fi} request.
6107 @cindex fill mode (@code{fi})
6108 @cindex mode, fill (@code{fi})
6109 Activate fill mode (which is the default). This request implicitly
6110 enables adjusting; it also inserts a break in the text currently being
6111 filled. The read-only number register @code{.u} is set to@tie{}1.
6113 The fill mode status is associated with the current environment
6114 (@pxref{Environments}).
6116 See @ref{Line Control}, for interaction with the @code{\c} escape.
6120 @cindex no-fill mode (@code{nf})
6121 @cindex mode, no-fill (@code{nf})
6122 Activate no-fill mode. Input lines are output as-is, retaining line
6123 breaks and ignoring the current line length. This command implicitly
6124 disables adjusting; it also causes a break. The number register
6125 @code{.u} is set to@tie{}0.
6127 The fill mode status is associated with the current environment
6128 (@pxref{Environments}).
6130 See @ref{Line Control}, for interaction with the @code{\c} escape.
6133 @DefreqList {ad, [@Var{mode}]}
6137 Activation and deactivation of adjusting is done implicitly with
6138 calls to the @code{fi} or @code{nf} requests.
6140 @var{mode} can have one of the following values:
6144 @cindex ragged-right
6145 Adjust text to the left margin. This produces what is traditionally
6146 called ragged-right text.
6150 Adjust text to the right margin, producing ragged-left text.
6153 @cindex centered text
6154 @cindex @code{ce} request, difference to @samp{.ad@tie{}c}
6155 Center filled text. This is different to the @code{ce} request which
6156 only centers text without filling.
6160 Justify to both margins. This is the default used by @code{gtroff}.
6163 Finally, @var{mode} can be the numeric argument returned by the @code{.j}
6166 With no argument, @code{gtroff} adjusts lines in the same way it did
6167 before adjusting was deactivated (with a call to @code{na}, for
6179 .ad \" back to centering
6181 .ad \n[ad] \" back to right justifying
6184 @cindex adjustment mode register (@code{.j})
6185 The current adjustment mode is available in the read-only number
6186 register @code{.j}; it can be stored and subsequently used to set
6189 The adjustment mode status is associated with the current environment
6190 (@pxref{Environments}).
6194 Disable adjusting. This request won't change the current adjustment
6195 mode: A subsequent call to @code{ad} uses the previous adjustment
6198 The adjustment mode status is associated with the current environment
6199 (@pxref{Environments}).
6203 @DefescListEnd {\\p, , , }
6204 Adjust the current line and cause a break.
6206 In most cases this produces very ugly results since @code{gtroff}
6207 doesn't have a sophisticated paragraph building algorithm (as @TeX{}
6208 have, for example); instead, @code{gtroff} fills and adjusts a paragraph
6212 This is an uninteresting sentence.
6213 This is an uninteresting sentence.\p
6214 This is an uninteresting sentence.
6221 This is an uninteresting sentence. This is an
6222 uninteresting sentence.
6223 This is an uninteresting sentence.
6227 @DefreqList {ss, word_space_size [@Var{sentence_space_size}]}
6229 @DefregListEnd {.sss}
6230 @cindex word space size register (@code{.ss})
6231 @cindex size of word space register (@code{.ss})
6232 @cindex space between words register (@code{.ss})
6233 @cindex sentence space size register (@code{.sss})
6234 @cindex size of sentence space register (@code{.sss})
6235 @cindex space between sentences register (@code{.sss})
6236 Change the size of a space between words. It takes its units as one
6237 twelfth of the space width parameter for the current font.
6238 Initially both the @var{word_space_size} and @var{sentence_space_size}
6239 are@tie{}12. In fill mode, the values specify the minimum distance.
6243 If two arguments are given to the @code{ss} request, the second
6244 argument sets the sentence space size. If the second argument is not
6245 given, sentence space size is set to @var{word_space_size}. The
6246 sentence space size is used in two circumstances: If the end of a
6247 sentence occurs at the end of a line in fill mode, then both an
6248 inter-word space and a sentence space are added; if two spaces follow
6249 the end of a sentence in the middle of a line, then the second space
6250 is a sentence space. If a second argument is never given to the
6251 @code{ss} request, the behaviour of @acronym{UNIX} @code{troff} is the
6252 same as that exhibited by GNU @code{troff}. In GNU @code{troff}, as
6253 in @acronym{UNIX} @code{troff}, a sentence should always be followed
6254 by either a newline or two spaces.
6256 The read-only number registers @code{.ss} and @code{.sss} hold the
6257 values of the parameters set by the first and second arguments of the
6260 The word space and sentence space values are associated with the current
6261 environment (@pxref{Environments}).
6263 Contrary to @acronym{AT&T} @code{troff}, this request is @emph{not}
6264 ignored if a TTY output device is used; the given values are then
6265 rounded down to a multiple of@tie{}12 (@pxref{Implementation Differences}).
6267 The request is ignored if there is no parameter.
6269 @cindex discardable horizontal space
6270 @cindex space, discardable, horizontal
6271 @cindex horizontal discardable space
6272 Another useful application of the @code{ss} request is to insert
6273 discardable horizontal space, i.e., space which is discarded at a line
6274 break. For example, paragraph-style footnotes could be separated this
6279 1.\ This is the first footnote.\c
6283 2.\ This is the second footnote.
6290 1. This is the first footnote. 2. This
6291 is the second footnote.
6295 Note that the @code{\h} escape produces unbreakable space.
6298 @DefreqList {ce, [@Var{nnn}]}
6299 @DefregListEnd {.ce}
6300 @cindex centering lines (@code{ce})
6301 @cindex lines, centering (@code{ce})
6302 Center text. While the @w{@samp{.ad c}} request also centers text,
6303 it fills the text as well. @code{ce} does not fill the
6304 text it affects. This request causes a break. The number of lines
6305 still to be centered is associated with the current environment
6306 (@pxref{Environments}).
6308 The following example demonstrates the differences.
6314 This is a small text fragment which shows the differences
6315 between the `.ce' and the `.ad c' request.
6319 This is a small text fragment which shows the differences
6320 between the `.ce' and the `.ad c' request.
6324 And here the result:
6327 This is a small text fragment which
6328 shows the differences
6329 between the `.ce' and the `.ad c' request.
6331 This is a small text fragment which
6332 shows the differences between the `.ce'
6333 and the `.ad c' request.
6336 With no arguments, @code{ce} centers the next line of text. @var{nnn}
6337 specifies the number of lines to be centered. If the argument is zero
6338 or negative, centering is disabled.
6340 The basic length for centering text is the line length (as set with the
6341 @code{ll} request) minus the indentation (as set with the @code{in}
6342 request). Temporary indentation is ignored.
6344 As can be seen in the previous example, it is a common idiom to turn
6345 on centering for a large number of lines, and to turn off centering
6346 after text to be centered. This is useful for any request which takes
6347 a number of lines as an argument.
6349 The @code{.ce} read-only number register contains the number of lines
6350 remaining to be centered, as set by the @code{ce} request.
6353 @DefreqList {rj, [@Var{nnn}]}
6354 @DefregListEnd {.rj}
6355 @cindex justifying text (@code{rj})
6356 @cindex text, justifying (@code{rj})
6357 @cindex right-justifying (@code{rj})
6358 Justify unfilled text to the right margin. Arguments are identical to
6359 the @code{ce} request. The @code{.rj} read-only number register is
6360 the number of lines to be right-justified as set by the @code{rj}
6361 request. This request causes a break. The number of lines still to be
6362 right-justified is associated with the current environment
6363 (@pxref{Environments}).
6367 @c =====================================================================
6369 @node Manipulating Hyphenation, Manipulating Spacing, Manipulating Filling and Adjusting, gtroff Reference
6370 @section Manipulating Hyphenation
6371 @cindex manipulating hyphenation
6372 @cindex hyphenation, manipulating
6374 As discussed in @ref{Hyphenation}, @code{gtroff} hyphenates words.
6375 There are a number of ways to influence hyphenation.
6377 @DefreqList {hy, [@Var{mode}]}
6378 @DefregListEnd {.hy}
6379 Enable hyphenation. The request has an optional numeric argument,
6380 @var{mode}, to restrict hyphenation if necessary:
6384 The default argument if @var{mode} is omitted. Hyphenate without
6385 restrictions. This is also the start-up value of @code{gtroff}.
6388 Do not hyphenate the last word on a page or column.
6391 Do not hyphenate the last two characters of a word.
6394 Do not hyphenate the first two characters of a word.
6397 Values in the previous table are additive. For example, the
6398 value@tie{}12 causes @code{gtroff} to neither hyphenate the last
6399 two nor the first two characters of a word.
6401 @cindex hyphenation restrictions register (@code{.hy})
6402 The current hyphenation restrictions can be found in the read-only
6403 number register @samp{.hy}.
6405 The hyphenation mode is associated with the current environment
6406 (@pxref{Environments}).
6410 Disable hyphenation (i.e., set the hyphenation mode to zero). Note
6411 that the hyphenation mode of the last call to @code{hy} is not
6414 The hyphenation mode is associated with the current environment
6415 (@pxref{Environments}).
6418 @DefreqList {hlm, [@Var{nnn}]}
6420 @DefregListEnd {.hlc}
6421 @cindex explicit hyphen (@code{\%})
6422 @cindex hyphen, explicit (@code{\%})
6423 @cindex consecutive hyphenated lines (@code{hlm})
6424 @cindex lines, consecutive hyphenated (@code{hlm})
6425 @cindex hyphenated lines, consecutive (@code{hlm})
6426 Set the maximum number of consecutive hyphenated lines to @var{nnn}.
6427 If this number is negative, there is no maximum. The default value
6428 is@tie{}@minus{}1 if @var{nnn} is omitted. This value is associated
6429 with the current environment (@pxref{Environments}). Only lines
6430 output from a given environment count towards the maximum associated
6431 with that environment. Hyphens resulting from @code{\%} are counted;
6432 explicit hyphens are not.
6434 The current setting of @code{hlm} is available in the @code{.hlm}
6435 read-only number register. Also the number of immediately preceding
6436 consecutive hyphenated lines are available in the read-only number
6437 register @samp{.hlc}.
6440 @Defreq {hw, word1 word2 @dots{}}
6441 Define how @var{word1}, @var{word2}, etc.@: are to be hyphenated. The
6442 words must be given with hyphens at the hyphenation points. For
6450 Besides the space character, any character whose hyphenation code value
6451 is zero can be used to separate the arguments of @code{hw} (see the
6452 documentation for the @code{hcode} request below for more information).
6453 In addition, this request can be used more than once.
6455 Hyphenation exceptions specified with the @code{hw} request are
6456 associated with the current hyphenation language; it causes an error
6457 if there is no current hyphenation language.
6459 This request is ignored if there is no parameter.
6461 In old versions of @code{troff} there was a limited amount of space to
6462 store such information; fortunately, with @code{gtroff}, this is no
6463 longer a restriction.
6466 @DefescList {\\%, , , }
6467 @deffnx Escape @t{\:}
6472 @esindex \@r{<colon>}
6474 @cindex hyphenation character (@code{\%})
6475 @cindex character, hyphenation (@code{\%})
6476 @cindex disabling hyphenation (@code{\%})
6477 @cindex hyphenation, disabling (@code{\%})
6478 To tell @code{gtroff} how to hyphenate words on the fly, use the
6479 @code{\%} escape, also known as the @dfn{hyphenation character}.
6480 Preceding a word with this character prevents it from being
6481 hyphenated; putting it inside a word indicates to @code{gtroff} that
6482 the word may be hyphenated at that point. Note that this mechanism
6483 only affects that one occurrence of the word; to change the
6484 hyphenation of a word for the entire document, use the @code{hw}
6487 The @code{\:} escape inserts a zero-width break point
6488 (that is, the word breaks but without adding a hyphen).
6491 ... check the /var/log/\:httpd/\:access_log file ...
6494 @cindex @code{\X}, followed by @code{\%}
6495 @cindex @code{\Y}, followed by @code{\%}
6496 @cindex @code{\%}, following @code{\X} or @code{\Y}
6497 Note that @code{\X} and @code{\Y} start a word, that is, the @code{\%}
6498 escape in (say) @w{@samp{\X'...'\%foobar}} and
6499 @w{@samp{\Y'...'\%foobar}} no longer prevents hyphenation but inserts
6500 a hyphenation point at the beginning of @samp{foobar}; most likely
6501 this isn't what you want to do.
6504 @Defreq {hc, [@Var{char}]}
6505 Change the hyphenation character to @var{char}. This character then
6506 works the same as the @code{\%} escape, and thus, no longer appears in
6507 the output. Without an argument, @code{hc} resets the hyphenation
6508 character to be @code{\%} (the default) only.
6510 The hyphenation character is associated with the current environment
6511 (@pxref{Environments}).
6514 @DefreqList {hpf, pattern_file}
6515 @DefreqItem {hpfa, pattern_file}
6516 @DefreqListEnd {hpfcode, a b [c d @dots{}]}
6517 @cindex hyphenation patterns (@code{hpf})
6518 @cindex patterns for hyphenation (@code{hpf})
6519 Read in a file of hyphenation patterns. This file is searched for in
6520 the same way as @file{@var{name}.tmac} (or @file{tmac.@var{name}}) is
6521 searched for if the @option{-m@var{name}} option is specified.
6523 It should have the same format as (simple) @TeX{} patterns files.
6524 More specifically, the following scanning rules are implemented.
6528 A percent sign starts a comment (up to the end of the line)
6529 even if preceded by a backslash.
6532 No support for `digraphs' like @code{\$}.
6535 @code{^^@var{xx}} (@var{x} is 0-9 or a-f) and @code{^^@var{x}} (character
6536 code of @var{x} in the range 0-127) are recognized; other use of @code{^}
6543 @code{hpf} checks for the expression @code{\patterns@{@dots{}@}}
6544 (possibly with whitespace before and after the braces).
6545 Everything between the braces is taken as hyphenation patterns.
6546 Consequently, @code{@{} and @code{@}} are not allowed in patterns.
6549 Similarly, @code{\hyphenation@{@dots{}@}} gives a list of hyphenation
6553 @code{\endinput} is recognized also.
6556 For backwards compatibility, if @code{\patterns} is missing,
6557 the whole file is treated as a list of hyphenation patterns
6558 (only recognizing the @code{%} character as the start of a comment).
6561 If no @code{hpf} request is specified (either in the document or in a
6562 macro package), @code{gtroff} won't hyphenate at all.
6564 The @code{hpfa} request appends a file of patterns to the current list.
6566 The @code{hpfcode} request defines mapping values for character codes in
6567 hyphenation patterns. @code{hpf} or @code{hpfa} then apply the mapping
6568 (after reading the patterns) before replacing or appending them to
6569 the current list of patterns. Its arguments are pairs of character codes
6570 -- integers from 0 to@tie{}255. The request maps character code@tie{}@var{a}
6571 to code@tie{}@var{b}, code@tie{}@var{c} to code@tie{}@var{d}, and so on. You
6572 can use character codes which would be invalid otherwise.
6578 The set of hyphenation patterns is associated with the current language
6579 set by the @code{hla} request. The @code{hpf} request is usually
6580 invoked by the @file{troffrc} or @file{troffrc-end} file; by default,
6581 @file{troffrc} loads hyphenation patterns and exceptions for American
6582 English (in files @file{hyphen.us} and @file{hyphenex.us}).
6584 A second call to @code{hpf} (for the same language) will replace the
6585 hyphenation patterns with the new ones.
6587 Invoking @code{hpf} causes an error if there is no current hyphenation
6591 @Defreq {hcode, c1 code1 c2 code2 @dots{}}
6592 @cindex hyphenation code (@code{hcode})
6593 @cindex code, hyphenation (@code{hcode})
6594 Set the hyphenation code of character @var{c1} to @var{code1}, that of
6595 @var{c2} to @var{code2}, etc. A hyphenation code must be a single
6596 input character (not a special character) other than a digit or a
6597 space. Initially each lower-case letter (@samp{a}-@samp{z}) has its
6598 hyphenation code set to itself, and each upper-case letter
6599 (@samp{A}-@samp{Z}) has a hyphenation code which is the lower-case
6602 This request is ignored if it has no parameter.
6605 @DefreqList {hym, [@Var{length}]}
6606 @DefregListEnd {.hym}
6607 @cindex hyphenation margin (@code{hym})
6608 @cindex margin for hyphenation (@code{hym})
6609 @cindex @code{ad} request, and hyphenation margin
6610 Set the (right) hyphenation margin to @var{length}. If the current
6611 adjustment mode is not @samp{b} or @samp{n}, the line is not
6612 hyphenated if it is shorter than @var{length}. Without an argument,
6613 the hyphenation margin is reset to its default value, which is@tie{}0.
6614 The default scaling indicator for this request is @samp{m}. The
6615 hyphenation margin is associated with the current environment
6616 (@pxref{Environments}).
6618 A negative argument resets the hyphenation margin to zero, emitting
6619 a warning of type @samp{range}.
6621 @cindex hyphenation margin register (@code{.hym})
6622 The current hyphenation margin is available in the @code{.hym} read-only
6626 @DefreqList {hys, [@Var{hyphenation_space}]}
6627 @DefregListEnd {.hys}
6628 @cindex hyphenation space (@code{hys})
6629 @cindex @code{ad} request, and hyphenation space
6630 Set the hyphenation space to @var{hyphenation_space}. If the current
6631 adjustment mode is @samp{b} or @samp{n}, don't hyphenate the line
6632 if it can be justified by adding no more than @var{hyphenation_space}
6633 extra space to each word space. Without argument, the hyphenation
6634 space is set to its default value, which is@tie{}0. The default
6635 scaling indicator for this request is @samp{m}. The hyphenation
6636 space is associated with the current environment
6637 (@pxref{Environments}).
6639 A negative argument resets the hyphenation space to zero, emitting a
6640 warning of type @samp{range}.
6642 @cindex hyphenation space register (@code{.hys})
6643 The current hyphenation space is available in the @code{.hys} read-only
6647 @Defreq {shc, [@Var{glyph}]}
6648 @cindex soft hyphen character, setting (@code{shc})
6649 @cindex character, soft hyphen, setting (@code{shc})
6650 @cindex glyph, soft hyphen (@code{hy})
6651 @cindex soft hyphen glyph (@code{hy})
6652 @cindex @code{char} request, and soft hyphen character
6653 @cindex @code{tr} request, and soft hyphen character
6654 Set the @dfn{soft hyphen character} to @var{glyph}.@footnote{@dfn{Soft
6655 hyphen character} is a misnomer since it is an output glyph.} If the
6656 argument is omitted, the soft hyphen character is set to the default
6657 glyph @code{\(hy} (this is the start-up value of @code{gtroff} also).
6658 The soft hyphen character is the glyph that is inserted when a word is
6659 hyphenated at a line break. If the soft hyphen character does not
6660 exist in the font of the character immediately preceding a potential
6661 break point, then the line is not broken at that point. Neither
6662 definitions (specified with the @code{char} request) nor translations
6663 (specified with the @code{tr} request) are considered when finding the
6664 soft hyphen character.
6667 @DefreqList {hla, language}
6668 @DefregListEnd {.hla}
6669 @cindex @code{hpf} request, and hyphenation language
6670 @cindex @code{hw} request, and hyphenation language
6673 Set the current hyphenation language to the string @var{language}.
6674 Hyphenation exceptions specified with the @code{hw} request and
6675 hyphenation patterns specified with the @code{hpf} and @code{hpfa}
6676 requests are both associated with the current hyphenation language.
6677 The @code{hla} request is usually invoked by the @file{troffrc} or the
6678 @file{troffrc-end} files; @file{troffrc} sets the default language to
6681 @cindex hyphenation language register (@code{.hla})
6682 The current hyphenation language is available as a string in the
6683 read-only number register @samp{.hla}.
6686 .ds curr_language \n[.hla]
6693 @c =====================================================================
6695 @node Manipulating Spacing, Tabs and Fields, Manipulating Hyphenation, gtroff Reference
6696 @section Manipulating Spacing
6697 @cindex manipulating spacing
6698 @cindex spacing, manipulating
6700 @Defreq {sp, [@Var{distance}]}
6701 Space downwards @var{distance}. With no argument it advances
6702 1@tie{}line. A negative argument causes @code{gtroff} to move up the page
6703 the specified distance. If the argument is preceded by a @samp{|}
6704 then @code{gtroff} moves that distance from the top of the page. This
6705 request causes a line break. The default scaling indicator is @samp{v}.
6707 If a vertical trap is sprung during execution of @code{sp}, the amount of
6708 vertical space after the trap is discarded. For example, this
6736 @cindex @code{sp} request, and traps
6737 @cindex discarded space in traps
6738 @cindex space, discarded, in traps
6739 @cindex traps, and discarded space
6740 The amount of discarded space is available in the number register
6743 To protect @code{sp} against vertical traps, use the @code{vpt} request:
6752 @DefreqList {ls, [@Var{nnn}]}
6754 @cindex double-spacing (@code{ls})
6755 Output @w{@var{nnn}@minus{}1} blank lines after each line of text.
6756 With no argument, @code{gtroff} uses the previous value before the
6757 last @code{ls} call.
6760 .ls 2 \" This causes double-spaced output
6761 .ls 3 \" This causes triple-spaced output
6762 .ls \" Again double-spaced
6765 The line spacing is associated with the current environment
6766 (@pxref{Environments}).
6768 @cindex line spacing register (@code{.L})
6769 The read-only number register @code{.L} contains the current line
6773 @xref{Changing Type Sizes}, for the requests @code{vs} and @code{pvs}
6774 as alternatives to @code{ls}.
6776 @DefescList {\\x, ', spacing, '}
6778 Sometimes, extra vertical spacing is only needed occasionally, e.g.@:
6779 to allow space for a tall construct (like an equation). The @code{\x}
6780 escape does this. The escape is given a numerical argument, usually
6781 enclosed in quotes (like @samp{\x'3p'}); the default scaling indicator
6782 is @samp{v}. If this number is positive extra vertical space is
6783 inserted below the current line. A negative number adds space above.
6784 If this escape is used multiple times on the same line, the maximum of
6787 @xref{Escapes}, for details on parameter delimiting characters.
6789 @cindex extra post-vertical line space register (@code{.a})
6790 The @code{.a} read-only number register contains the most recent
6791 (nonnegative) extra vertical line space.
6793 Using @code{\x} can be necessary in combination with the @code{\b}
6794 escape, as the following example shows.
6797 This is a test with the \[rs]b escape.
6799 This is a test with the \[rs]b escape.
6801 This is a test with \b'xyz'\x'-1m'\x'1m'.
6803 This is a test with the \[rs]b escape.
6805 This is a test with the \[rs]b escape.
6812 This is a test with the \b escape.
6813 This is a test with the \b escape.
6815 This is a test with y.
6817 This is a test with the \b escape.
6818 This is a test with the \b escape.
6824 @DefregListEnd {.ns}
6825 @cindex @code{sp} request, and no-space mode
6826 @cindex no-space mode (@code{ns})
6827 @cindex mode, no-space (@code{ns})
6828 @cindex blank lines, disabling
6829 @cindex lines, blank, disabling
6830 Enable @dfn{no-space mode}. In this mode, spacing (either via
6831 @code{sp} or via blank lines) is disabled. The @code{bp} request to
6832 advance to the next page is also disabled, except if it is accompanied
6833 by a page number (see @ref{Page Control}, for more information). This
6834 mode ends when actual text is output or the @code{rs} request is
6835 encountered which ends no-space mode. The read-only number register
6836 @code{.ns} is set to@tie{}1 as long as no-space mode is active.
6838 This request is useful for macros that conditionally
6839 insert vertical space before the text starts
6840 (for example, a paragraph macro could insert some space
6841 except when it is the first paragraph after a section header).
6845 @c =====================================================================
6847 @node Tabs and Fields, Character Translations, Manipulating Spacing, gtroff Reference
6848 @section Tabs and Fields
6849 @cindex tabs, and fields
6850 @cindex fields, and tabs
6852 @cindex @acronym{EBCDIC} encoding of a tab
6853 A tab character (@acronym{ASCII} char@tie{}9, @acronym{EBCDIC}
6854 char@tie{}5) causes a horizontal movement to the next tab stop (much
6855 like it did on a typewriter).
6858 @cindex tab character, non-interpreted (@code{\t})
6859 @cindex character, tab, non-interpreted (@code{\t})
6860 This escape is a non-interpreted tab character. In copy mode
6861 (@pxref{Copy-in Mode}), @code{\t} is the same as a real tab character.
6864 @DefreqList {ta, [@Var{n1} @Var{n2} @dots{} @Var{nn} @t{T} @Var{r1} @Var{r2} @dots{} @Var{rn}]}
6865 @DefregListEnd {.tabs}
6866 Change tab stop positions. This request takes a series of tab
6867 specifiers as arguments (optionally divided into two groups with the
6868 letter @samp{T}) which indicate where each tab stop is to be
6869 (overriding any previous settings).
6871 Tab stops can be specified absolutely, i.e., as the distance from the
6872 left margin. For example, the following sets 6@tie{}tab stops every
6876 .ta 1i 2i 3i 4i 5i 6i
6879 Tab stops can also be specified using a leading @samp{+}
6880 which means that the specified tab stop is set relative to
6881 the previous tab stop. For example, the following is equivalent to the
6885 .ta 1i +1i +1i +1i +1i +1i
6888 @code{gtroff} supports an extended syntax to specify repeat values after
6889 the @samp{T} mark (these values are always taken as relative) -- this is
6890 the usual way to specify tabs set at equal intervals. The following is,
6891 yet again, the same as the previous examples. It does even more since
6892 it defines an infinite number of tab stops separated by one inch.
6898 Now we are ready to interpret the full syntax given at the beginning:
6899 Set tabs at positions @var{n1}, @var{n2}, @dots{}, @var{nn} and then set
6900 tabs at @var{nn}+@var{r1}, @var{nn}+@var{r2}, @dots{}, @var{nn}+@var{rn}
6901 and then at @var{nn}+@var{rn}+@var{r1}, @var{nn}+@var{rn}+@var{r2},
6902 @dots{}, @var{nn}+@var{rn}+@var{rn}, and so on.
6904 Example: @samp{4c +6c T 3c 5c 2c} is equivalent to @samp{4c 10c 13c 18c
6905 20c 23c 28c 30c @dots{}}.
6907 The material in each tab column (i.e., the column between two tab stops)
6908 may be justified to the right or left or centered in the column. This
6909 is specified by appending @samp{R}, @samp{L}, or @samp{C} to the tab
6910 specifier. The default justification is @samp{L}. Example:
6920 The default unit of the @code{ta} request is @samp{m}.
6923 A tab stop is converted into a non-breakable horizontal movement which
6924 can be neither stretched nor squeezed. For example,
6933 creates a single line which is a bit longer than 10@tie{}inches (a string
6934 is used to show exactly where the tab characters are). Now consider the
6944 @code{gtroff} first converts the tab stops of the line into unbreakable
6945 horizontal movements, then splits the line after the second @samp{b}
6946 (assuming a sufficiently short line length). Usually, this isn't what
6950 Superfluous tabs (i.e., tab characters which do not correspond to a tab
6951 stop) are ignored except the first one which delimits the characters
6952 belonging to the last tab stop for right-justifying or centering.
6953 Consider the following example
6957 .ds ZZ foo\tbar\tfoobar
6958 .ds ZZZ foo\tbar\tfoo\tbar
6969 which produces the following output:
6978 The first line right-justifies the second `foo' relative to the tab
6979 stop. The second line right-justifies `foobar'. The third line finally
6980 right-justifies only `foo' because of the additional tab character which
6981 marks the end of the string belonging to the last defined tab stop.
6984 Tab stops are associated with the current environment
6985 (@pxref{Environments}).
6988 Calling @code{ta} without an argument removes all tab stops.
6991 @cindex tab stops, for TTY output devices
6992 The start-up value of @code{gtroff} is @w{@samp{T 0.8i}}.
6995 @cindex tab settings register (@code{.tabs})
6996 The read-only number register @code{.tabs} contains a string
6997 representation of the current tab settings suitable for use as an
6998 argument to the @code{ta} request.
7001 .ds tab-string \n[.tabs]
7006 @cindex @code{.S} register, Plan@tie{}9 alias for @code{.tabs}
7007 @cindex @code{.tabs} register, Plan@tie{}9 alias (@code{.S})
7008 The @code{troff} version of the Plan@tie{}9 operating system uses
7009 register @code{.S} for the same purpose.
7012 @Defreq {tc, [@Var{fill-glyph}]}
7013 @cindex tab repetition character (@code{tc})
7014 @cindex character, tab repetition (@code{tc})
7015 @cindex glyph, tab repetition (@code{tc})
7016 Normally @code{gtroff} fills the space to the next tab stop with
7017 whitespace. This can be changed with the @code{tc} request. With no
7018 argument @code{gtroff} reverts to using whitespace, which is the
7019 default. The value of this @dfn{tab repetition character} is
7020 associated with the current environment
7021 (@pxref{Environments}).@footnote{@dfn{Tab repetition character} is a
7022 misnomer since it is an output glyph.}
7025 @DefreqList {linetabs, n}
7026 @DefregListEnd {.linetabs}
7027 @cindex tab, line-tabs mode
7028 @cindex line-tabs mode
7029 @cindex mode, line-tabs
7030 If @var{n} is missing or not zero, enable @dfn{line-tabs} mode,
7031 or disable it otherwise (the default).
7032 In line-tabs mode, @code{gtroff} computes tab distances
7033 relative to the (current) output line instead of the input line.
7035 For example, the following code:
7048 in normal mode, results in the output
7055 in line-tabs mode, the same code outputs
7061 Line-tabs mode is associated with the current environment.
7062 The read-only register @code{.linetabs} is set to@tie{}1 if in line-tabs
7063 mode, and 0 in normal mode.
7071 @c ---------------------------------------------------------------------
7073 @node Leaders, Fields, Tabs and Fields, Tabs and Fields
7077 Sometimes it may may be desirable to use the @code{tc} request to fill a
7078 particular tab stop with a given glyph (for example dots in a table
7079 of contents), but also normal tab stops on the rest of the line. For
7080 this @code{gtroff} provides an alternate tab mechanism, called
7081 @dfn{leaders} which does just that.
7083 @cindex leader character
7084 A leader character (character code@tie{}1) behaves similarly to a tab
7085 character: It moves to the next tab stop. The only difference is that
7086 for this movement, the fill glyph defaults to a period character and
7090 @cindex leader character, non-interpreted (@code{\a})
7091 @cindex character, leader, non-interpreted (@code{\a})
7092 This escape is a non-interpreted leader character. In copy mode
7093 (@pxref{Copy-in Mode}), @code{\a} is the same as a real leader
7097 @Defreq {lc, [@Var{fill-glyph}]}
7098 @cindex leader repetition character (@code{lc})
7099 @cindex character, leader repetition (@code{lc})
7100 @cindex glyph, leader repetition (@code{lc})
7101 Declare the @dfn{leader repetition character}.@footnote{@dfn{Leader
7102 repetition character} is a misnomer since it is an output glyph.}
7103 Without an argument, leaders act the same as tabs (i.e., using
7104 whitespace for filling). @code{gtroff}'s start-up value is a dot
7105 (@samp{.}). The value of the leader repetition character is
7106 associated with the current environment (@pxref{Environments}).
7109 @cindex table of contents
7110 @cindex contents, table of
7111 For a table of contents, to name an example, tab stops may be defined so
7112 that the section number is one tab stop, the title is the second with
7113 the remaining space being filled with a line of dots, and then the page
7114 number slightly separated from the dots.
7117 .ds entry 1.1\tFoo\a\t12
7127 1.1 Foo.......................................... 12
7130 @c ---------------------------------------------------------------------
7132 @node Fields, , Leaders, Tabs and Fields
7136 @cindex field delimiting character (@code{fc})
7137 @cindex delimiting character, for fields (@code{fc})
7138 @cindex character, field delimiting (@code{fc})
7139 @cindex field padding character (@code{fc})
7140 @cindex padding character, for fields (@code{fc})
7141 @cindex character, field padding (@code{fc})
7142 @dfn{Fields} are a more general way of laying out tabular data. A field
7143 is defined as the data between a pair of @dfn{delimiting characters}.
7144 It contains substrings which are separated by @dfn{padding characters}.
7145 The width of a field is the distance on the @emph{input} line from the
7146 position where the field starts to the next tab stop. A padding
7147 character inserts stretchable space similar to @TeX{}'s @code{\hss}
7148 command (thus it can even be negative) to make the sum of all substring
7149 lengths plus the stretchable space equal to the field width. If more
7150 than one padding character is inserted, the available space is evenly
7151 distributed among them.
7153 @Defreq {fc, [@Var{delim-char} [@Var{padding-char}]]}
7154 Define a delimiting and a padding character for fields. If the latter
7155 is missing, the padding character defaults to a space character. If
7156 there is no argument at all, the field mechanism is disabled (which is
7157 the default). Note that contrary to e.g.@: the tab repetition
7158 character, delimiting and padding characters are @emph{not} associated
7159 to the current environment (@pxref{Environments}).
7172 and here the result:
7181 @c =====================================================================
7183 @node Character Translations, Troff and Nroff Mode, Tabs and Fields, gtroff Reference
7184 @section Character Translations
7185 @cindex character translations
7186 @cindex translations of characters
7188 @cindex control character, changing (@code{cc})
7189 @cindex character, control, changing (@code{cc})
7190 @cindex no-break control character, changing (@code{c2})
7191 @cindex character, no-break control, changing (@code{c2})
7192 @cindex control character, no-break, changing (@code{c2})
7193 The control character (@samp{.}) and the no-break control character
7194 (@samp{'}) can be changed with the @code{cc} and @code{c2} requests,
7197 @Defreq {cc, [@Var{c}]}
7198 Set the control character to@tie{}@var{c}. With no argument the default
7199 control character @samp{.} is restored. The value of the control
7200 character is associated with the current environment
7201 (@pxref{Environments}).
7204 @Defreq {c2, [@Var{c}]}
7205 Set the no-break control character to@tie{}@var{c}. With no argument the
7206 default control character @samp{'} is restored. The value of the
7207 no-break control character is associated with the current environment
7208 (@pxref{Environments}).
7212 @cindex disabling @code{\} (@code{eo})
7213 @cindex @code{\}, disabling (@code{eo})
7214 Disable the escape mechanism completely. After executing this
7215 request, the backslash character @samp{\} no longer starts an escape
7218 This request can be very helpful in writing macros since it is not
7219 necessary then to double the escape character. Here an example:
7222 .\" This is a simplified version of the
7223 .\" .BR request from the man macro package
7227 . while (\n[.$] >= 2) \@{\
7228 . as result \fB\$1\fR\$2
7231 . if \n[.$] .as result \fB\$1
7239 @Defreq {ec, [@Var{c}]}
7240 @cindex escape character, changing (@code{ec})
7241 @cindex character, escape, changing (@code{ec})
7242 Set the escape character to@tie{}@var{c}. With no argument the default
7243 escape character @samp{\} is restored. It can be also used to
7244 re-enable the escape mechanism after an @code{eo} request.
7246 Note that changing the escape character globally will likely break
7247 macro packages since @code{gtroff} has no mechanism to `intern' macros,
7248 i.e., to convert a macro definition into an internal form which is
7249 independent of its representation (@TeX{} has this mechanism).
7250 If a macro is called, it is executed literally.
7254 @DefreqListEnd {ecr, }
7255 The @code{ecs} request saves the current escape character
7256 in an internal register.
7257 Use this request in combination with the @code{ec} request to
7258 temporarily change the escape character.
7260 The @code{ecr} request restores the escape character
7261 saved with @code{ecs}.
7262 Without a previous call to @code{ecs}, this request
7263 sets the escape character to @code{\}.
7266 @DefescList {\\\\, , , }
7267 @DefescItem {\\e, , , }
7268 @DefescListEnd {\\E, , , }
7269 Print the current escape character (which is the backslash character
7270 @samp{\} by default).
7272 @code{\\} is a `delayed' backslash; more precisely, it is the default
7273 escape character followed by a backslash, which no longer has special
7274 meaning due to the leading escape character. It is @emph{not} an escape
7275 sequence in the usual sense! In any unknown escape sequence
7276 @code{\@var{X}} the escape character is ignored and @var{X} is printed.
7277 But if @var{X} is equal to the current escape character, no warning is
7280 As a consequence, only at top-level or in a diversion a backslash glyph is
7281 printed; in copy-in mode, it expands to a single backslash which then
7282 combines with the following character to an escape sequence.
7284 The @code{\E} escape differs from @code{\e} by printing an escape
7285 character that is not interpreted in copy mode.
7286 Use this to define strings with escapes that work
7287 when used in copy mode (for example, as a macro argument).
7288 The following example defines strings to begin and end
7292 .ds @{ \v'-.3m'\s'\En[.s]*60/100'
7296 Another example to demonstrate the differences between the various escape
7297 sequences, using a strange escape character, @samp{-}.
7309 The result is surprising for most users, expecting @samp{1} since
7310 @samp{foo} is a valid identifier. What has happened? As mentioned
7311 above, the leading escape character makes the following character
7312 ordinary. Written with the default escape character the sequence
7313 @samp{--} becomes @samp{\-} -- this is the minus sign.
7315 If the escape character followed by itself is a valid escape sequence,
7316 only @code{\E} yields the expected result:
7329 Similar to @code{\\}, the sequence @code{\.} isn't a real escape sequence.
7330 As before, a warning message is suppressed if the escape character is
7331 followed by a dot, and the dot itself is printed.
7348 The first backslash is consumed while the macro is read, and the second
7349 is swallowed while exexuting macro @code{foo}.
7352 A @dfn{translation} is a mapping of an input character to an output
7353 glyph. The mapping occurs at output time, i.e., the input character
7354 gets assigned the metric information of the mapped output character
7355 right before input tokens are converted to nodes (@pxref{Gtroff
7356 Internals}, for more on this process).
7358 @DefreqList {tr, @Var{a}@Var{b}@Var{c}@Var{d}@dots{}}
7359 @DefreqListEnd {trin, @Var{a}@Var{b}@Var{c}@Var{d}@dots{}}
7360 Translate character @var{a} to glyph@tie{}@var{b}, character @var{c} to
7361 glyph@tie{}@var{d}, etc. If there is an odd number of arguments, the
7362 last one is translated to an unstretchable space (@w{@samp{\ }}).
7364 The @code{trin} request is identical to @code{tr},
7365 but when you unformat a diversion with @code{asciify}
7366 it ignores the translation.
7367 @xref{Diversions}, for details about the @code{asciify} request.
7373 @cindex @code{\(}, and translations
7374 @cindex @code{\[}, and translations
7375 @cindex @code{\'}, and translations
7376 @cindex @code{\`}, and translations
7377 @cindex @code{\-}, and translations
7378 @cindex @code{\_}, and translations
7379 @cindex @code{\C}, and translations
7380 @cindex @code{\N}, and translations
7381 @cindex @code{char} request, and translations
7382 @cindex special characters
7383 @cindex character, special
7384 @cindex numbered glyph (@code{\N})
7385 @cindex glyph, numbered (@code{\N})
7386 Special characters (@code{\(@var{xx}}, @code{\[@var{xxx}]},
7387 @code{\C'@var{xxx}'}, @code{\'}, @code{\`}, @code{\-}, @code{\_}),
7388 glyphs defined with the @code{char} request, and numbered glyphs
7389 (@code{\N'@var{xxx}'}) can be translated also.
7392 @cindex @code{\e}, and translations
7393 The @code{\e} escape can be translated also.
7396 @cindex @code{\%}, and translations
7397 @cindex @code{\~}, and translations
7398 Characters can be mapped onto the @code{\%} and @code{\~} escapes (but
7399 @code{\%} and @code{\~} can't be mapped onto another glyph).
7402 @cindex backspace character, and translations
7403 @cindex character, backspace, and translations
7404 @cindex leader character, and translations
7405 @cindex character, leader, and translations
7406 @cindex newline character, and translations
7407 @cindex character, newline, and translations
7408 @cindex tab character, and translations
7409 @cindex character, tab, and translations
7410 @cindex @code{\a}, and translations
7411 @cindex @code{\t}, and translations
7412 The following characters can't be translated: space (with one exception,
7413 see below), backspace, newline, leader (and @code{\a}), tab (and
7417 @cindex @code{shc} request, and translations
7418 Translations are not considered for finding the soft hyphen character
7419 set with the @code{shc} request.
7422 @cindex @code{\&}, and translations
7423 The pair @samp{@var{c}\&} (this is an arbitrary character@tie{}@var{c}
7424 followed by the zero width space character) maps this character to nothing.
7433 It is even possible to map the space character to nothing:
7442 As shown in the example, the space character can't be the first
7443 character/glyph pair as an argument of @code{tr}. Additionally, it is
7444 not possible to map the space character to any other glyph; requests
7445 like @w{@samp{.tr aa x}} undo @w{@samp{.tr aa \&}} instead.
7447 If justification is active, lines are justified in spite of the
7448 `empty' space character (but there is no minimal distance, i.e.@: the
7449 space character, between words).
7452 After an output glyph has been constructed (this happens at the
7453 moment immediately before the glyph is appended to an output
7454 glyph list, either by direct output, in a macro, diversion, or
7455 string), it is no longer affected by @code{tr}.
7458 Translating character to glyphs where one of them or both are
7459 undefined is possible also; @code{tr} does not check whether the
7460 entities in its argument do exist.
7462 @xref{Gtroff Internals}.
7465 @code{troff} no longer has a hard-coded dependency on @w{Latin-1};
7466 all @code{char@var{XXX}} entities have been removed from the font
7467 description files. This has a notable consequence which shows up in
7468 warnings like @code{can't find character with input code @var{XXX}}
7469 if the @code{tr} request isn't handled properly.
7471 Consider the following translation:
7478 This maps input character @code{@'e} onto glyph @code{@'E}, which is
7479 identical to glyph @code{char201}. But this glyph intentionally
7480 doesn't exist! Instead, @code{\[char201]} is treated as an input
7481 character entity and is by default mapped onto @code{\['E]}, and
7482 @code{gtroff} doesn't handle translations of translations.
7484 The right way to write the above translation is
7491 With other words, the first argument of @code{tr} should be an input
7492 character or entity, and the second one a glyph entity.
7495 Without an argument, the @code{tr} request is ignored.
7499 @Defreq {trnt, @Var{a}@Var{b}@Var{c}@Var{d}@dots{}}
7500 @cindex @code{\!}, and @code{trnt}
7501 @code{trnt} is the same as the @code{tr} request except that the
7502 translations do not apply to text that is transparently throughput
7503 into a diversion with @code{\!}. @xref{Diversions}, for more
7517 prints @samp{b} to the standard error stream; if @code{trnt} is used
7518 instead of @code{tr} it prints @samp{a}.
7522 @c =====================================================================
7524 @node Troff and Nroff Mode, Line Layout, Character Translations, gtroff Reference
7525 @section Troff and Nroff Mode
7531 Originally, @code{nroff} and @code{troff} were two separate programs,
7532 the former for TTY output, the latter for everything else. With GNU
7533 @code{troff}, both programs are merged into one executable, sending
7534 its output to a device driver (@code{grotty} for TTY devices,
7535 @code{grops} for @sc{PostScript}, etc.) which interprets the
7536 intermediate output of @code{gtroff}. For @acronym{UNIX} @code{troff}
7537 it makes sense to talk about @dfn{Nroff mode} and @dfn{Troff mode}
7538 since the differences are hardcoded. For GNU @code{troff}, this
7539 distinction is not appropriate because @code{gtroff} simply takes the
7540 information given in the font files for a particular device without
7541 handling requests specially if a TTY output device is used.
7543 Usually, a macro package can be used with all output devices.
7544 Nevertheless, it is sometimes necessary to make a distinction between
7545 TTY and non-TTY devices: @code{gtroff} provides two built-in
7546 conditions @samp{n} and @samp{t} for the @code{if}, @code{ie}, and
7547 @code{while} requests to decide whether @code{gtroff} shall behave
7548 like @code{nroff} or like @code{troff}.
7553 Make the @samp{t} built-in condition true (and the @samp{n} built-in
7554 condition false) for @code{if}, @code{ie}, and @code{while}
7555 conditional requests. This is the default if @code{gtroff}
7556 (@emph{not} @code{groff}) is started with the @option{-R} switch to
7557 avoid loading of the start-up files @file{troffrc} and
7558 @file{troffrc-end}. Without @option{-R}, @code{gtroff} stays in troff
7559 mode if the output device is not a TTY (e.g.@: `ps').
7564 Make the @samp{n} built-in condition true (and the @samp{t} built-in
7565 condition false) for @code{if}, @code{ie}, and @code{while}
7566 conditional requests. This is the default if @code{gtroff} uses a TTY
7567 output device; the code for switching to nroff mode is in the file
7568 @file{tty.tmac} which is loaded by the start-up file @code{troffrc}.
7571 @xref{Conditionals and Loops}, for more details on built-in
7575 @c =====================================================================
7577 @node Line Layout, Line Control, Troff and Nroff Mode, gtroff Reference
7578 @section Line Layout
7580 @cindex layout, line
7582 @cindex dimensions, line
7583 @cindex line dimensions
7584 The following drawing shows the dimensions which @code{gtroff} uses for
7585 placing a line of output onto the page. They are labeled with the
7586 request which manipulates each dimension.
7590 |<-----------ll------------>|
7591 +----+----+----------------------+----+
7593 +----+----+----------------------+----+
7595 |<--------paper width---------------->|
7599 These dimensions are:
7603 @cindex left margin (@code{po})
7604 @cindex margin, left (@code{po})
7605 @cindex page offset (@code{po})
7606 @cindex offset, page (@code{po})
7607 @dfn{Page offset} -- this is the leftmost position of text on the final
7608 output, defining the @dfn{left margin}.
7611 @cindex indentation (@code{in})
7612 @cindex line indentation (@code{in})
7613 @dfn{Indentation} -- this is the distance from the left margin where
7617 @cindex line length (@code{ll})
7618 @cindex length of line (@code{ll})
7619 @dfn{Line length} -- this is the distance from the left margin to right
7623 A simple demonstration:
7627 This is text without indentation.
7628 The line length has been set to 3\~inch.
7631 Now the left and right margins are both increased.
7634 Calling .in and .ll without parameters restore
7635 the previous values.
7641 This is text without indenta-
7642 tion. The line length has
7647 Calling .in and .ll without
7648 parameters restore the previ-
7652 @DefreqList {po, [@Var{offset}]}
7653 @DefreqItem {po, @t{+}@Var{offset}}
7654 @DefreqItem {po, @t{-}@Var{offset}}
7657 Set horizontal page offset to @var{offset} (or increment or decrement
7658 the current value by @var{offset}). Note that this request does not
7659 cause a break, so changing the page offset in the middle of text being
7660 filled may not yield the expected result. The initial value is
7661 1@dmn{i}. For TTY output devices, it is set to 0 in the startup file
7662 @file{troffrc}; the default scaling indicator is @samp{m} (and
7663 not @samp{v} as incorrectly documented in the original
7664 @acronym{UNIX} troff manual).
7666 The current page offset can be found in the read-only number register
7669 If @code{po} is called without an argument, the page offset is reset to
7670 the previous value before the last call to @code{po}.
7685 @DefreqList {in, [@Var{indent}]}
7686 @DefreqItem {in, @t{+}@Var{indent}}
7687 @DefreqItem {in, @t{-}@Var{indent}}
7689 Set indentation to @var{indent} (or increment or decrement the
7690 current value by @var{indent}). This request causes a break.
7691 Initially, there is no indentation.
7693 If @code{in} is called without an argument, the indentation is reset to
7694 the previous value before the last call to @code{in}. The default
7695 scaling indicator is @samp{m}.
7697 The indentation is associated with the current environment
7698 (@pxref{Environments}).
7700 If a negative indentation value is specified (which is not allowed),
7701 @code{gtroff} emits a warning of type @samp{range} and sets the
7702 indentation to zero.
7704 The effect of @code{in} is delayed until a partially collected line (if
7705 it exists) is output. A temporary indent value is reset to zero also.
7707 The current indentation (as set by @code{in}) can be found in the
7708 read-only number register @samp{.i}.
7711 @DefreqList {ti, offset}
7712 @DefreqItem {ti, @t{+}@Var{offset}}
7713 @DefreqItem {ti, @t{-}@Var{offset}}
7714 @DefregListEnd {.in}
7715 Temporarily indent the next output line by @var{offset}. If an
7716 increment or decrement value is specified, adjust the temporary
7717 indentation relative to the value set by the @code{in} request.
7719 This request causes a break; its value is associated with the current
7720 environment (@pxref{Environments}). The default scaling indicator
7721 is @samp{m}. A call of @code{ti} without an argument is ignored.
7723 If the total indentation value is negative (which is not allowed),
7724 @code{gtroff} emits a warning of type @samp{range} and sets the
7725 temporary indentation to zero. `Total indentation' is either
7726 @var{offset} if specified as an absolute value, or the temporary plus
7727 normal indentation, if @var{offset} is given as a relative value.
7729 The effect of @code{ti} is delayed until a partially collected line (if
7730 it exists) is output.
7732 The read-only number register @code{.in} is the indentation that applies
7733 to the current output line.
7735 The difference between @code{.i} and @code{.in} is that the latter takes
7736 into account whether a partially collected line still uses the old
7737 indentation value or a temporary indentation value is active.
7740 @DefreqList {ll, [@Var{length}]}
7741 @DefreqItem {ll, @t{+}@Var{length}}
7742 @DefreqItem {ll, @t{-}@Var{length}}
7744 @DefregListEnd {.ll}
7745 Set the line length to @var{length} (or increment or decrement the
7746 current value by @var{length}). Initially, the line length is set to
7747 6.5@dmn{i}. The effect of @code{ll} is delayed until a partially
7748 collected line (if it exists) is output. The default scaling
7749 indicator is @samp{m}.
7751 If @code{ll} is called without an argument, the line length is reset to
7752 the previous value before the last call to @code{ll}. If a negative
7753 line length is specified (which is not allowed), @code{gtroff} emits a
7754 warning of type @samp{range} and sets the line length to zero.
7756 The line length is associated with the current environment
7757 (@pxref{Environments}).
7759 @cindex line length register (@code{.l})
7760 The current line length (as set by @code{ll}) can be found in the
7761 read-only number register @samp{.l}. The read-only number register
7762 @code{.ll} is the line length that applies to the current output line.
7764 Similar to @code{.i} and @code{.in}, the difference between @code{.l}
7765 and @code{.ll} is that the latter takes into account whether a partially
7766 collected line still uses the old line length value.
7770 @c =====================================================================
7772 @node Line Control, Page Layout, Line Layout, gtroff Reference
7773 @section Line Control
7774 @cindex line control
7775 @cindex control, line
7777 It is important to understand how @code{gtroff} handles input and output
7780 Many escapes use positioning relative to the input line. For example,
7784 This is a \h'|1.2i'test.
7799 The main usage of this feature is to define macros which act exactly
7800 at the place where called.
7803 .\" A simple macro to underline a word
7805 . nop \\$1\l'|0\[ul]'
7810 In the above example, @samp{|0} specifies a negative distance from the
7811 current position (at the end of the just emitted argument @code{\$1}) back
7812 to the beginning of the input line. Thus, the @samp{\l} escape draws a
7813 line from right to left.
7815 @cindex input line continuation (@code{\})
7816 @cindex line, input, continuation (@code{\})
7817 @cindex continuation, input line (@code{\})
7818 @cindex output line, continuation (@code{\c})
7819 @cindex line, output, continuation (@code{\c})
7820 @cindex continuation, output line (@code{\c})
7821 @cindex interrupted line
7822 @cindex line, interrupted
7823 @code{gtroff} makes a difference between input and output line
7824 continuation; the latter is also called @dfn{interrupting} a line.
7826 @DefescList {\\@key{RET}, , ,}
7827 @DefescItem {\\c, , ,}
7828 @DefregListEnd{.int}
7829 Continue a line. @code{\@key{RET}} (this is a backslash at the end
7830 of a line immediately followed by a newline) works on the input level,
7831 suppressing the effects of the following newline in the input.
7836 @result{} This is a .test
7839 The @samp{|} operator is also affected.
7841 @cindex @code{\R}, after @code{\c}
7842 @code{\c} works on the output level. Anything after this escape on the
7843 same line is ignored, except @code{\R} which works as usual. Anything
7844 before @code{\c} on the same line will be appended to the current partial
7845 output line. The next non-command line after an interrupted line counts
7846 as a new input line.
7848 The visual results depend on whether no-fill mode is active.
7852 @cindex @code{\c}, and no-fill mode
7853 @cindex no-fill mode, and @code{\c}
7854 @cindex mode, no-fill, and @code{\c}
7855 If no-fill mode is active (using the @code{nf} request), the next input
7856 text line after @code{\c} will be handled as a continuation of the same
7863 @result{} This is a test.
7867 @cindex @code{\c}, and fill mode
7868 @cindex fill mode, and @code{\c}
7869 @cindex mode, fill, and @code{\c}
7870 If fill mode is active (using the @code{fi} request), a word interrupted
7871 with @code{\c} will be continued with the text on the next input text line,
7872 without an intervening space.
7877 @result{} This is a test.
7881 Note that an intervening control line which causes a break is stronger
7882 than @code{\c}, flushing out the current partial line in the usual way.
7884 @cindex interrupted line register (@code{.int})
7885 The @code{.int} register contains a positive value
7886 if the last output line was interrupted with @code{\c}; this is
7887 associated with the current environment (@pxref{Environments}).
7891 @c =====================================================================
7893 @node Page Layout, Page Control, Line Control, gtroff Reference
7894 @section Page Layout
7896 @cindex layout, page
7898 @code{gtroff} provides some very primitive operations for controlling
7901 @DefreqList {pl, [@Var{length}]}
7902 @DefreqItem {pl, @t{+}@Var{length}}
7903 @DefreqItem {pl, @t{-}@Var{length}}
7905 @cindex page length (@code{pl})
7906 @cindex length of page (@code{pl})
7907 Set the @dfn{page length} to @var{length} (or increment or decrement
7908 the current value by @var{length}). This is the length of the
7909 physical output page. The default scaling indicator is @samp{v}.
7911 @cindex page length register (@code{.p})
7912 The current setting can be found in the read-only number register
7917 @cindex bottom margin
7918 @cindex margin, bottom
7919 Note that this only specifies the size of the page, not the top and
7920 bottom margins. Those are not set by @code{gtroff} directly.
7921 @xref{Traps}, for further information on how to do this.
7923 Negative @code{pl} values are possible also, but not very useful: No
7924 trap is sprung, and each line is output on a single page (thus
7925 suppressing all vertical spacing).
7927 If no argument or an invalid argument is given, @code{pl} sets the page
7928 length to 11@dmn{i}.
7934 @code{gtroff} provides several operations which help in setting up top
7935 and bottom titles (or headers and footers).
7937 @Defreq {tl, @t{'}@Var{left}@t{'}@Var{center}@t{'}@Var{right}@t{'}}
7938 @cindex title line (@code{tl})
7939 @cindex three-part title (@code{tl})
7940 @cindex page number character (@code{%})
7941 Print a @dfn{title line}. It consists of three parts: a left
7942 justified portion, a centered portion, and a right justified portion.
7943 The argument separator @samp{'} can be replaced with any character not
7944 occurring in the title line. The @samp{%} character is replaced with
7945 the current page number. This character can be changed with the
7946 @code{pc} request (see below).
7948 Without argument, @code{tl} is ignored.
7954 A title line is not restricted to the top or bottom of a page.
7957 @code{tl} prints the title line immediately, ignoring a partially filled
7958 line (which stays untouched).
7961 It is not an error to omit closing delimiters. For example,
7962 @w{@samp{.tl /foo}} is equivalent to @w{@samp{.tl /foo///}}: It prints a
7963 title line with the left justified word @samp{foo}; the centered and
7964 right justfied parts are empty.
7967 @code{tl} accepts the same parameter delimiting characters as the
7968 @code{\A} escape; see @ref{Escapes}.
7972 @DefreqList {lt, [@Var{length}]}
7973 @DefreqItem {lt, @t{+}@Var{length}}
7974 @DefreqItem {lt, @t{-}@Var{length}}
7975 @DefregListEnd {.lt}
7976 @cindex length of title line (@code{lt})
7977 @cindex title line, length (@code{lt})
7978 @cindex title line length register (@code{.lt})
7979 The title line is printed using its own line length, which is
7980 specified (or incremented or decremented) with the @code{lt} request.
7981 Initially, the title line length is set to 6.5@dmn{i}. If a negative
7982 line length is specified (which is not allowed), @code{gtroff} emits a
7983 warning of type @samp{range} and sets the title line length to zero.
7984 The default scaling indicator is @samp{m}. If @code{lt} is called
7985 without an argument, the title length is reset to the previous value
7986 before the last call to @code{lt}.
7988 The current setting of this is available in the @code{.lt} read-only
7989 number register; it is associated with the current environment
7990 (@pxref{Environments}).
7994 @DefreqList {pn, page}
7995 @DefreqItem {pn, @t{+}@Var{page}}
7996 @DefreqItem {pn, @t{-}@Var{page}}
7997 @DefregListEnd {.pn}
7998 @cindex page number (@code{pn})
7999 @cindex number, page (@code{pn})
8000 Change (increase or decrease) the page number of the @emph{next} page.
8001 The only argument is the page number; the request is ignored without a
8004 The read-only number register @code{.pn} contains the number of the next
8005 page: either the value set by a @code{pn} request, or the number of the
8006 current page plus@tie{}1.
8010 @cindex page number register (@code{%})
8011 A read-write register holding the current page number.
8014 @Defreq {pc, [@Var{char}]}
8015 @cindex changing the page number character (@code{pc})
8016 @cindex page number character, changing (@code{pc})
8018 Change the page number character (used by the @code{tl} request) to a
8019 different character. With no argument, this mechanism is disabled.
8020 Note that this doesn't affect the number register@tie{}@code{%}.
8026 @c =====================================================================
8028 @node Page Control, Fonts and Symbols, Page Layout, gtroff Reference
8029 @section Page Control
8030 @cindex page control
8031 @cindex control, page
8033 @DefreqList {bp, [@Var{page}]}
8034 @DefreqItem {bp, @t{+}@Var{page}}
8035 @DefreqListEnd {bp, @t{-}@Var{page}}
8036 @cindex new page (@code{bp})
8037 @cindex page, new (@code{bp})
8038 Stop processing the current page and move to the next page. This
8039 request causes a break. It can also take an argument to set
8040 (increase, decrease) the page number of the next page. The only
8041 difference between @code{bp} and @code{pn} is that @code{pn} does not
8042 cause a break or actually eject a page.
8045 .de newpage \" define macro
8047 'sp .5i \" vertical space
8048 .tl 'left top'center top'right top' \" title
8049 'sp .3i \" vertical space
8053 @cindex @code{bp} request, and top-level diversion
8054 @cindex top-level diversion, and @code{bp}
8055 @cindex diversion, top-level, and @code{bp}
8056 @code{bp} has no effect if not called within the top-level diversion
8057 (@pxref{Diversions}).
8059 The number register @code{.pe} is set to@tie{}1 while @code{bp} is
8060 active. @xref{Page Location Traps}.
8063 @Defreq {ne, [@Var{space}]}
8064 @cindex orphan lines, preventing with @code{ne}
8065 @cindex conditional page break (@code{ne})
8066 @cindex page break, conditional (@code{ne})
8067 It is often necessary to force a certain amount of space before a new
8068 page occurs. This is most useful to make sure that there is not a
8069 single @dfn{orphan} line left at the bottom of a page. The @code{ne}
8070 request ensures that there is a certain distance, specified by the
8071 first argument, before the next page is triggered (see @ref{Traps},
8072 for further information). The default scaling indicator for @code{ne}
8073 is @samp{v}; the default value of @var{space} is@tie{}1@dmn{v} if no
8076 For example, to make sure that no fewer than 2@tie{}lines get orphaned,
8077 do the following before each paragraph:
8084 @code{ne} will then automatically cause a page break if there is space
8088 @DefreqList {sv, [@Var{space}]}
8089 @DefreqListEnd {os, }
8090 @cindex @code{ne} request, comparison with @code{sv}
8091 @code{sv} is similar to the @code{ne} request; it reserves the
8092 specified amount of vertical space. If the desired amount of space
8093 exists before the next trap (or the bottom page boundary if no trap is
8094 set), the space is output immediately (ignoring a partially filled line
8095 which stays untouched). If there is not enough space, it is stored for
8096 later output via the @code{os} request. The default value is@tie{}1@dmn{v}
8097 if no argument is given; the default scaling indicator is @samp{v}.
8099 @cindex @code{sv} request, and no-space mode
8100 @cindex @code{os} request, and no-space mode
8101 Both @code{sv} and @code{os} ignore no-space mode. While the @code{sv}
8102 request allows negative values for @var{space}, @code{os} will ignore
8107 @cindex current vertical position (@code{nl})
8108 @cindex vertical position, current (@code{nl})
8109 @cindex position, vertical, current (@code{nl})
8110 This register contains the current vertical position. If the vertical
8111 position is zero and the top of page transition hasn't happened yet,
8112 @code{nl} is set to negative value. @code{gtroff} itself does this at
8113 the very beginning of a document before anything has been printed, but
8114 the main usage is to plant a header trap on a page if this page has
8117 Consider the following:
8149 Without resetting @code{nl} to a negative value, the just planted trap
8150 would be active beginning with the @emph{next} page, not the current
8153 @xref{Diversions}, for a comparison with the @code{.h} and @code{.d}
8157 @c =====================================================================
8159 @node Fonts and Symbols, Sizes, Page Control, gtroff Reference
8160 @section Fonts and Symbols
8163 @code{gtroff} can switch fonts at any point in the text.
8165 The basic set of fonts is @samp{R}, @samp{I}, @samp{B}, and @samp{BI}.
8166 These are Times Roman, Italic, Bold, and Bold Italic. For non-TTY
8167 devices, there is also at least one symbol font which contains various
8168 special symbols (Greek, mathematics).
8176 * Artificial Fonts::
8177 * Ligatures and Kerning::
8180 @c ---------------------------------------------------------------------
8182 @node Changing Fonts, Font Families, Fonts and Symbols, Fonts and Symbols
8183 @subsection Changing Fonts
8186 @DefreqList {ft, [@Var{font}]}
8187 @DefescItem {\\f, , f, }
8188 @DefescItem {\\f, @lparen{}, fn, }
8189 @DefescListEnd {\\f, @lbrack{}, font, @rbrack}
8190 @cindex changing fonts (@code{ft}, @code{\f})
8191 @cindex fonts, changing (@code{ft}, @code{\f})
8192 @cindex @code{sty} request, and changing fonts
8193 @cindex @code{fam} request, and changing fonts
8194 @cindex @code{\F}, and changing fonts
8198 The @code{ft} request and the @code{\f} escape change the current font
8199 to @var{font} (one-character name@tie{}@var{f}, two-character name
8202 If @var{font} is a style name (as set with the @code{sty} request or
8203 with the @code{styles} command in the @file{DESC} file), use it within
8204 the current font family (as set with the @code{fam} request, @code{\F}
8205 escape, or with the @code{family} command in the @file{DESC} file).
8207 @cindex previous font (@code{ft}, @code{\f[]}, @code{\fP})
8208 @cindex font, previous (@code{ft}, @code{\f[]}, @code{\fP})
8209 With no argument or using @samp{P} as an argument, @code{.ft} switches
8210 to the previous font. Use @code{\f[]} to do this with the escape. The
8211 old syntax forms @code{\fP} or @code{\f[P]} are also supported.
8213 Fonts are generally specified as upper-case strings, which are usually
8214 1@tie{}to 4 characters representing an abbreviation or acronym of the
8215 font name. This is no limitation, just a convention.
8217 The example below produces two identical lines.
8226 eggs, bacon, \fBspam\fP and sausage.
8229 Note that @code{\f} doesn't produce an input token in @code{gtroff}.
8230 As a consequence, it can be used in requests like @code{mc} (which
8231 expects a single character as an argument) to change the font on
8238 @xref{Font Positions}, for an alternative syntax.
8241 @Defreq {ftr, f [@Var{g}]}
8242 @cindex @code{ft} request, and font translations
8243 @cindex @code{ul} request, and font translations
8244 @cindex @code{bd} request, and font translations
8245 @cindex @code{\f}, and font translations
8246 @cindex @code{cs} request, and font translations
8247 @cindex @code{tkf} request, and font translations
8248 @cindex @code{special} request, and font translations
8249 @cindex @code{fspecial} request, and font translations
8250 @cindex @code{fp} request, and font translations
8251 @cindex @code{sty} request, and font translations
8252 Translate font@tie{}@var{f} to font@tie{}@var{g}. Whenever a font
8253 named@tie{}@var{f} is referred to in a @code{\f} escape sequence, or in the
8254 @code{ft}, @code{ul}, @code{bd}, @code{cs}, @code{tkf},
8255 @code{special}, @code{fspecial}, @code{fp}, or @code{sty} requests,
8256 font@tie{}@var{g} is used. If @var{g} is missing or equal to@tie{}@var{f}
8257 the translation is undone.
8260 @c ---------------------------------------------------------------------
8262 @node Font Families, Font Positions, Changing Fonts, Fonts and Symbols
8263 @subsection Font Families
8264 @cindex font families
8265 @cindex families, font
8267 @cindex styles, font
8269 Due to the variety of fonts available, @code{gtroff} has added the
8270 concept of @dfn{font families} and @dfn{font styles}. The fonts are
8271 specified as the concatenation of the font family and style. Specifying
8272 a font without the family part causes @code{gtroff} to use that style of
8275 @cindex PostScript fonts
8276 @cindex fonts, PostScript
8277 Currently, fonts for the devices @option{-Tps}, @option{-Tdvi}, and
8278 @option{-Tlbp} are set up to this mechanism.
8279 By default, @code{gtroff} uses the Times family with the four styles
8280 @samp{R}, @samp{I}, @samp{B}, and @samp{BI}.
8282 This way, it is possible to use the basic four fonts and to select a
8283 different font family on the command line (@pxref{Groff Options}).
8285 @DefreqList {fam, [@Var{family}]}
8287 @DefescItem {\\F, , f, }
8288 @DefescItem {\\F, @lparen{}, fm, }
8289 @DefescItem {\\F, @lbrack{}, family, @rbrack}
8290 @DefregListEnd {.fn}
8291 @cindex changing font family (@code{fam}, @code{\F})
8292 @cindex font family, changing (@code{fam}, @code{\F})
8293 Switch font family to @var{family} (one-character name@tie{}@var{f},
8294 two-character name @var{fm}). If no argument is given, switch
8295 back to the previous font family. Use @code{\F[]} to do this with the
8296 escape. Note that @code{\FP} doesn't work; it selects font family
8299 The value at start-up is @samp{T}.
8300 The current font family is available in the read-only number register
8301 @samp{.fam} (this is a string-valued register); it is associated with
8302 the current environment.
8306 .fam H \" helvetica family
8307 spam, \" used font is family H + style R = HR
8308 .ft B \" family H + style B = font HB
8310 .fam T \" times family
8311 spam, \" used font is family T + style B = TB
8312 .ft AR \" font AR (not a style)
8314 .ft R \" family T + style R = font TR
8318 Note that @code{\F} doesn't produce an input token in @code{gtroff}.
8319 As a consequence, it can be used in requests like @code{mc} (which
8320 expects a single character as an argument) to change the font family on
8327 The @samp{.fn} register contains the current @dfn{real font name}
8328 of the current font.
8329 This is a string-valued register.
8330 If the current font is a style, the value of @code{\n[.fn]}
8331 is the proper concatenation of family and style name.
8334 @Defreq {sty, n style}
8335 @cindex changing font style (@code{sty})
8336 @cindex font style, changing (@code{sty})
8337 @cindex @code{cs} request, and font styles
8338 @cindex @code{bd} request, and font styles
8339 @cindex @code{tkf} request, and font styles
8340 @cindex @code{uf} request, and font styles
8341 @cindex @code{fspecial} request, and font styles
8342 Associate @var{style} with font position@tie{}@var{n}. A font position
8343 can be associated either with a font or with a style. The current
8344 font is the index of a font position and so is also either a font or a
8345 style. If it is a style, the font that is actually used is the font
8346 which name is the concatenation of the name of the current
8347 family and the name of the current style. For example, if the current
8348 font is@tie{}1 and font position@tie{}1 is associated with style
8349 @samp{R} and the current font family is @samp{T}, then font
8350 @samp{TR} will be used. If the current font is not a style, then the
8351 current family is ignored. If the requests @code{cs}, @code{bd},
8352 @code{tkf}, @code{uf}, or @code{fspecial} are applied to a style,
8353 they will instead be applied to the member of the current family
8354 corresponding to that style.
8356 @var{n}@tie{}must be a non-negative integer value.
8360 The default family can be set with the @option{-f} option
8361 (@pxref{Groff Options}). The @code{styles} command in the @file{DESC}
8362 file controls which font positions (if any) are initially associated
8363 with styles rather than fonts. For example, the default setting for
8364 @sc{PostScript} fonts
8380 @code{fam} and @code{\F} always check whether the current font position
8381 is valid; this can give surprising results if the current font position is
8382 associated with a style.
8384 In the following example, we want to access the @sc{PostScript} font
8385 @code{FooBar} from the font family @code{Foo}:
8390 @result{} warning: can't find font `FooR'
8394 The default font position at start-up is@tie{}1; for the
8395 @sc{PostScript} device, this is associated with style @samp{R}, so
8396 @code{gtroff} tries to open @code{FooR}.
8398 A solution to this problem is to use a dummy font like the following:
8401 .fp 0 dummy TR \" set up dummy font at position 0
8402 .sty \n[.fp] Bar \" register style `Bar'
8403 .ft 0 \" switch to font at position 0
8404 .fam Foo \" activate family `Foo'
8405 .ft Bar \" switch to font `FooBar'
8408 @xref{Font Positions}.
8411 @c ---------------------------------------------------------------------
8413 @node Font Positions, Using Symbols, Font Families, Fonts and Symbols
8414 @subsection Font Positions
8415 @cindex font positions
8416 @cindex positions, font
8418 For the sake of old phototypesetters and compatibility with old versions
8419 of @code{troff}, @code{gtroff} has the concept of font @dfn{positions},
8420 on which various fonts are mounted.
8422 @DefreqList {fp, pos font [@Var{external-name}]}
8424 @DefregListEnd {.fp}
8425 @cindex mounting font (@code{fp})
8426 @cindex font, mounting (@code{fp})
8427 Mount font @var{font} at position @var{pos} (which must be a
8428 non-negative integer). This numeric position can then be referred to
8429 with font changing commands. When @code{gtroff} starts it is using
8430 font position@tie{}1 (which must exist; position@tie{}0 is unused
8431 usually at start-up).
8433 @cindex font position register (@code{.f})
8434 The current font in use, as a font position, is available in the
8435 read-only number register @samp{.f}. This can be useful to remember the
8436 current font for later recall. It is associated with the current
8437 environment (@pxref{Environments}).
8440 .nr save-font \n[.f]
8442 ... text text text ...
8446 @cindex next free font position register (@code{.fp})
8447 The number of the next free font position is available in the read-only
8448 number register @samp{.fp}. This is useful when mounting a new font,
8452 .fp \n[.fp] NEATOFONT
8455 @pindex DESC@r{, and font mounting}
8456 Fonts not listed in the @file{DESC} file are automatically mounted on
8457 the next available font position when they are referenced. If a font
8458 is to be mounted explicitly with the @code{fp} request on an unused
8459 font position, it should be mounted on the first unused font position,
8460 which can be found in the @code{.fp} register. Although @code{gtroff}
8461 does not enforce this strictly, it is not allowed to mount a font at a
8462 position whose number is much greater (approx.@: 1000 positions) than
8463 that of any currently used position.
8465 The @code{fp} request has an optional third argument. This argument
8466 gives the external name of the font, which is used for finding the font
8467 description file. The second argument gives the internal name of the
8468 font which is used to refer to the font in @code{gtroff} after it has
8469 been mounted. If there is no third argument then the internal name is
8470 used as the external name. This feature makes it possible to use
8471 fonts with long names in compatibility mode.
8474 Both the @code{ft} request and the @code{\f} escape have alternative
8475 syntax forms to access font positions.
8477 @DefreqList {ft, nnn}
8478 @DefescItem {\\f, , n, }
8479 @DefescItem {\\f, @lparen{}, nn, }
8480 @DefescListEnd {\\f, @lbrack{}, nnn, @rbrack}
8481 @cindex changing font position (@code{\f})
8482 @cindex font position, changing (@code{\f})
8483 @cindex @code{sty} request, and font positions
8484 @cindex @code{fam} request, and font positions
8485 @cindex @code{\F}, and font positions
8489 Change the current font position to @var{nnn} (one-digit
8490 position@tie{}@var{n}, two-digit position @var{nn}), which must be a
8491 non-negative integer.
8493 If @var{nnn} is associated with a style (as set with the @code{sty}
8494 request or with the @code{styles} command in the @file{DESC} file), use
8495 it within the current font family (as set with the @code{fam} request,
8496 the @code{\F} escape, or with the @code{family} command in the @file{DESC}
8503 .ft \" switch back to font 1
8507 this is font 1 again
8510 @xref{Changing Fonts}, for the standard syntax form.
8513 @c ---------------------------------------------------------------------
8515 @node Using Symbols, Special Fonts, Font Positions, Fonts and Symbols
8516 @subsection Using Symbols
8517 @cindex using symbols
8518 @cindex symbols, using
8523 A @dfn{glyph} is a graphical representation of a @dfn{character}.
8524 While a character is an abstract entity containing semantic
8525 information, a glyph is something which can be actually seen on screen
8526 or paper. It is possible that a character has multiple glyph
8527 representation forms (for example, the character `A' can be either
8528 written in a roman or an italic font, yielding two different glyphs);
8529 sometimes more than one character maps to a single glyph (this is a
8530 @dfn{ligature} -- the most common is `fi').
8533 @cindex special fonts
8536 @cindex @code{special} request, and glyph search order
8537 @cindex @code{fspecial} request, and glyph search order
8538 A @dfn{symbol} is simply a named glyph. Within @code{gtroff}, all
8539 glyph names of a particular font are defined in its font file. If the
8540 user requests a glyph not available in this font, @code{gtroff} looks
8541 up an ordered list of @dfn{special fonts}. By default, the
8542 @sc{PostScript} output device supports the two special fonts @samp{SS}
8543 (slanted symbols) and @samp{S} (symbols) (the former is looked up
8544 before the latter). Other output devices use different names for
8545 special fonts. Fonts mounted with the @code{fonts} keyword in the
8546 @file{DESC} file are globally available. To install additional
8547 special fonts locally (i.e.@: for a particular font), use the
8548 @code{fspecial} request.
8550 Here the exact rules how @code{gtroff} searches a given symbol:
8554 If the symbol has been defined with the @code{char} request, use it.
8555 This hides a symbol with the same name in the current font.
8558 Check the current font.
8561 If the symbol has been defined with the @code{fchar} request, use it.
8564 Check whether the current font has a font-specific list of special fonts;
8565 test all fonts in the order of appearance in the last @code{fspecial}
8566 call if appropriate.
8569 If the symbol has been defined with the @code{fschar} request for the
8570 current font, use it.
8573 Check all fonts in the order of appearance in the last @code{special}
8577 If the symbol has been defined with the @code{schar} request, use it.
8580 As a last resort, consult all fonts loaded up to now for special fonts
8581 and check them, starting with the lowest font number. Note that this can
8582 sometimes lead to surprising results since the @code{fonts} line in the
8583 @file{DESC} file often contains empty positions which are filled later
8584 on. For example, consider the following:
8591 This mounts font @code{foo} at font position@tie{}3. We assume that
8592 @code{FOO} is a special font, containing glyph @code{foo},
8593 and that no font has been loaded yet. The line
8600 makes font @code{BAZ} special only if font @code{BAR} is active. We
8601 further assume that @code{BAZ} is really a special font, i.e., the font
8602 description file contains the @code{special} keyword, and that it
8603 also contains glyph @code{foo} with a special shape fitting to font
8604 @code{BAR}. After executing @code{fspecial}, font @code{BAR} is loaded at
8605 font position@tie{}1, and @code{BAZ} at position@tie{}2.
8607 We now switch to a new font @code{XXX}, trying to access glyph @code{foo}
8608 which is assumed to be missing. There are neither font-specific special
8609 fonts for @code{XXX} nor any other fonts made special with the
8610 @code{special} request, so @code{gtroff} starts the search for special
8611 fonts in the list of already mounted fonts, with increasing font
8612 positions. Consequently, it finds @code{BAZ} before @code{FOO} even for
8613 @code{XXX} which is not the intended behaviour.
8616 @xref{Font Files}, and @ref{Special Fonts}, for more details.
8618 @cindex list of available glyphs (@cite{groff_char(7)} man page)
8619 @cindex available glyphs, list (@cite{groff_char(7)} man page)
8620 @cindex glyphs, available, list (@cite{groff_char(7)} man page)
8621 The list of available symbols is device dependent; see the
8622 @cite{groff_char(7)} man page for a complete list of all glyphs. For
8626 man -Tdvi groff_char > groff_char.dvi
8630 for a list using the default DVI fonts (not all versions of the
8631 @code{man} program support the @option{-T} option). If you want to
8632 use an additional macro package to change the used fonts, @code{groff}
8633 must be called directly:
8636 groff -Tdvi -mec -man groff_char.7 > groff_char.dvi
8639 @cindex composite glyph names
8640 @cindex glyph names, composite
8641 @cindex groff glyph list (GGL)
8642 @cindex GGL (groff glyph list)
8643 @cindex adobe glyph list (AGL)
8644 @cindex AGL (adobe glyph list)
8645 Glyph names not listed in groff_char(7) are derived algorithmically,
8646 using a simplified version of the Adobe Glyph List (AGL) algorithm
8648 @uref{http://partners.adobe.com/asn/developer/typeforum/unicodegn.html}.
8649 The (frozen) set of glyph names which can't be derived algorithmically
8650 is called @dfn{groff glyph list (GGL)}.
8654 A glyph for Unicode character U+@var{XXXX}[@var{X}[@var{X}]] which is
8655 not a composite character will be named
8656 @code{u@var{XXXX}@r{[}@var{X}@r{[}@var{X}@r{]]}}. @var{X} must be an
8657 uppercase hexadecimal digit. Examples: @code{u1234}, @code{u008E},
8658 @code{u12DB8}. The largest Unicode value is 0x10FFFF. There must be at
8659 least four @code{X} digits; if necessary, add leading zeroes (after the
8660 @samp{u}). No zero padding is allowed for character codes greater than
8661 0xFFFF. Surrogates (i.e., Unicode values greater than 0xFFFF
8662 represented with character codes from the surrogate area U+D800-U+DFFF)
8663 are not allowed too.
8666 A glyph representing more than a single input character will be named
8669 @samp{u} @var{component1} @samp{_} @var{component2} @samp{_} @var{component3} @dots{}
8673 Example: @code{u0045_0302_0301}.
8675 For simplicity, all Unicode characters which are composites must be
8676 decomposed maximally (this is normalization form@tie{}D in the Unicode
8677 standard); for example, @code{u00CA_0301} is not a valid glyph name
8678 since U+00CA (@sc{latin capital letter e with circumflex}) can be
8679 further decomposed into U+0045 (@sc{latin capital letter e}) and U+0302
8680 (@sc{combining circumflex accent}). @code{u0045_0302_0301} is thus the
8681 glyph name for U+1EBE, @sc{latin capital letter e with circumflex and
8685 groff maintains a table to decompose all algorithmically derived glyph
8686 names which are composites itself. For example, @code{u0100} (@sc{latin
8687 letter a with macron}) will be automatically decomposed into
8688 @code{u0041_0304}. Additionally, a glyph name of the GGL is preferred
8689 to an algorithmically derived glyph name; groff also automatically does
8690 the mapping. Example: The glyph @code{u0045_0302} will be mapped to
8694 glyph names of the GGL can't be used in composite glyph names; for
8695 example, @code{^E_u0301} is invalid.
8698 @DefescList {\\, @lparen{}, nm, }
8699 @DefescItem {\\, @lbrack{}, name, @rbrack}
8700 @DefescListEnd {\\, @lbrack{}, component1 component2 @dots{}, @rbrack}
8701 Insert a symbol @var{name} (two-character name @var{nm}) or a composite
8702 glyph with component glyphs @var{component1}, @var{component2},
8703 @enddots{} There is no special syntax for one-character names -- the
8704 natural form @samp{\@var{n}} would collide with escapes.@footnote{Note
8705 that a one-character symbol is not the same as an input character, i.e.,
8706 the character @code{a} is not the same as @code{\[a]}. By default,
8707 @code{groff} defines only a single one-character symbol, @code{\[-]}; it
8708 is usually accessed as @code{\-}. On the other hand, @code{gtroff} has
8709 the special feature that @code{\[char@var{XXX}]} is the same as the
8710 input character with character code @var{XXX}. For example,
8711 @code{\[char97]} is identical to the letter @code{a} if @acronym{ASCII}
8712 encoding is active.}
8714 If @var{name} is undefined, a warning of type @samp{char} is generated,
8715 and the escape is ignored. @xref{Debugging}, for information about
8718 groff resolves @code{\[...]} with more than a single component as
8723 Any component which is found in the GGL will be converted to the
8724 @code{u@var{XXXX}} form.
8727 Any component @code{u@var{XXXX}} which is found in the list of
8728 decomposable glyphs will be decomposed.
8731 The resulting elements are then concatenated with @samp{_} inbetween,
8732 dropping the leading @samp{u} in all elements but the first.
8735 No check for the existence of any component (similar to @code{tr}
8736 request) will be done.
8742 @samp{A} maps to @code{u0041}, @samp{ho} maps to @code{u02DB}, thus the
8743 final glyph name would be @code{u0041_02DB}. Note this is not the
8744 expected result: The ogonek glyph @samp{ho} is a spacing ogonek, but for
8745 a proper composite a non-spacing ogonek (U+0328) is necessary. Looking
8746 into the file @file{composite.tmac} one can find @w{@samp{.composite ho
8747 u0328}} which changes the mapping of @samp{ho} while a composite glyph
8748 name is constructed, causing the final glyph name to be
8755 @samp{^E} maps to @code{u0045_0302}, thus the final glyph name is
8756 @code{u0045_0302_0301} in all forms (assuming proper calls of the
8757 @code{composite} request).
8760 It is not possible to define glyphs with names like @w{@samp{A ho}}
8761 within a groff font file. This is not really a limitation; instead, you
8762 have to define @code{u0041_0328}.
8765 @Defesc {\\C, ', xxx, '}
8766 @cindex named character (@code{\C})
8767 @cindex character, named (@code{\C})
8768 Typeset the glyph named @var{xxx}.@footnote{@code{\C} is actually a
8769 misnomer since it accesses an output glyph.} Normally it is more
8770 convenient to use @code{\[@var{xxx}]}, but @code{\C} has the advantage
8771 that it is compatible with newer versions of @acronym{AT&T}
8772 @code{troff} and is available in compatibility mode.
8775 @Defreq {composite, from to}
8776 @pindex composite.tmac
8777 Map glyph name @var{from} to glyph name @var{to} if it is used in
8778 @code{\[...]} with more than one component. See above for examples.
8780 This mapping is based on glyph names only; no check for the existence of
8781 either glyph is done.
8783 A set of default mappings for many accents can be found in the file
8784 @file{composite.tmac} which is loaded at start-up.
8787 @Defesc {\\N, ', n, '}
8788 @cindex numbered glyph (@code{\N})
8789 @cindex glyph, numbered (@code{\N})
8790 @cindex @code{char} request, used with @code{\N}
8792 Typeset the glyph with code@tie{}@var{n} in the current font
8793 (@code{n}@tie{}is @strong{not} the input character code). The
8794 number @var{n}@tie{}can be any non-negative decimal integer. Most devices
8795 only have glyphs with codes between 0 and@tie{}255; the Unicode
8796 output device uses codes in the range 0--65535. If the current
8797 font does not contain a glyph with that code, special fonts are
8798 @emph{not} searched. The @code{\N} escape sequence can be
8799 conveniently used in conjunction with the @code{char} request:
8802 .char \[phone] \f[ZD]\N'37'
8807 @cindex unnamed glyphs
8808 @cindex glyphs, unnamed
8809 The code of each glyph is given in the fourth column in the font
8810 description file after the @code{charset} command. It is possible to
8811 include unnamed glyphs in the font description file by using a
8812 name of @samp{---}; the @code{\N} escape sequence is the only way to
8815 No kerning is applied to glyphs accessed with @code{\N}.
8818 Some escape sequences directly map onto special glyphs.
8821 This is a backslash followed by the apostrophe character, @acronym{ASCII}
8822 character @code{0x27} (@acronym{EBCDIC} character @code{0x7D}). The same
8823 as @code{\[aa]}, the acute accent.
8827 This is a backslash followed by @acronym{ASCII} character @code{0x60}
8828 (@acronym{EBCDIC} character @code{0x79} usually). The same as
8829 @code{\[ga]}, the grave accent.
8833 This is the same as @code{\[-]}, the minus sign in the current font.
8836 @Defreq {cflags, n c1 c2 @dots{}}
8837 @cindex glyph properties (@code{cflags})
8838 @cindex character properties (@code{cflags})
8839 @cindex properties of glyphs (@code{cflags})
8840 @cindex properties of characters (@code{cflags})
8841 Input characters and symbols have certain properties associated
8842 with it.@footnote{Note that the output glyphs themselves don't have
8843 such properties. For @code{gtroff}, a glyph is a numbered box with
8844 a given width, depth, and height, nothing else. All manipulations
8845 with the @code{cflags} request work on the input level.} These
8846 properties can be modified with the @code{cflags} request. The
8847 first argument is the sum of the desired flags and the remaining
8848 arguments are the characters or symbols to have those properties.
8849 It is possible to omit the spaces between the characters or symbols.
8853 @cindex end-of-sentence characters
8854 @cindex characters, end-of-sentence
8855 The character ends sentences (initially characters @samp{.?!} have this
8859 @cindex hyphenating characters
8860 @cindex characters, hyphenation
8861 Lines can be broken before the character (initially no characters have
8865 @cindex @code{hy} glyph, and @code{cflags}
8866 @cindex @code{em} glyph, and @code{cflags}
8867 Lines can be broken after the character (initially the character
8868 @samp{-} and the symbols @samp{\[hy]} and @samp{\[em]} have this property).
8871 @cindex overlapping characters
8872 @cindex characters, overlapping
8873 @cindex @code{ul} glyph, and @code{cflags}
8874 @cindex @code{rn} glyph, and @code{cflags}
8875 @cindex @code{ru} glyph, and @code{cflags}
8876 @cindex @code{radicalex} glyph, and @code{cflags}
8877 @cindex @code{sqrtex} glyph, and @code{cflags}
8878 The character overlaps horizontally (initially the symbols
8879 @samp{\[ul]}, @samp{\[rn]}, @samp{\[ru]}, @samp{\[radicalex}, and
8880 @samp{\[sqrtex]} have this property).
8883 @cindex @code{br} glyph, and @code{cflags}
8884 The character overlaps vertically (initially symbol @samp{\[br]} has
8888 @cindex transparent characters
8889 @cindex character, transparent
8890 @cindex @code{"}, at end of sentence
8891 @cindex @code{'}, at end of sentence
8892 @cindex @code{)}, at end of sentence
8893 @cindex @code{]}, at end of sentence
8894 @cindex @code{*}, at end of sentence
8895 @cindex @code{dg} glyph, at end of sentence
8896 @cindex @code{rq} glyph, at end of sentence
8897 An end-of-sentence character followed by any number of characters with
8898 this property is treated as the end of a sentence if followed by a
8899 newline or two spaces; in other words the character is
8900 @dfn{transparent} for the purposes of end-of-sentence recognition --
8901 this is the same as having a zero space factor in @TeX{} (initially
8902 characters @samp{"')]*} and the symbols @samp{\[dg]} and @samp{\[rq]} have
8907 @DefreqList {char, g [@Var{string}]}
8908 @DefreqItem {fchar, g [@Var{string}]}
8909 @DefreqItem {fschar, f g [@Var{string}]}
8910 @DefreqListEnd {schar, g [@Var{string}]}
8911 @cindex defining character (@code{char})
8912 @cindex defining fallback character (@code{fchar}, @code{fschar}, @code{schar})
8913 @cindex character, defining (@code{char})
8914 @cindex character, defining fallback (@code{fchar}, @code{fschar}, @code{schar})
8915 @cindex fallback character, defining (@code{fchar}, @code{fschar}, @code{schar})
8916 @cindex creating new characters (@code{char})
8917 @cindex defining symbol (@code{char})
8918 @cindex symbol, defining (@code{char})
8919 @cindex defining glyph (@code{char})
8920 @cindex glyph, defining (@code{char})
8921 @cindex escape character, while defining glyph
8922 @cindex character, escape, while defining glyph
8923 @cindex @code{tr} request, and glyph definitions
8924 @cindex @code{cp} request, and glyph definitions
8925 @cindex @code{rc} request, and glyph definitions
8926 @cindex @code{lc} request, and glyph definitions
8927 @cindex @code{\l}, and glyph definitions
8928 @cindex @code{\L}, and glyph definitions
8929 @cindex @code{\&}, and glyph definitions
8930 @cindex @code{\e}, and glyph definitions
8931 @cindex @code{hcode} request, and glyph definitions
8932 Define a new glyph@tie{}@var{g} to be @var{string} (which can be
8933 empty).@footnote{@code{char} is a misnomer since an output glyph is
8934 defined.} Every time glyph@tie{}@var{g} needs to be printed,
8935 @var{string} is processed in a temporary environment and the result is
8936 wrapped up into a single object. Compatibility mode is turned off and
8937 the escape character is set to @samp{\} while @var{string} is being
8938 processed. Any emboldening, constant spacing or track kerning is
8939 applied to this object rather than to individual characters in
8942 A glyph defined by these requests can be used just
8943 like a normal glyph provided by the output device. In particular,
8944 other characters can be translated to it with the @code{tr} or
8945 @code{trin} requests; it can be made the leader character by the
8946 @code{lc} request; repeated patterns can be drawn with the glyph
8947 using the @code{\l} and @code{\L} escape sequences; words containing
8948 the glyph can be hyphenated correctly if the @code{hcode} request
8949 is used to give the glyph's symbol a hyphenation code.
8951 There is a special anti-recursion feature: Use of @code{g} within
8952 the glyph's definition is handled like normal characters and symbols
8953 not defined with @code{char}.
8955 Note that the @code{tr} and @code{trin} requests take precedence if
8956 @code{char} accesses the same symbol.
8970 The @code{fchar} request defines a fallback glyph:
8971 @code{gtroff} only checks for glyphs defined with @code{fchar}
8972 if it cannot find the glyph in the current font.
8973 @code{gtroff} carries out this test before checking special fonts.
8975 @code{fschar} defines a fallback glyph for font@tie{}@var{f}: @code{gtroff}
8976 checks for glyphs defined with @code{fschar} after the list of fonts
8977 declared as font-specific special fonts with the @code{fspecial} request,
8978 but before the list of fonts declared as global special fonts with the
8979 @code{special} request.
8981 Finally, the @code{schar} request defines a global fallback glyph:
8982 @code{gtroff} checks for glyphs defined with @code{schar} after the list
8983 of fonts declared as global special fonts with the @code{special} request,
8984 but before the already mounted special fonts.
8986 @xref{Using Symbols}, for a detailed description of the glyph
8987 searching mechanism in @code{gtroff}.
8990 @DefreqList {rchar, c1 c2 @dots{}}
8991 @DefreqListEnd {rfschar, f c1 c2 @dots{}}
8992 @cindex removing glyph definition (@code{rchar}, @code{rfschar})
8993 @cindex glyph, removing definition (@code{rchar}, @code{rfschar})
8994 @cindex fallback glyph, removing definition (@code{rchar}, @code{rfschar})
8995 Remove the definitions of glyphs @var{c1}, @var{c2},@tie{}@enddots{}
8996 This undoes the effect of a @code{char}, @code{fchar}, or
8997 @code{schar} request.
8999 It is possible to omit the whitespace between arguments.
9001 The request @code{rfschar} removes glyph definitions defined with
9002 @code{fschar} for glyph@tie{}f.
9005 @xref{Special Characters}.
9007 @c ---------------------------------------------------------------------
9009 @node Special Fonts, Artificial Fonts, Using Symbols, Fonts and Symbols
9010 @subsection Special Fonts
9011 @cindex special fonts
9012 @cindex fonts, special
9014 Special fonts are those that @code{gtroff} searches
9015 when it cannot find the requested glyph in the current font.
9016 The Symbol font is usually a special font.
9018 @code{gtroff} provides the following two requests to add more special
9019 fonts. @xref{Using Symbols}, for a detailed description of the glyph
9020 searching mechanism in @code{gtroff}.
9022 Usually, only non-TTY devices have special fonts.
9024 @DefreqList {special, [@Var{s1} @Var{s2} @dots{}]}
9025 @DefreqListEnd {fspecial, f [@Var{s1} @Var{s2} @dots{}]}
9028 Use the @code{special} request to define special fonts. Initially, this
9031 Use the @code{fspecial} request to designate special fonts only when
9032 font@tie{}@var{f} is active. Initially, this list is empty.
9034 Previous calls to @code{special} or @code{fspecial} are overwritten;
9035 without arguments, the particular list of special fonts is set to empty.
9036 Special fonts are searched in the order they appear as arguments.
9038 All fonts which appear in a call to @code{special} or @code{fspecial} are
9041 @xref{Using Symbols}, for the exact search order of glyphs.
9044 @c ---------------------------------------------------------------------
9046 @node Artificial Fonts, Ligatures and Kerning, Special Fonts, Fonts and Symbols
9047 @subsection Artificial Fonts
9048 @cindex artificial fonts
9049 @cindex fonts, artificial
9051 There are a number of requests and escapes for artificially creating
9052 fonts. These are largely vestiges of the days when output devices
9053 did not have a wide variety of fonts, and when @code{nroff} and
9054 @code{troff} were separate programs. Most of them are no longer
9055 necessary in GNU @code{troff}. Nevertheless, they are supported.
9057 @DefescList {\\H, ', height, '}
9058 @DefescItem {\\H, ', @t{+}height, '}
9059 @DefescItem {\\H, ', @t{-}height, '}
9060 @DefregListEnd {.height}
9061 @cindex changing the font height (@code{\H})
9062 @cindex font height, changing (@code{\H})
9063 @cindex height, font, changing (@code{\H})
9064 Change (increment, decrement) the height of the current font, but not
9065 the width. If @var{height} is zero, restore the original height.
9066 Default scaling indicator is @samp{z}.
9068 The read-only number register @code{.height} contains the font height as
9071 Currently, only the @option{-Tps} device supports this feature.
9073 Note that @code{\H} doesn't produce an input token in @code{gtroff}.
9074 As a consequence, it can be used in requests like @code{mc} (which
9075 expects a single character as an argument) to change the font on
9082 In compatibility mode, @code{gtroff} behaves differently: If an
9083 increment or decrement is used, it is always taken relative to the
9084 current point size and not relative to the previously selected font
9089 \H'+5'test \H'+5'test
9093 prints the word @samp{test} twice with the same font height (five
9094 points larger than the current font size).
9097 @DefescList {\\S, ', slant, '}
9098 @DefregListEnd {.slant}
9099 @cindex changing the font slant (@code{\S})
9100 @cindex font slant, changing (@code{\S})
9101 @cindex slant, font, changing (@code{\S})
9102 Slant the current font by @var{slant} degrees. Positive values slant
9103 to the right. Only integer values are possible.
9105 The read-only number register @code{.slant} contains the font slant as
9108 Currently, only the @option{-Tps} device supports this feature.
9110 Note that @code{\S} doesn't produce an input token in @code{gtroff}.
9111 As a consequence, it can be used in requests like @code{mc} (which
9112 expects a single character as an argument) to change the font on
9119 This request is incorrectly documented in the original @acronym{UNIX}
9120 troff manual; the slant is always set to an absolute value.
9123 @Defreq {ul, [@Var{lines}]}
9124 @cindex underlining (@code{ul})
9125 The @code{ul} request normally underlines subsequent lines if a TTY
9126 output device is used. Otherwise, the lines are printed in italics
9127 (only the term `underlined' is used in the following). The single
9128 argument is the number of input lines to be underlined; with no
9129 argument, the next line is underlined. If @var{lines} is zero or
9130 negative, stop the effects of @code{ul} (if it was active). Requests
9131 and empty lines do not count for computing the number of underlined
9132 input lines, even if they produce some output like @code{tl}. Lines
9133 inserted by macros (e.g.@: invoked by a trap) do count.
9135 At the beginning of @code{ul}, the current font is stored and the
9136 underline font is activated. Within the span of a @code{ul} request,
9137 it is possible to change fonts, but after the last line affected by
9138 @code{ul} the saved font is restored.
9140 This number of lines still to be underlined is associated with the
9141 current environment (@pxref{Environments}). The underline font can be
9142 changed with the @code{uf} request.
9144 @c XXX @xref should be changed to grotty
9146 @c @xref{Troff and Nroff Mode}, for a discussion how underlining is
9147 @c implemented in for TTY output devices, and which problems can arise.
9149 The @code{ul} request does not underline spaces.
9152 @Defreq {cu, [@Var{lines}]}
9153 @cindex continuous underlining (@code{cu})
9154 @cindex underlining, continuous (@code{cu})
9155 The @code{cu} request is similar to @code{ul} but underlines spaces as
9156 well (if a TTY output device is used).
9160 @cindex underline font (@code{uf})
9161 @cindex font for underlining (@code{uf})
9162 Set the underline font (globally) used by @code{ul} and @code{cu}. By
9163 default, this is the font at position@tie{}2. @var{font} can be either
9164 a non-negative font position or the name of a font.
9167 @DefreqList {bd, font [@Var{offset}]}
9168 @DefreqItem {bd, font1 font2 [@Var{offset}]}
9170 @cindex imitating bold face (@code{bd})
9171 @cindex bold face, imitating (@code{bd})
9172 Artificially create a bold font by printing each glyph twice,
9175 Two syntax forms are available.
9179 Imitate a bold font unconditionally. The first argument specifies the
9180 font to embolden, and the second is the number of basic units, minus
9181 one, by which the two glyphs are offset. If the second argument is
9182 missing, emboldening is turned off.
9184 @var{font} can be either a non-negative font position or the name of a
9187 @var{offset} is available in the @code{.b} read-only register if a
9188 special font is active; in the @code{bd} request, its default unit is
9191 @cindex @code{fspecial} request, and imitating bold
9193 @cindex embolding of special fonts
9194 @cindex special fonts, emboldening
9196 Imitate a bold form conditionally. Embolden @var{font1} by
9197 @var{offset} only if font @var{font2} is the current font. This
9198 command can be issued repeatedly to set up different emboldening
9199 values for different current fonts. If the second argument is
9200 missing, emboldening is turned off for this particular current font.
9202 This affects special fonts only (either set up with the @code{special}
9203 command in font files or with the @code{fspecial} request).
9207 @Defreq {cs, font [@Var{width} [@Var{em-size}]]}
9208 @cindex constant glyph space mode (@code{cs})
9209 @cindex mode for constant glyph space (@code{cs})
9210 @cindex glyph, constant space
9211 @cindex @code{ps} request, and constant glyph space mode
9212 Switch to and from @dfn{constant glyph space mode}. If activated, the
9213 width of every glyph is @math{@var{width}/36} ems. The em size is
9214 given absolutely by @var{em-size}; if this argument is missing, the em
9215 value is taken from the current font size (as set with the @code{ps}
9216 request) when the font is effectively in use. Without second and
9217 third argument, constant glyph space mode is deactivated.
9219 Default scaling indicator for @var{em-size} is @samp{z}; @var{width} is
9223 @c ---------------------------------------------------------------------
9225 @node Ligatures and Kerning, , Artificial Fonts, Fonts and Symbols
9226 @subsection Ligatures and Kerning
9227 @cindex ligatures and kerning
9228 @cindex kerning and ligatures
9230 Ligatures are groups of characters that are run together, i.e, producing
9231 a single glyph. For example, the letters `f' and `i' can form a
9232 ligature `fi' as in the word `file'. This produces a cleaner look
9233 (albeit subtle) to the printed output. Usually, ligatures are not
9234 available in fonts for TTY output devices.
9236 Most @sc{PostScript} fonts support the fi and fl ligatures. The C/A/T
9237 typesetter that was the target of @acronym{AT&T} @code{troff} also
9238 supported `ff', `ffi', and `ffl' ligatures. Advanced typesetters or
9239 `expert' fonts may include ligatures for `ft' and `ct', although GNU
9240 @code{troff} does not support these (yet).
9242 Only the current font is checked for ligatures and kerns; neither special
9243 fonts nor entities defined with the @code{char} request (and its siblings)
9244 are taken into account.
9246 @DefreqList {lg, [@Var{flag}]}
9247 @DefregListEnd {.lg}
9248 @cindex activating ligatures (@code{lg})
9249 @cindex ligatures, activating (@code{lg})
9250 @cindex ligatures enabled register (@code{.lg})
9251 Switch the ligature mechanism on or off; if the parameter is non-zero
9252 or missing, ligatures are enabled, otherwise disabled. Default is on.
9253 The current ligature mode can be found in the read-only number register
9254 @code{.lg} (set to 1 or@tie{}2 if ligatures are enabled, 0@tie{}otherwise).
9256 Setting the ligature mode to@tie{}2 enables the two-character ligatures
9257 (fi, fl, and ff) and disables the three-character ligatures (ffi and
9261 @dfn{Pairwise kerning} is another subtle typesetting mechanism that
9262 modifies the distance between a glyph pair to improve readability.
9263 In most cases (but not always) the distance is decreased.
9265 For example, compare the combination of the letters `V' and `A'. With
9266 kerning, `VA' is printed. Without kerning it appears as `V@w{}A'.
9268 Typewriter-like fonts and fonts for terminals where all glyphs
9269 have the same width don't use kerning.
9271 @DefreqList {kern, [@Var{flag}]}
9272 @DefregListEnd {.kern}
9273 @cindex activating kerning (@code{kern})
9274 @cindex kerning, activating (@code{kern})
9275 @cindex kerning enabled register (@code{.kern})
9276 Switch kerning on or off. If the parameter is non-zero or missing,
9277 enable pairwise kerning, otherwise disable it. The read-only number
9278 register @code{.kern} is set to@tie{}1 if pairwise kerning is enabled,
9281 @cindex zero width space character (@code{\&})
9282 @cindex character, zero width space (@code{\&})
9283 @cindex space character, zero width (@code{\&})
9284 If the font description file contains pairwise kerning information,
9285 glyphs from that font are kerned. Kerning between two glyphs
9286 can be inhibited by placing @code{\&} between them: @samp{V\&A}.
9288 @xref{Font File Format}.
9291 @cindex track kerning
9292 @cindex kerning, track
9293 @dfn{Track kerning} expands or reduces the space between glyphs.
9294 This can be handy, for example, if you need to squeeze a long word
9295 onto a single line or spread some text to fill a narrow column. It
9296 must be used with great care since it is usually considered bad
9297 typography if the reader notices the effect.
9299 @Defreq {tkf, f s1 n1 s2 n2}
9300 @cindex activating track kerning (@code{tkf})
9301 @cindex track kerning, activating (@code{tkf})
9302 Enable track kerning for font@tie{}@var{f}. If the current font
9303 is@tie{}@var{f} the width of every glyph is increased by an amount
9304 between @var{n1} and @var{n2} (@var{n1}, @var{n2} can be negative); if
9305 the current point size is less than or equal to @var{s1} the width is
9306 increased by @var{n1}; if it is greater than or equal to @var{s2} the
9307 width is increased by @var{n2}; if the point size is greater than or
9308 equal to @var{s1} and less than or equal to @var{s2} the increase in
9309 width is a linear function of the point size.
9311 The default scaling indicator is @samp{z} for @var{s1} and @var{s2},
9312 @samp{p} for @var{n1} and @var{n2}.
9314 Note that the track kerning amount is added even to the rightmost glyph
9315 in a line; for large values it is thus recommended to increase the line
9316 length by the same amount to compensate it.
9319 Sometimes, when typesetting letters of different fonts, more or less
9320 space at such boundaries are needed. There are two escapes to help
9324 @cindex italic correction (@code{\/})
9325 @cindex correction, italic (@code{\/})
9326 @cindex correction between italic and roman glyph (@code{\/}, @code{\,})
9327 @cindex roman glyph, correction after italic glyph (@code{\/})
9328 @cindex italic glyph, correction before roman glyph (@code{\/})
9329 @cindex glyph, italic correction (@code{\/})
9330 Increase the width of the preceding glyph so that the spacing
9331 between that glyph and the following glyph is correct if the
9332 following glyph is a roman glyph. For example, if an
9333 italic@tie{}@code{f} is immediately followed by a roman right
9334 parenthesis, then in many fonts the top right portion of the@tie{}@code{f}
9335 overlaps the top left of the right parenthesis. Use this escape
9336 sequence whenever an italic glyph is immediately followed by a
9337 roman glyph without any intervening space. This small amount of
9338 space is also called @dfn{italic correction}.
9344 @result{} {@it f}@r{)}
9346 @result{} @i{f}@r{)}
9352 @Defesc {\\\,, , , }
9353 @cindex left italic correction (@code{\,})
9354 @cindex correction, left italic (@code{\,})
9355 @cindex glyph, left italic correction (@code{\,})
9356 @cindex roman glyph, correction before italic glyph (@code{\,})
9357 @cindex italic glyph, correction after roman glyph (@code{\,})
9358 Modify the spacing of the following glyph so that the spacing
9359 between that glyph and the preceding glyph is correct if the
9360 preceding glyph is a roman glyph. Use this escape sequence
9361 whenever a roman glyph is immediately followed by an italic
9362 glyph without any intervening space. In analogy to above, this
9363 space could be called @dfn{left italic correction}, but this term
9370 @result{} @r{q}@i{f}
9372 @result{} @r{q}@math{@ptexcomma}@i{f}
9379 Insert a zero-width character, which is invisible. Its intended use
9380 is to stop interaction of a character with its surrounding.
9384 It prevents the insertion of extra space after an end-of-sentence
9390 @result{} Test. Test.
9393 @result{} Test. Test.
9397 It prevents interpretation of a control character at the beginning of
9402 @result{} warning: `Test' not defined
9408 It prevents kerning between two glyphs.
9416 @result{} @r{V@w{}A}
9422 It is needed to map an arbitrary character to nothing in the @code{tr}
9423 request (@pxref{Character Translations}).
9428 This escape is similar to @code{\&} except that it behaves like a
9429 character declared with the @code{cflags} request to be transparent
9430 for the purposes of an end-of-sentence character.
9432 Its main usage is in macro definitions to protect against arguments
9433 starting with a control character.
9445 @result{}This is a test.' This is a test.
9449 @result{}This is a test.' This is a test.
9454 @c =====================================================================
9456 @node Sizes, Strings, Fonts and Symbols, gtroff Reference
9462 @cindex size of type
9463 @cindex vertical spacing
9464 @cindex spacing, vertical
9465 @code{gtroff} uses two dimensions with each line of text, type size
9466 and vertical spacing. The @dfn{type size} is approximately the height
9467 of the tallest glyph.@footnote{This is usually the parenthesis.
9468 Note that in most cases the real dimensions of the glyphs in a font
9469 are @emph{not} related to its type size! For example, the standard
9470 @sc{PostScript} font families `Times Roman', `Helvetica', and
9471 `Courier' can't be used together at 10@dmn{pt}; to get acceptable
9472 output, the size of `Helvetica' has to be reduced by one point, and
9473 the size of `Courier' must be increased by one point.} @dfn{Vertical
9474 spacing} is the amount of space @code{gtroff} allows for a line of
9475 text; normally, this is about 20%@tie{}larger than the current type
9476 size. Ratios smaller than this can result in hard-to-read text;
9477 larger than this, it spreads the text out more vertically (useful for
9478 term papers). By default, @code{gtroff} uses 10@tie{}point type on
9479 12@tie{}point spacing.
9482 The difference between type size and vertical spacing is known, by
9483 typesetters, as @dfn{leading} (this is pronounced `ledding').
9486 * Changing Type Sizes::
9487 * Fractional Type Sizes::
9490 @c ---------------------------------------------------------------------
9492 @node Changing Type Sizes, Fractional Type Sizes, Sizes, Sizes
9493 @subsection Changing Type Sizes
9495 @DefreqList {ps, [@Var{size}]}
9496 @DefreqItem {ps, @t{+}@Var{size}}
9497 @DefreqItem {ps, @t{-}@Var{size}}
9498 @DefescItem {\\s, , size, }
9500 @cindex changing type sizes (@code{ps}, @code{\s})
9501 @cindex type sizes, changing (@code{ps}, @code{\s})
9502 @cindex point sizes, changing (@code{ps}, @code{\s})
9503 Use the @code{ps} request or the @code{\s} escape to change (increase,
9504 decrease) the type size (in points). Specify @var{size} as either an
9505 absolute point size, or as a relative change from the current size.
9506 The size@tie{}0, or no argument, goes back to the previous size.
9508 Default scaling indicator of @code{size} is @samp{z}. If @code{size}
9509 is zero or negative, it is set to 1@dmn{u}.
9511 @cindex type size registers (@code{.s}, @code{.ps})
9512 @cindex point size registers (@code{.s}, @code{.ps})
9513 The read-only number register @code{.s} returns the point size in
9514 points as a decimal fraction. This is a string. To get the point
9515 size in scaled points, use the @code{.ps} register instead.
9517 @code{.s} is associated with the current environment
9518 (@pxref{Environments}).
9525 wink, wink, \s+2nudge, nudge,\s+8 say no more!
9529 The @code{\s} escape may be called in a variety of ways. Much like
9530 other escapes there must be a way to determine where the argument ends
9531 and the text begins. Any of the following forms are valid:
9535 Set the point size to @var{n}@tie{}points. @var{n}@tie{}must be either
9536 0 or in the range 4 to@tie{}39.
9540 Increase or decrease the point size by @var{n}@tie{}points.
9541 @var{n}@tie{}must be exactly one digit.
9544 Set the point size to @var{nn}@tie{}points. @var{nn} must be exactly
9551 Increase or decrease the point size by @var{nn}@tie{}points. @var{nn}
9552 must be exactly two digits.
9555 Note that @code{\s} doesn't produce an input token in @code{gtroff}.
9556 As a consequence, it can be used in requests like @code{mc} (which
9557 expects a single character as an argument) to change the font on
9564 @xref{Fractional Type Sizes}, for yet another syntactical form of
9565 using the @code{\s} escape.
9568 @Defreq {sizes, s1 s2 @dots{} sn [0]}
9569 Some devices may only have certain permissible sizes, in which case
9570 @code{gtroff} rounds to the nearest permissible size.
9571 The @file{DESC} file specifies which sizes are permissible for the device.
9573 Use the @code{sizes} request to change the permissible sizes
9574 for the current output device.
9575 Arguments are in scaled points;
9576 the @code{sizescale} line in the
9577 @file{DESC} file for the output device
9578 provides the scaling factor.
9579 For example, if the scaling factor is 1000,
9580 then the value 12000 is 12@tie{}points.
9582 Each argument can be a single point size (such as @samp{12000}),
9583 or a range of sizes (such as @samp{4000-72000}).
9584 You can optionally end the list with a zero.
9587 @DefreqList {vs, [@Var{space}]}
9588 @DefreqItem {vs, @t{+}@Var{space}}
9589 @DefreqItem {vs, @t{-}@Var{space}}
9591 @cindex changing vertical line spacing (@code{vs})
9592 @cindex vertical line spacing, changing (@code{vs})
9593 @cindex vertical line spacing register (@code{.v})
9594 Change (increase, decrease) the vertical spacing by @var{space}. The
9595 default scaling indicator is @samp{p}.
9597 If @code{vs} is called without an argument, the vertical spacing is
9598 reset to the previous value before the last call to @code{vs}.
9600 @cindex @code{.V} register, and @code{vs}
9601 @code{gtroff} creates a warning of type @samp{range} if @var{space} is
9602 negative; the vertical spacing is then set to the vertical
9603 resolution (as given in the @code{.V} register).
9605 The read-only number register @code{.v} contains the current vertical
9606 spacing; it is associated with the current environment
9607 (@pxref{Environments}).
9610 @cindex vertical line spacing, effective value
9611 The effective vertical line spacing consists of four components.
9615 The vertical line spacing as set with the @code{vs} request.
9617 @cindex post-vertical line spacing
9618 @cindex line spacing, post-vertical (@code{pvs})
9620 The @dfn{post-vertical line spacing} as set with the @code{pvs} request.
9621 This is vertical space which will be added after a line has been
9624 @cindex extra pre-vertical line space (@code{\x})
9625 @cindex line space, extra pre-vertical (@code{\x})
9627 The @dfn{extra pre-vertical line space} as set with the @code{\x} request,
9628 using a negative value. This is vertical space which will be added once
9629 before the current line has been output.
9631 @cindex extra post-vertical line space (@code{\x})
9632 @cindex line space, extra post-vertical (@code{\x})
9634 The @dfn{extra post-vertical line space} as set with the @code{\x} request,
9635 using a positive value. This is vertical space which will be added once
9636 after the current line has been output.
9639 @cindex double-spacing (@code{vs}, @code{pvs})
9640 It is usually better to use @code{vs} or @code{pvs} instead of @code{ls}
9641 to produce double-spaced documents: @code{vs} and @code{pvs} have a finer
9642 granularity for the inserted vertical space compared to @code{ls};
9643 furthermore, certain preprocessors assume single-spacing.
9645 @xref{Manipulating Spacing}, for more details on the @code{\x} escape
9646 and the @code{ls} request.
9648 @DefreqList {pvs, [@Var{space}]}
9649 @DefreqItem {pvs, @t{+}@Var{space}}
9650 @DefreqItem {pvs, @t{-}@Var{space}}
9651 @DefregListEnd {.pvs}
9652 @cindex @code{ls} request, alternative to (@code{pvs})
9653 @cindex post-vertical line spacing, changing (@code{pvs})
9654 @cindex post-vertical line spacing register (@code{.pvs})
9655 Change (increase, decrease) the post-vertical spacing by
9656 @var{space}. The default scaling indicator is @samp{p}.
9658 If @code{pvs} is called without an argument, the post-vertical spacing is
9659 reset to the previous value before the last call to @code{pvs}.
9661 @code{gtroff} creates a warning of type @samp{range} if @var{space} is
9662 zero or negative; the vertical spacing is then set to zero.
9664 The read-only number register @code{.pvs} contains the current
9665 post-vertical spacing; it is associated with the current environment
9666 (@pxref{Environments}).
9669 @c ---------------------------------------------------------------------
9671 @node Fractional Type Sizes, , Changing Type Sizes, Sizes
9672 @subsection Fractional Type Sizes
9673 @cindex fractional type sizes
9674 @cindex fractional point sizes
9675 @cindex type sizes, fractional
9676 @cindex point sizes, fractional
9677 @cindex sizes, fractional
9679 @cindex @code{s} unit
9680 @cindex unit, @code{s}
9681 @cindex @code{z} unit
9682 @cindex unit, @code{z}
9683 @cindex @code{ps} request, with fractional type sizes
9684 @cindex @code{cs} request, with fractional type sizes
9685 @cindex @code{tkf} request, with fractional type sizes
9686 @cindex @code{\H}, with fractional type sizes
9687 @cindex @code{\s}, with fractional type sizes
9688 A @dfn{scaled point} is equal to @math{1/@var{sizescale}} points,
9689 where @var{sizescale} is specified in the @file{DESC} file (1@tie{}by
9690 default). There is a new scale indicator @samp{z} which has the
9691 effect of multiplying by @var{sizescale}. Requests and escape
9692 sequences in @code{gtroff} interpret arguments that represent a point
9693 size as being in units of scaled points, but they evaluate each such
9694 argument using a default scale indicator of @samp{z}. Arguments
9695 treated in this way are the argument to the @code{ps} request, the
9696 third argument to the @code{cs} request, the second and fourth
9697 arguments to the @code{tkf} request, the argument to the @code{\H}
9698 escape sequence, and those variants of the @code{\s} escape sequence
9699 that take a numeric expression as their argument (see below).
9701 For example, suppose @var{sizescale} is@tie{}1000; then a scaled point
9702 is equivalent to a millipoint; the request @w{@samp{.ps 10.25}} is
9703 equivalent to @w{@samp{.ps 10.25z}} and thus sets the point size to
9704 10250@tie{}scaled points, which is equal to 10.25@tie{}points.
9706 @code{gtroff} disallows the use of the @samp{z} scale indicator in
9707 instances where it would make no sense, such as a numeric
9708 expression whose default scale indicator was neither @samp{u} nor
9709 @samp{z}. Similarly it would make
9710 no sense to use a scaling indicator other than @samp{z} or @samp{u} in a
9711 numeric expression whose default scale indicator was @samp{z}, and so
9712 @code{gtroff} disallows this as well.
9714 There is also new scale indicator @samp{s} which multiplies by the
9715 number of units in a scaled point. So, for example, @samp{\n[.ps]s} is
9716 equal to @samp{1m}. Be sure not to confuse the @samp{s} and @samp{z}
9720 A read-only number register returning the point size in scaled points.
9722 @code{.ps} is associated with the current environment
9723 (@pxref{Environments}).
9727 @DefregListEnd {.sr}
9728 @cindex last-requested point size registers (@code{.psr}, @code{.sr})
9729 @cindex point size registers, last-requested (@code{.psr}, @code{.sr})
9730 @cindex @code{.ps} register, in comparison with @code{.psr}
9731 @cindex @code{.s} register, in comparison with @code{.sr}
9732 The last-requested point size in scaled points is contained in the
9733 @code{.psr} read-only number register. The last requested point size
9734 in points as a decimal fraction can be found in @code{.sr}. This is a
9735 string-valued read-only number register.
9737 Note that the requested point sizes are device-independent, whereas
9738 the values returned by the @code{.ps} and @code{.s} registers are not.
9739 For example, if a point size of 11@dmn{pt} is requested, and a
9740 @code{sizes} request (or a @code{sizescale} line in a @file{DESC} file)
9741 specifies 10.95@dmn{pt} instead, this value is actually used.
9743 Both registers are associated with the current environment
9744 (@pxref{Environments}).
9747 The @code{\s} escape has the following syntax for working with
9748 fractional type sizes:
9753 Set the point size to @var{n}@tie{}scaled points; @var{n}@tie{}is a numeric
9754 expression with a default scale indicator of @samp{z}.
9764 Increase or or decrease the point size by @var{n}@tie{}scaled points;
9765 @var{n}@tie{}is a numeric expression with a default scale indicator of
9772 @c =====================================================================
9774 @node Strings, Conditionals and Loops, Sizes, gtroff Reference
9778 @code{gtroff} has string variables, which are entirely for user
9779 convenience (i.e.@: there are no built-in strings exept @code{.T}, but
9780 even this is a read-write string variable).
9782 @DefreqList {ds, name [@Var{string}]}
9783 @DefreqItem {ds1, name [@Var{string}]}
9784 @DefescItem {\\*, , n, }
9785 @DefescItem {\\*, @lparen{}, nm, }
9786 @DefescListEnd {\\*, @lbrack{}, name arg1 arg2 @dots{}, @rbrack{}}
9787 @cindex string interpolation (@code{\*})
9788 @cindex string expansion (@code{\*})
9789 @cindex interpolation of strings (@code{\*})
9790 @cindex expansion of strings (@code{\*})
9791 @cindex string arguments
9792 @cindex arguments, of strings
9793 Define and access a string variable @var{name} (one-character
9794 name@tie{}@var{n}, two-character name @var{nm}). If @var{name} already
9795 exists, @code{ds} overwrites the previous definition. Only the syntax form
9796 using brackets can take arguments which are handled identically to
9797 macro arguments; the single exception is that a closing bracket as an
9798 argument must be enclosed in double quotes. @xref{Request and Macro
9799 Arguments}, and @ref{Parameters}.
9806 This is \*[foo nice].
9807 @result{} This is a nice test.
9810 The @code{\*} escape @dfn{interpolates} (expands in-place) a
9811 previously-defined string variable. To be more precise, the stored
9812 string is pushed onto the input stack which is then parsed by
9813 @code{gtroff}. Similar to number registers, it is possible to nest
9814 strings, i.e. string variables can be called within string variables.
9816 If the string named by the @code{\*} escape does not exist, it is
9817 defined as empty, and a warning of type @samp{mac} is emitted (see
9818 @ref{Debugging}, for more details).
9820 @cindex comments, with @code{ds}
9821 @cindex @code{ds} request, and comments
9822 @strong{Caution:} Unlike other requests, the second argument to the
9823 @code{ds} request takes up the entire line including trailing spaces.
9824 This means that comments on a line with such a request can introduce
9825 unwanted space into a string.
9828 .ds UX \s-1UNIX\s0\u\s-3tm\s0\d \" UNIX trademark
9832 Instead the comment should be put on another line or have the comment
9833 escape adjacent with the end of the string.
9836 .ds UX \s-1UNIX\s0\u\s-3tm\s0\d\" UNIX trademark
9839 @cindex trailing quotes
9840 @cindex quotes, trailing
9841 @cindex leading spaces with @code{ds}
9842 @cindex spaces with @code{ds}
9843 @cindex @code{ds} request, and leading spaces
9844 To produce leading space the string can be started with a double
9845 quote. No trailing quote is needed; in fact, any trailing quote is
9846 included in your string.
9849 .ds sign " Yours in a white wine sauce,
9852 @cindex multi-line strings
9853 @cindex strings, multi-line
9854 @cindex newline character, in strings, escaping
9855 @cindex escaping newline characters, in strings
9856 Strings are not limited to a single line of text. A string can span
9857 several lines by escaping the newlines with a backslash. The
9858 resulting string is stored @emph{without} the newlines.
9861 .ds foo lots and lots \
9862 of text are on these \
9866 It is not possible to have real newlines in a string. To put a single
9867 double quote character into a string, use two consecutive double quote
9870 The @code{ds1} request turns off compatibility mode
9871 while interpreting a string. To be more precise, a @dfn{compatibility
9872 save} input token is inserted at the beginning of the string, and a
9873 @dfn{compatibility restore} input token at the end.
9877 .ds aa The value of xxx is \\n[xxx].
9878 .ds1 bb The value of xxx ix \\n[xxx].
9883 @result{} warning: number register `[' not defined
9884 @result{} The value of xxx is 0xxx].
9886 @result{} The value of xxx ix 12345.
9889 @cindex name space, common, of macros, diversions, and strings
9890 @cindex common name space of macros, diversions, and strings
9891 @cindex macros, shared name space with strings and diversions
9892 @cindex strings, shared name space with macros and diversions
9893 @cindex diversions, shared name space with macros and strings
9894 Strings, macros, and diversions (and boxes) share the same name space.
9895 Internally, even the same mechanism is used to store them. This has
9896 some interesting consequences. For example, it is possible to call a
9897 macro with string syntax and vice versa.
9904 @result{} This is a funny test.
9906 .ds yyy a funny test
9909 @result{} This is a funny test.
9912 Diversions and boxes can be also called with string syntax.
9914 Another consequence is that you can copy one-line diversions or boxes
9922 .ds yyy This is \*[xxx]\c
9924 @result{} @r{This is a }@i{test}.
9928 As the previous example shows, it is possible to store formatted
9929 output in strings. The @code{\c} escape prevents the insertion of an
9930 additional blank line in the output.
9932 Copying diversions longer than a single output line produces
9942 .ds yyy This is \*[xxx]\c
9944 @result{} test This is a funny.
9947 Usually, it is not predictable whether a diversion contains one or
9948 more output lines, so this mechanism should be avoided. With
9949 @acronym{UNIX} @code{troff}, this was the only solution to strip off a
9950 final newline from a diversion. Another disadvantage is that the
9951 spaces in the copied string are already formatted, making them
9952 unstretchable. This can cause ugly results.
9954 @cindex stripping final newline in diversions
9955 @cindex diversion, stripping final newline
9956 @cindex final newline, stripping in diversions
9957 @cindex newline, final, stripping in diversions
9958 @cindex horizontal space, unformatting
9959 @cindex space, horizontal, unformatting
9960 @cindex unformatting horizontal space
9961 A clean solution to this problem is available in GNU @code{troff},
9962 using the requests @code{chop} to remove the final newline of a
9963 diversion, and @code{unformat} to make the horizontal spaces
9976 @result{} This is a funny test.
9979 @xref{Gtroff Internals}, for more information.
9982 @DefreqList {as, name [@Var{string}]}
9983 @DefreqListEnd {as1, name [@Var{string}]}
9984 @cindex appending to a string (@code{as})
9985 @cindex string, appending (@code{as})
9986 The @code{as} request is similar to @code{ds} but appends @var{string}
9987 to the string stored as @var{name} instead of redefining it. If
9988 @var{name} doesn't exist yet, it is created.
9991 .as sign " with shallots, onions and garlic,
9994 The @code{as1} request is similar to @code{as}, but compatibility mode
9995 is switched off while the appended string is interpreted. To be more
9996 precise, a @dfn{compatibility save} input token is inserted at the
9997 beginning of the appended string, and a @dfn{compatibility restore}
9998 input token at the end.
10001 Rudimentary string manipulation routines are given with the next two
10004 @Defreq {substring, str n1 [@Var{n2}]}
10005 @cindex substring (@code{substring})
10006 Replace the string named @var{str} with the substring
10007 defined by the indices @var{n1} and@tie{}@var{n2}. The first character
10008 in the string has index@tie{}0. If @var{n2} is omitted, it is taken to
10009 be equal to the string's length. If the index value @var{n1} or
10010 @var{n2} is negative, it is counted from the end of the
10011 string, going backwards: The last character has index@tie{}@minus{}1, the
10012 character before the last character has index@tie{}@minus{}2, etc.
10016 .substring xxx 1 -4
10022 @Defreq {length, reg str}
10023 @cindex length of a string (@code{length})
10024 @cindex string, length of (@code{length})
10025 Compute the number of characters of @var{str} and return it in the
10026 number register @var{reg}. If @var{reg} doesn't exist, it is created.
10027 @code{str} is read in copy mode.
10030 .ds xxx abcd\h'3i'efgh
10031 .length yyy \*[xxx]
10037 @Defreq {rn, xx yy}
10038 @cindex renaming request (@code{rn})
10039 @cindex request, renaming (@code{rn})
10040 @cindex renaming macro (@code{rn})
10041 @cindex macro, renaming (@code{rn})
10042 @cindex renaming string (@code{rn})
10043 @cindex string, renaming (@code{rn})
10044 @cindex renaming diversion (@code{rn})
10045 @cindex diversion, renaming (@code{rn})
10046 Rename the request, macro, diversion, or string @var{xx} to @var{yy}.
10050 @cindex removing request (@code{rm})
10051 @cindex request, removing (@code{rm})
10052 @cindex removing macro (@code{rm})
10053 @cindex macro, removing (@code{rm})
10054 @cindex removing string (@code{rm})
10055 @cindex string, removing (@code{rm})
10056 @cindex removing diversion (@code{rm})
10057 @cindex diversion, removing (@code{rm})
10058 Remove the request, macro, diversion, or string @var{xx}. @code{gtroff}
10059 treats subsequent invocations as if the object had never been defined.
10062 @Defreq {als, new old}
10063 @cindex alias, string, creating (@code{als})
10064 @cindex alias, macro, creating (@code{als})
10065 @cindex alias, diversion, creating (@code{als})
10066 @cindex creating alias, for string (@code{als})
10067 @cindex creating alias, for macro (@code{als})
10068 @cindex creating alias, for diversion (@code{als})
10069 @cindex string, creating alias (@code{als})
10070 @cindex macro, creating alias (@code{als})
10071 @cindex diversion, creating alias (@code{als})
10072 Create an alias named @var{new} for the request, string, macro, or
10073 diversion object named @var{old}. The new name and the old name are
10074 exactly equivalent (it is similar to a hard rather than a soft
10075 link). If @var{old} is undefined, @code{gtroff} generates a warning of
10076 type @samp{mac} and ignores the request.
10080 Remove (chop) the last character from the macro, string, or diversion
10081 named @var{xx}. This is useful for removing the newline from the end
10082 of diversions that are to be interpolated as strings. This command
10083 can be used repeatedly; see @ref{Gtroff Internals}, for details on
10084 nodes inserted additionally by @code{gtroff}.
10087 @xref{Identifiers}, and @ref{Comments}.
10090 @c =====================================================================
10092 @node Conditionals and Loops, Writing Macros, Strings, gtroff Reference
10093 @section Conditionals and Loops
10094 @cindex conditionals and loops
10095 @cindex loops and conditionals
10098 * Operators in Conditionals::
10103 @c ---------------------------------------------------------------------
10105 @node Operators in Conditionals, if-else, Conditionals and Loops, Conditionals and Loops
10106 @subsection Operators in Conditionals
10108 @cindex @code{if} request, operators to use with
10109 @cindex @code{while} request, operators to use with
10110 In @code{if} and @code{while} requests, there are several more
10111 operators available:
10116 True if the current page is even or odd numbered (respectively).
10119 True if the document is being processed in nroff mode (i.e., the
10120 @code{.nroff} command has been issued).
10123 True if the document is being processed in troff mode (i.e., the
10124 @code{.troff} command has been issued).
10127 Always false. This condition is for compatibility with other
10128 @code{troff} versions only.
10130 @item '@var{xxx}'@var{yyy}'
10131 True if the string @var{xxx} is equal to the string @var{yyy}. Other
10132 characters can be used in place of the single quotes; the same set of
10133 delimiters as for the @code{\D} escape is used (@pxref{Escapes}).
10134 @code{gtroff} formats the strings before being compared:
10145 The resulting motions, glyph sizes, and fonts have to
10146 match,@footnote{The created output nodes must be identical.
10147 @xref{Gtroff Internals}.} and not the individual motion, size, and
10148 font requests. In the previous example, @samp{|} and @samp{\fR|\fP}
10149 both result in a roman @samp{|} glyph with the same point size and
10150 at the same location on the page, so the strings are equal. If
10151 @samp{.ft@tie{}I} had been added before the @samp{.ie}, the result
10152 would be ``false'' because (the first) @samp{|} produces an italic
10153 @samp{|} rather than a roman one.
10156 True if there is a number register named @var{xxx}.
10159 True if there is a string, macro, diversion, or request named @var{xxx}.
10162 True if there is a color named @var{xxx}.
10165 True if there is a glyph @var{g} available@footnote{The name of this
10166 conditional operator is a misnomer since it tests names of output
10167 glyphs.}; @var{g} is either an @acronym{ASCII} character or a special
10168 character (@code{\(@var{gg}} or @code{\[@var{ggg}]}); the condition
10169 is also true if @var{g} has been defined by the @code{char} request.
10172 Note that these operators can't be combined with other operators like
10173 @samp{:} or @samp{&}; only a leading @samp{!} (without whitespace
10174 between the exclamation mark and the operator) can be used to negate
10186 A whitespace after @samp{!} always evaluates to zero (this bizarre
10187 behaviour is due to compatibility with @acronym{UNIX} @code{troff}).
10195 @result{} r xxx true
10198 It is possible to omit the whitespace before the argument to the
10199 @samp{r}, @samp{d}, and @samp{c} operators.
10201 @xref{Expressions}.
10203 @c ---------------------------------------------------------------------
10205 @node if-else, while, Operators in Conditionals, Conditionals and Loops
10206 @subsection if-else
10209 @code{gtroff} has if-then-else constructs like other languages, although
10210 the formatting can be painful.
10212 @Defreq {if, expr anything}
10213 Evaluate the expression @var{expr}, and executes @var{anything} (the
10214 remainder of the line) if @var{expr} evaluates to non-zero (true).
10215 @var{anything} is interpreted as though it was on a line by itself
10216 (except that leading spaces are swallowed). @xref{Expressions}, for
10222 .if ((\n[xxx] == 1) & (\n[yyy] == 2)) true
10227 @Defreq{nop, anything}
10228 Executes @var{anything}.
10229 This is similar to @code{.if@tie{}1}.
10232 @DefreqList {ie, expr anything}
10233 @DefreqListEnd {el, anything}
10234 Use the @code{ie} and @code{el} requests to write an if-then-else.
10235 The first request is the `if' part and the latter is the `else' part.
10238 .ie n .ls 2 \" double-spacing in nroff
10239 .el .ls 1 \" single-spacing in troff
10243 @c there is a bug in makeinfo <= 4.1a: you can't have `@{' as an argument
10246 @c and in 4.2 you still can't use @{ in macros.
10248 @c @DefescList {\@{, , , }
10249 @c @DefescListEnd {\@}, , , }
10250 @deffn Escape @t{\@{}
10251 @deffnx Escape @t{\@}}
10254 @cindex begin of conditional block (@code{\@{})
10255 @cindex end of conditional block (@code{\@}})
10256 @cindex conditional block, begin (@code{\@{})
10257 @cindex conditional block, end (@code{\@}})
10258 @cindex block, conditional, begin (@code{\@{})
10259 @cindex block, condititional, end (@code{\@}})
10260 In many cases, an if (or if-else) construct needs to execute more than
10261 one request. This can be done using the @code{\@{} and @code{\@}}
10262 escapes. The following example shows the possible ways to use these
10263 escapes (note the position of the opening and closing braces).
10278 @xref{Expressions}.
10280 @c ---------------------------------------------------------------------
10282 @node while, , if-else, Conditionals and Loops
10286 @code{gtroff} provides a looping construct using the @code{while}
10287 request, which is used much like the @code{if} (and related) requests.
10289 @Defreq {while, expr anything}
10290 Evaluate the expression @var{expr}, and repeatedly execute
10291 @var{anything} (the remainder of the line) until @var{expr} evaluates
10296 .while (\na < 9) \@{\
10300 @result{} 1, 2, 3, 4, 5, 6, 7, 8, 9, 10
10305 @cindex @code{de} request, and @code{while}
10308 The body of a @code{while} request is treated like the body of a
10309 @code{de} request: @code{gtroff} temporarily stores it in a macro
10310 which is deleted after the loop has been exited. It can considerably
10311 slow down a macro if the body of the @code{while} request (within the
10312 macro) is large. Each time the macro is executed, the @code{while}
10313 body is parsed and stored again as a temporary macro.
10318 . while (\\n[num] > 0) \@{\
10319 . \" many lines of code
10325 @cindex recursive macros
10326 @cindex macros, recursive
10328 The traditional and ofter better solution (@acronym{UNIX} @code{troff}
10329 doesn't have the @code{while} request) is to use a recursive macro
10330 instead which is parsed only once during its definition.
10334 . if (\\n[num] > 0) \@{\
10335 . \" many lines of code
10348 Note that the number of available recursion levels is set to@tie{}1000
10349 (this is a compile-time constant value of @code{gtroff}).
10352 The closing brace of a @code{while} body must end a line.
10357 . while (\n[a] < 10) \@{\
10360 @result{} unbalanced \@{ \@}
10366 @cindex @code{while} request, confusing with @code{br}
10367 @cindex @code{break} request, in a @code{while} loop
10368 @cindex @code{continue} request, in a @code{while} loop
10369 Break out of a @code{while} loop. Be sure not to confuse this with
10370 the @code{br} request (causing a line break).
10373 @Defreq {continue, }
10374 Finish the current iteration of a @code{while} loop, immediately
10375 restarting the next iteration.
10378 @xref{Expressions}.
10381 @c =====================================================================
10383 @node Writing Macros, Page Motions, Conditionals and Loops, gtroff Reference
10384 @section Writing Macros
10385 @cindex writing macros
10386 @cindex macros, writing
10388 A @dfn{macro} is a collection of text and embedded commands which can
10389 be invoked multiple times. Use macros to define common operations.
10391 @DefreqList {de, name [@Var{end}]}
10392 @DefreqItem {de1, name [@Var{end}]}
10393 @DefreqListEnd {dei, name [@Var{end}]}
10394 Define a new macro named @var{name}. @code{gtroff} copies subsequent
10395 lines (starting with the next one) into an internal buffer until it
10396 encounters the line @samp{..} (two dots). The optional second
10397 argument to @code{de} changes this to a macro to @samp{.@var{end}}.
10399 There can be whitespace after the first dot in the line containing the
10400 ending token (either @samp{.} or macro @samp{@var{end}}).
10402 Here a small example macro called @samp{P} which causes a break and
10403 inserts some vertical space. It could be used to separate paragraphs.
10412 The following example defines a macro within another. Remember that
10413 expansion must be protected twice; once for reading the macro and
10414 once for executing.
10417 \# a dummy macro to avoid a warning
10423 . nop \f[B]Hallo \\\\$1!\f[]
10429 @result{} @b{Hallo Joe!}
10433 Since @code{\f} has no expansion, it isn't necessary to protect its
10434 backslash. Had we defined another macro within @code{bar} which takes
10435 a parameter, eight backslashes would be necessary before @samp{$1}.
10437 The @code{de1} request turns off compatibility mode
10438 while executing the macro. On entry, the current compatibility mode
10439 is saved and restored at exit.
10445 The value of xxx is \\n[xxx].
10448 The value of xxx ix \\n[xxx].
10454 @result{} warning: number register
\e' not defined
10455 @result{} The value of xxx is 0xxx].
10457 @result{} The value of xxx ix 12345.
10460 The @code{dei} request defines a macro indirectly.
10461 That is, it expands strings whose names
10462 are @var{name} or @var{end} before performing the append.
10480 Using @file{trace.tmac}, you can trace calls to @code{de} and @code{de1}.
10482 Note that macro identifiers are shared with identifiers for strings and
10486 @DefreqList {am, name [@Var{end}]}
10487 @DefreqItem {am1, name [@Var{end}]}
10488 @DefreqListEnd {ami, name [@Var{end}]}
10489 @cindex appending to a macro (@code{am})
10490 @cindex macro, appending (@code{am})
10491 Works similarly to @code{de} except it appends onto the macro named
10492 @var{name}. So, to make the previously defined @samp{P} macro actually
10493 do indented instead of block paragraphs, add the necessary code to the
10494 existing macro like this:
10502 The @code{am1} request turns off compatibility mode
10503 while executing the appended macro piece. To be more precise, a
10504 @dfn{compatibility save} input token is inserted at the beginning of
10505 the appended code, and a @dfn{compatibility restore} input token at
10508 The @code{ami} request appends indirectly,
10509 meaning that @code{gtroff} expands strings whose names
10510 are @var{name} or @var{end} before performing the append.
10513 Using @file{trace.tmac}, you can trace calls to @code{am} and @code{am1}.
10516 @xref{Strings}, for the @code{als} request to rename a macro.
10518 The @code{de}, @code{am}, @code{di}, @code{da}, @code{ds}, and
10519 @code{as} requests (together with its variants) only create a new object
10520 if the name of the macro, diversion or string diversion is currently
10521 undefined or if it is defined to be a request; normally they modify the
10522 value of an existing object.
10524 @Defreq {return, [@Var{anything}]}
10525 Exit a macro, immediately returning to the caller.
10527 If called with an argument, exit twice, namely the current macro and the
10528 macro one level higher. This is used to define a wrapper macro for
10529 @code{return} in @file{trace.tmac}.
10537 @c ---------------------------------------------------------------------
10539 @node Copy-in Mode, Parameters, Writing Macros, Writing Macros
10540 @subsection Copy-in Mode
10541 @cindex copy-in mode
10542 @cindex mode, copy-in
10544 @cindex @code{\n}, when reading text for a macro
10545 @cindex @code{\$}, when reading text for a macro
10546 @cindex @code{\*}, when reading text for a macro
10547 @cindex @code{\\}, when reading text for a macro
10548 @cindex \@key{RET}, when reading text for a macro
10549 When @code{gtroff} reads in the text for a macro, string, or diversion,
10550 it copies the text (including request lines, but excluding escapes) into
10551 an internal buffer. Escapes are converted into an internal form,
10552 except for @code{\n}, @code{\$}, @code{\*}, @code{\\} and
10553 @code{\@key{RET}} which are evaluated and inserted into the text where
10554 the escape was located. This is known as @dfn{copy-in} mode or
10557 What this means is that you can specify when these escapes are to be
10558 evaluated (either at copy-in time or at the time of use) by insulating
10559 the escapes with an extra backslash. Compare this to the @code{\def}
10560 and @code{\edef} commands in @TeX{}.
10562 The following example prints the numbers 20 and@tie{}10:
10574 @c ---------------------------------------------------------------------
10576 @node Parameters, , Copy-in Mode, Writing Macros
10577 @subsection Parameters
10580 The arguments to a macro or string can be examined using a variety of
10584 @cindex number of arguments register (@code{.$})
10585 The number of arguments passed to a macro or string. This is a read-only
10589 Any individual argument can be retrieved with one of the following
10592 @DefescList {\\$, , n, }
10593 @DefescItem {\\$, @lparen{}, nn, }
10594 @DefescListEnd {\\$, @lbrack{}, nnn, @rbrack{}}
10595 @cindex copy-in mode, and macro arguments
10596 @cindex macro, arguments (@code{\$})
10597 @cindex arguments, macro (@code{\$})
10598 Retrieve the @var{n}@dmn{th}, @var{nn}@dmn{th} or @var{nnn}@dmn{th}
10599 argument. As usual, the first form only accepts a single number
10600 (larger than zero), the second a two-digit number (larger or equal
10601 to@tie{}10), and the third any positive integer value (larger
10602 than zero). Macros and strings can have an unlimited number of arguments.
10603 Note that due to copy-in mode, use two backslashes on these in actual use
10604 to prevent interpolation until the macro is actually invoked.
10607 @Defreq {shift, [@Var{n}]}
10608 Shift the arguments 1@tie{}position, or as
10609 many positions as specified by its argument. After executing this
10610 request, argument@tie{}@var{i} becomes argument @math{@var{i}-@var{n}};
10611 arguments 1 to@tie{}@var{n} are no longer available. Shifting by
10612 negative amounts is currently undefined.
10615 @DefescList {\\$*, , , }
10616 @DefescListEnd {\\$@@, , , }
10617 In some cases it is convenient to use all of the arguments at once (for
10618 example, to pass the arguments along to another macro). The @code{\$*}
10619 escape concatenates all the arguments separated by spaces. A
10620 similar escape is @code{\$@@}, which concatenates all the
10621 arguments with each surrounded by double quotes, and separated by
10622 spaces. If not in compatibility mode, the input level of double quotes
10623 is preserved (see @ref{Request and Macro Arguments}).
10626 @Defesc {\\$0, , , }
10627 @cindex macro name register (@code{\$0})
10628 @cindex @code{als} request, and @code{\$0}
10629 The name used to invoke the current macro.
10630 The @code{als} request can make a macro have more than one name.
10635 . if \\n[error] \@{\
10636 . tm \\$0: Houston, we have a problem.
10641 .als foo generic-macro
10642 .als bar generic-macro
10646 @xref{Request and Macro Arguments}.
10649 @c =====================================================================
10651 @node Page Motions, Drawing Requests, Writing Macros, gtroff Reference
10652 @section Page Motions
10653 @cindex page motions
10654 @cindex motions, page
10656 @xref{Manipulating Spacing}, for a discussion of the main request for
10657 vertical motion, @code{sp}.
10659 @DefreqList {mk, [@Var{reg}]}
10660 @DefreqListEnd {rt, [@Var{dist}]}
10661 @cindex marking vertical page location (@code{mk})
10662 @cindex page location, vertical, marking (@code{mk})
10663 @cindex location, vertical, page, marking (@code{mk})
10664 @cindex vertical page location, marking (@code{mk})
10665 @cindex returning to marked vertical page location (@code{rt})
10666 @cindex page location, vertical, returning to marked (@code{rt})
10667 @cindex location, vertical, page, returning to marked (@code{rt})
10668 @cindex vertical page location, returning to marked (@code{rt})
10669 The request @code{mk} can be used to mark a location on a page, for
10670 movement to later. This request takes a register name as an argument
10671 in which to store the current page location. With no argument it
10672 stores the location in an internal register. The results of this can
10673 be used later by the @code{rt} or the @code{sp} request (or the
10676 The @code{rt} request returns @emph{upwards} to the location marked
10677 with the last @code{mk} request. If used with an argument, return to
10678 a position which distance from the top of the page is @var{dist} (no
10679 previous call to @code{mk} is necessary in this case). Default scaling
10680 indicator is @samp{v}.
10682 Here a primitive solution for a two-column macro.
10685 .nr column-length 1.5i
10687 .nr bottom-margin 1m
10694 . ll \\n[column-length]u
10695 . wh -\\n[bottom-margin]u 2c-trap
10702 . ie \\n[right-side] \@{\
10704 . po -(\\n[column-length]u + \\n[column-gap]u)
10706 . wh -\\n[bottom-margin]u
10709 . \" switch to right side
10711 . po +(\\n[column-length]u + \\n[column-gap]u)
10720 This is a small test which shows how the
10721 rt request works in combination with mk.
10724 Starting here, text is typeset in two columns.
10725 Note that this implementation isn't robust
10726 and thus not suited for a real two-column
10733 This is a small test which shows how the
10734 rt request works in combination with mk.
10736 Starting here, isn't robust
10737 text is typeset and thus not
10738 in two columns. suited for a
10739 Note that this real two-column
10740 implementation macro.
10744 The following escapes give fine control of movements about the page.
10746 @Defesc {\\v, ', e, '}
10747 @cindex vertical motion (@code{\v})
10748 @cindex motion, vertical (@code{\v})
10749 Move vertically, usually from the current location on the page (if no
10750 absolute position operator @samp{|} is used). The
10751 argument@tie{}@var{e} specifies the distance to move; positive is
10752 downwards and negative upwards. The default scaling indicator for this
10753 escape is @samp{v}. Beware, however, that @code{gtroff} continues text
10754 processing at the point where the motion ends, so you should always
10755 balance motions to avoid interference with text processing.
10757 @code{\v} doesn't trigger a trap. This can be quite useful; for example,
10758 consider a page bottom trap macro which prints a marker in the margin to
10759 indicate continuation of a footnote or something similar.
10762 There are some special-case escapes for vertical motion.
10764 @Defesc {\\r, , , }
10765 Move upwards@tie{}1@dmn{v}.
10768 @Defesc {\\u, , , }
10769 Move upwards@tie{}.5@dmn{v}.
10772 @Defesc {\\d, , , }
10773 Move down@tie{}.5@dmn{v}.
10776 @Defesc {\\h, ', e, '}
10777 @cindex inserting horizontal space (@code{\h})
10778 @cindex horizontal space (@code{\h})
10779 @cindex space, horizontal (@code{\h})
10780 @cindex horizontal motion (@code{\h})
10781 @cindex motion, horizontal (@code{\h})
10782 Move horizontally, usually from the current location (if no absolute
10783 position operator @samp{|} is used). The expression@tie{}@var{e}
10784 indicates how far to move: positive is rightwards and negative
10785 leftwards. The default scaling indicator for this escape is @samp{m}.
10787 This horizontal space is not discarded at the end of a line. To insert
10788 discardable space of a certain length use the @code{ss} request.
10791 There are a number of special-case escapes for horizontal motion.
10793 @Defesc {\\@key{SP}, , , }
10794 @cindex space, unbreakable
10795 @cindex unbreakable space
10796 An unbreakable and unpaddable (i.e.@: not expanded during filling)
10797 space. (Note: This is a backslash followed by a space.)
10800 @Defesc {\\~, , , }
10801 An unbreakable space that stretches like a normal inter-word space
10802 when a line is adjusted.
10805 @Defesc {\\|, , , }
10806 A 1/6@dmn{th} em space. Ignored for TTY output devices (rounded to
10810 @Defesc {\\^, , , }
10811 A 1/12@dmn{th} em space. Ignored for TTY output devices (rounded to
10815 @Defesc {\\0, , , }
10816 @cindex space, width of a digit (@code{\0})
10817 @cindex digit width space (@code{\0})
10818 A space the size of a digit.
10821 The following string sets the @TeX{} logo:
10824 .ds TeX T\h'-.1667m'\v'.224m'E\v'-.224m'\h'-.125m'X
10827 @DefescList {\\w, ', text, '}
10834 @DefregListEnd {skw}
10835 @cindex width escape (@code{\w})
10836 Return the width of the specified @var{text} in basic units.
10837 This allows horizontal movement based on the width of some
10838 arbitrary text (e.g.@: given as an argument to a macro).
10841 The length of the string `abc' is \w'abc'u.
10842 @result{} The length of the string `abc' is 72u.
10845 Font changes may occur in @var{text} which don't affect current
10848 After use, @code{\w} sets several registers:
10853 The highest and lowest point of the baseline, respectively, in @var{text}.
10857 Like the @code{st} and @code{sb} registers, but takes account of the
10858 heights and depths of glyphs. With other words, this gives the
10859 highest and lowest point of @var{text}. Values below the baseline are
10863 Defines the kinds of glyphs occurring in @var{text}:
10867 only short glyphs, no descenders or tall glyphs.
10870 at least one descender.
10873 at least one tall glyph.
10876 at least one each of a descender and a tall glyph.
10880 The amount of horizontal space (possibly negative) that should be added
10881 to the last glyph before a subscript.
10884 How far to right of the center of the last glyph in the @code{\w}
10885 argument, the center of an accent from a roman font should be placed
10890 @DefescList {\\k, , p, }
10891 @DefescItem {\\k, @lparen{}, ps, }
10892 @DefescListEnd {\\k, @lbrack{}, position, @rbrack}
10893 @cindex saving horizontal input line position (@code{\k})
10894 @cindex horizontal input line position, saving (@code{\k})
10895 @cindex input line position, horizontal, saving (@code{\k})
10896 @cindex position, horizontal input line, saving (@code{\k})
10897 @cindex line, input, horizontal position, saving (@code{\k})
10898 Store the current horizontal position in the @emph{input} line in
10899 number register with name @var{position} (one-character name@tie{}@var{p},
10900 two-character name @var{ps}). Use this, for example, to return to the
10901 beginning of a string for highlighting or other decoration.
10905 @cindex horizontal input line position register (@code{hp})
10906 @cindex input line, horizontal position, register (@code{hp})
10907 @cindex position, horizontal, in input line, register (@code{hp})
10908 @cindex line, input, horizontal position, register (@code{hp})
10909 The current horizontal position at the input line.
10913 @cindex horizontal output line position register (@code{.k})
10914 @cindex output line, horizontal position, register (@code{.k})
10915 @cindex position, horizontal, in output line, register (@code{.k})
10916 @cindex line, output, horizontal position, register (@code{.k})
10917 A read-only number register containing the current horizontal output
10921 @Defesc {\\o, ', abc, '}
10922 @cindex overstriking glyphs (@code{\o})
10923 @cindex glyphs, overstriking (@code{\o})
10924 Overstrike glyphs @var{a}, @var{b}, @var{c}, @dots{}; the glyphs
10925 are centered, and the resulting spacing is the largest width of the
10929 @Defesc {\\z, , g, , }
10930 @cindex zero-width printing (@code{\z}, @code{\Z})
10931 @cindex printing, zero-width (@code{\z}, @code{\Z})
10932 Print glyph @var{g} with zero width, i.e., without spacing. Use
10933 this to overstrike glyphs left-aligned.
10936 @Defesc {\\Z, ', anything, '}
10937 @cindex zero-width printing (@code{\z}, @code{\Z})
10938 @cindex printing, zero-width (@code{\z}, @code{\Z})
10939 Print @var{anything}, then restore the horizontal and vertical position.
10940 The argument may not contain tabs or leaders.
10942 The following is an example of a strike-through macro:
10947 \Z@@\v'-.25m'\l'\\n[ww]u'@@\\$1
10952 an actual emergency!
10957 @c =====================================================================
10959 @node Drawing Requests, Traps, Page Motions, gtroff Reference
10960 @section Drawing Requests
10961 @cindex drawing requests
10962 @cindex requests for drawing
10964 @code{gtroff} provides a number of ways to draw lines and other figures
10965 on the page. Used in combination with the page motion commands (see
10966 @ref{Page Motions}, for more info), a wide variety of figures can be
10967 drawn. However, for complex drawings these operations can be quite
10968 cumbersome, and it may be wise to use graphic preprocessors like
10969 @code{gpic} or @code{ggrn}. @xref{gpic}, and @ref{ggrn}, for more
10972 All drawing is done via escapes.
10974 @DefescList {\\l, ', l, '}
10975 @DefescListEnd {\\l, ', lg, '}
10976 @cindex drawing horizontal lines (@code{\l})
10977 @cindex horizontal line, drawing (@code{\l})
10978 @cindex line, horizontal, drawing (@code{\l})
10979 Draw a line horizontally. @var{l} is the length of the line to be
10980 drawn. If it is positive, start the line at the current location and
10981 draw to the right; its end point is the new current location. Negative
10982 values are handled differently: The line starts at the current location
10983 and draws to the left, but the current location doesn't move.
10985 @var{l} can also be specified absolutely (i.e.@: with a leading
10986 @samp{|}) which draws back to the beginning of the input line.
10987 Default scaling indicator is @samp{m}.
10989 @cindex underscore glyph (@code{\[ru]})
10990 @cindex glyph, underscore (@code{\[ru]})
10991 @cindex line drawing glyph
10992 @cindex glyph, for line drawing
10993 The optional second parameter@tie{}@var{g} is a glyph to draw the line
10994 with. If this second argument is not specified, @code{gtroff} uses
10995 the underscore glyph, @code{\[ru]}.
10997 @cindex zero width space character (@code{\&})
10998 @cindex character, zero width space (@code{\&})
10999 @cindex space character, zero width (@code{\&})
11000 To separate the two arguments (to prevent @code{gtroff} from
11001 interpreting a drawing glyph as a scaling indicator if the glyph is
11002 represented by a single character) use @code{\&}.
11004 Here a small useful example:
11008 \[br]\\$*\[br]\l'|0\[rn]'\l'|0\[ul]'
11013 Note that this works by outputting a box rule (a vertical line), then
11014 the text given as an argument and then another box rule. Finally, the
11015 line drawing escapes both draw from the current location to the
11016 beginning of the @emph{input} line -- this works because the line
11017 length is negative, not moving the current point.
11020 @DefescList {\\L, ', l, '}
11021 @DefescListEnd {\\L, ', lg, '}
11022 @cindex drawing vertical lines (@code{\L})
11023 @cindex vertical line drawing (@code{\L})
11024 @cindex line, vertical, drawing (@code{\L})
11025 @cindex line drawing glyph
11026 @cindex glyph for line drawing
11027 @cindex box rule glyph (@code{\[br]})
11028 @cindex glyph, box rule (@code{\[br]})
11029 Draw vertical lines. Its parameters are
11030 similar to the @code{\l} escape, except that the default scaling
11031 indicator is @samp{v}. The movement is downwards for positive values,
11032 and upwards for negative values. The default glyph is the box rule
11033 glyph, @code{\[br]}. As with the vertical motion escapes, text
11034 processing blindly continues where the line ends.
11037 This is a \L'3v'test.
11041 Here the result, produced with @code{grotty}.
11051 @Defesc {\\D, ', command arg @dots{}, '}
11052 The @code{\D} escape provides a variety of drawing functions.
11053 Note that on character devices, only vertical and horizontal lines are
11054 supported within @code{grotty}; other devices may only support a subset
11055 of the available drawing functions.
11057 The default scaling indicator for all subcommands of @code{\D} is
11058 @samp{m} for horizontal distances and @samp{v} for vertical ones.
11059 Exceptions are @w{@code{\D'f @dots{}'}} and @w{@code{\D't @dots{}'}}
11060 which use @code{u} as the default, and @w{@code{\D'F@var{x} @dots{}'}}
11061 which arguments are treated similar to the @code{defcolor} request.
11064 @item \D'l @var{dx} @var{dy}'
11065 @cindex line, drawing (@w{@code{\D'l @dots{}'}})
11066 @cindex drawing a line (@w{@code{\D'l @dots{}'}})
11067 Draw a line from the current location to the relative point specified by
11068 (@var{dx},@var{dy}).
11070 The following example is a macro for creating a box around a text string;
11071 for simplicity, the box margin is taken as a fixed value, 0.2@dmn{m}.
11077 \h'-.2m'\v'(.2m - \\n[rsb]u)'\
11078 \D'l 0 -(\\n[rst]u - \\n[rsb]u + .4m)'\
11079 \D'l (\\n[@@wd]u + .4m) 0'\
11080 \D'l 0 (\\n[rst]u - \\n[rsb]u + .4m)'\
11081 \D'l -(\\n[@@wd]u + .4m) 0'\
11082 \h'.2m'\v'-(.2m - \\n[rsb]u)'\
11089 First, the width of the string is stored in register @code{@@wd}. Then,
11090 four lines are drawn to form a box, properly offset by the box margin.
11091 The registers @code{rst} and @code{rsb} are set by the @code{\w} escape,
11092 containing the largest height and depth of the whole string.
11094 @item \D'c @var{d}'
11095 @cindex circle, drawing (@w{@code{\D'c @dots{}'}})
11096 @cindex drawing a circle (@w{@code{\D'c @dots{}'}})
11097 Draw a circle with a diameter of@tie{}@var{d} with the leftmost point at the
11098 current position. After drawing, the current location is positioned at the
11099 rightmost point of the circle.
11101 @item \D'C @var{d}'
11102 @cindex circle, solid, drawing (@w{@code{\D'C @dots{}'}})
11103 @cindex drawing a solid circle (@w{@code{\D'C @dots{}'}})
11104 @cindex solid circle, drawing (@w{@code{\D'C @dots{}'}})
11105 Draw a solid circle with the same parameters and behaviour as an outlined
11106 circle. No outline is drawn.
11108 @item \D'e @var{x} @var{y}'
11109 @cindex drawing an ellipse (@w{@code{\D'e @dots{}'}})
11110 @cindex ellipse, drawing (@w{@code{\D'e @dots{}'}})
11111 Draw an ellipse with a horizontal diameter of @var{x} and a vertical
11112 diameter of @var{y} with the leftmost point at the current position.
11113 After drawing, the current location is positioned at the rightmost point of
11116 @item \D'E @var{x} @var{y}'
11117 @cindex ellipse, solid, drawing (@w{@code{\D'E @dots{}'}})
11118 @cindex drawing a solid ellipse (@w{@code{\D'E @dots{}'}})
11119 @cindex solid ellipse, drawing (@w{@code{\D'E @dots{}'}})
11120 Draw a solid ellipse with the same parameters and behaviour as an
11121 outlined ellipse. No outline is drawn.
11123 @item \D'a @var{dx1} @var{dy1} @var{dx2} @var{dy2}'
11124 @cindex arc, drawing (@w{@code{\D'a @dots{}'}})
11125 @cindex drawing an arc (@w{@code{\D'a @dots{}'}})
11126 Draw an arc clockwise from the current location through the two
11127 specified relative locations (@var{dx1},@var{dy1}) and
11128 (@var{dx2},@var{dy2}). The coordinates of the first point are relative
11129 to the current position, and the coordinates of the second point are
11130 relative to the first point. After drawing, the current position is moved
11131 to the final point of the arc.
11133 @item \D'~ @var{dx1} @var{dy1} @var{dx2} @var{dy2} @dots{}'
11134 @cindex drawing a spline (@w{@code{\D'~ @dots{}'}})
11135 @cindex spline, drawing (@w{@code{\D'~ @dots{}'}})
11136 Draw a spline from the current location to the relative point
11137 (@var{dx1},@var{dy1}) and then to (@var{dx2},@var{dy2}), and so on.
11138 The current position is moved to the terminal point of the drawn curve.
11140 @item \D'f @var{n}'
11141 @cindex gray shading (@w{@code{\D'f @dots{}'}})
11142 @cindex shading filled objects (@w{@code{\D'f @dots{}'}})
11143 Set the shade of gray to be used for filling solid objects to@tie{}@var{n};
11144 @var{n}@tie{}must be an integer between 0 and@tie{}1000, where 0
11145 corresponds solid white and 1000 to solid black, and values in between
11146 correspond to intermediate shades of gray. This applies only to solid
11147 circles, solid ellipses, and solid polygons. By default, a level of
11150 Despite of being silly, the current point is moved horizontally to the
11151 right by@tie{}@var{n}.
11153 @cindex @w{@code{\D'f @dots{}'}} and horizontal resolution
11154 Don't use this command! It has the serious drawback that it will be
11155 always rounded to the next integer multiple of the horizontal resolution
11156 (the value of the @code{hor} keyword in the @file{DESC} file). Use
11157 @code{\M} (@pxref{Colors}) or @w{@code{\D'Fg @dots{}'}} instead.
11159 @item \D'p @var{dx1} @var{dy1} @var{dx2} @var{dy2} @dots{}'
11160 @cindex drawing a polygon (@w{@code{\D'p @dots{}'}})
11161 @cindex polygon, drawing (@w{@code{\D'p @dots{}'}})
11162 Draw a polygon from the current location to the relative position
11163 (@var{dx1},@var{dy1}) and then to (@var{dx2},@var{dy2}) and so on.
11164 When the specified data points are exhausted, a line is drawn back
11165 to the starting point. The current position is changed by adding the
11166 sum of all arguments with odd index to the actual horizontal position and
11167 the even ones to the vertical position.
11169 @item \D'P @var{dx1} @var{dy1} @var{dx2} @var{dy2} @dots{}'
11170 @cindex polygon, solid, drawing (@w{@code{\D'P @dots{}'}})
11171 @cindex drawing a solid polygon (@w{@code{\D'P @dots{}'}})
11172 @cindex solid polygon, drawing (@w{@code{\D'P @dots{}'}})
11173 Draw a solid polygon with the same parameters and behaviour as an
11174 outlined polygon. No outline is drawn.
11176 Here a better variant of the box macro to fill the box with some color.
11177 Note that the box must be drawn before the text since colors in
11178 @code{gtroff} are not transparent; the filled polygon would hide the
11185 \h'-.2m'\v'(.2m - \\n[rsb]u)'\
11187 \D'P 0 -(\\n[rst]u - \\n[rsb]u + .4m) \
11188 (\\n[@@wd]u + .4m) 0 \
11189 0 (\\n[rst]u - \\n[rsb]u + .4m) \
11190 -(\\n[@@wd]u + .4m) 0'\
11191 \h'.2m'\v'-(.2m - \\n[rsb]u)'\
11198 @item \D't @var{n}'
11199 @cindex line thickness (@w{@code{\D't @dots{}'}})
11200 @cindex thickness of lines (@w{@code{\D't @dots{}'}})
11201 Set the current line thickness to @var{n}@tie{}machine units. A value of
11202 zero selects the smallest available line thickness. A negative value
11203 makes the line thickness proportional to the current point size (this is
11204 the default behaviour of @acronym{AT&T} @code{troff}).
11206 Despite of being silly, the current point is moved horizontally to the
11207 right by@tie{}@var{n}.
11209 @item \D'F@var{scheme} @var{color_components}'
11210 @cindex unnamed fill colors (@code{\D'F@dots{}'})
11211 @cindex fill colors, unnamed (@code{\D'F@dots{}'})
11212 @cindex colors, fill, unnamed (@code{\D'F@dots{}'})
11213 Change current fill color. @var{scheme} is a single letter denoting the
11214 color scheme: @samp{r} (rgb), @samp{c} (cmy), @samp{k} (cmyk), @samp{g}
11215 (gray), or @samp{d} (default color). The color components use exactly
11216 the same syntax as in the @code{defcolor} request (@pxref{Colors}); the
11217 command @code{\D'Fd'} doesn't take an argument.
11219 @emph{No} position changing!
11225 \D'Fg .3' \" same gray as \D'f 700'
11226 \D'Fr #0000ff' \" blue
11230 @xref{Graphics Commands}.
11232 @Defesc {\\b, ', string, '}
11233 @cindex pile, glyph (@code{\b})
11234 @cindex glyph pile (@code{\b})
11235 @cindex stacking glyphs (@code{\b})
11236 @dfn{Pile} a sequence of glyphs vertically, and center it vertically
11237 on the current line. Use it to build large brackets and braces.
11239 Here an example how to create a large opening brace:
11242 \b'\[lt]\[bv]\[lk]\[bv]\[lb]'
11245 @cindex @code{\b}, limitations
11246 @cindex limitations of @code{\b} escape
11247 The first glyph is on the top, the last glyph in @var{string} is
11248 at the bottom. Note that @code{gtroff} separates the glyphs
11249 vertically by 1@dmn{m}, and the whole object is centered 0.5@dmn{m}
11250 above the current baseline; the largest glyph width is used as the
11251 width for the whole object. This rather unflexible positioning
11252 algorithm doesn't work with @option{-Tdvi} since the bracket pieces vary
11253 in height for this device. Instead, use the @code{eqn} preprocessor.
11255 @xref{Manipulating Spacing}, how to adjust the vertical spacing with
11256 the @code{\x} escape.
11260 @c =====================================================================
11262 @node Traps, Diversions, Drawing Requests, gtroff Reference
11266 @dfn{Traps} are locations, which, when reached, call a specified
11267 macro. These traps can occur at a given location on the page, at a
11268 given location in the current diversion, at a blank line,
11269 after a certain number of input lines, or at the end of input.
11271 @cindex planting a trap
11272 @cindex trap, planting
11273 Setting a trap is also called @dfn{planting}.
11274 @cindex trap, springing
11275 @cindex springing a trap
11276 It is also said that a trap is @dfn{sprung} if the associated macro
11280 * Page Location Traps::
11281 * Diversion Traps::
11282 * Input Line Traps::
11283 * Blank Line Traps::
11284 * End-of-input Traps::
11287 @c ---------------------------------------------------------------------
11289 @node Page Location Traps, Diversion Traps, Traps, Traps
11290 @subsection Page Location Traps
11291 @cindex page location traps
11292 @cindex traps, page location
11294 @dfn{Page location traps} perform an action when @code{gtroff}
11295 reaches or passes a certain vertical location on the page. Page
11296 location traps have a variety of purposes, including:
11300 setting headers and footers
11303 setting body text in multiple columns
11309 @DefreqList {vpt, flag}
11310 @DefregListEnd {.vpt}
11311 @cindex enabling vertical position traps (@code{vpt})
11312 @cindex vertical position traps, enabling (@code{vpt})
11313 @cindex vertical position trap enable register (@code{.vpt})
11314 Enable vertical position traps if @var{flag} is non-zero, or disables
11315 them otherwise. Vertical position traps are traps set by the @code{wh}
11316 or @code{dt} requests. Traps set by the @code{it} request are not
11317 vertical position traps. The parameter that controls whether vertical
11318 position traps are enabled is global. Initially vertical position traps
11319 are enabled. The current setting of this is available in the
11320 @code{.vpt} read-only number register.
11322 Note that a page can't be ejected if @code{vpt} is set to zero.
11325 @Defreq {wh, dist [@Var{macro}]}
11326 Set a page location trap. Non-negative values for @var{dist} set
11327 the trap relative to the top of the page; negative values set
11328 the trap relative to the bottom of the page. Default scaling
11329 indicator is @samp{v}.
11331 @var{macro} is the name of the macro to execute when the
11332 trap is sprung. If @var{macro} is missing, remove the first trap
11333 (if any) at @var{dist}.
11335 @cindex page headers
11336 @cindex page footers
11339 The following is a simple example of how many macro packages
11340 set headers and footers.
11343 .de hd \" Page header
11349 .de fo \" Page footer
11355 .wh 0 hd \" trap at top of the page
11356 .wh -1i fo \" trap one inch from bottom
11359 A trap at or below the bottom of the page is ignored; it can be made
11360 active by either moving it up or increasing the page length so that the
11361 trap is on the page.
11363 It is possible to have more than one trap at the same location; to do so,
11364 the traps must be defined at different locations, then moved together with
11365 the @code{ch} request; otherwise the second trap would replace the first
11366 one. Earlier defined traps hide later defined traps if moved to the same
11367 position (the many empty lines caused by the @code{bp} request are omitted
11368 in the following example):
11401 @cindex distance to next trap register (@code{.t})
11402 @cindex trap, distance, register (@code{.t})
11403 A read-only number register holding the distance to the next trap.
11405 If there are no traps between the current position and the bottom of the
11406 page, it contains the distance to the page bottom. In a diversion, the
11407 distance to the page bottom is infinite (the returned value is the biggest
11408 integer which can be represented in @code{groff}) if there are no diversion
11412 @Defreq {ch, macro [@Var{dist}]}
11413 @cindex changing trap location (@code{ch})
11414 @cindex trap, changing location (@code{ch})
11415 Change the location of a trap.
11416 The first argument is the name of the macro to be invoked at
11417 the trap, and the second argument is the new location for the trap
11418 (note that the parameters are specified in opposite order as in the
11419 @code{wh} request). This is useful for building up footnotes in a
11420 diversion to allow more space at the bottom of the page for them.
11422 Default scaling indicator for @var{dist} is @samp{v}. If @var{dist}
11423 is missing, the trap is removed.
11429 ... (simplified) footnote example ...
11435 The read-only number register @code{.ne} contains the amount of space
11436 that was needed in the last @code{ne} request that caused a trap to be
11437 sprung. Useful in conjunction with the @code{.trunc} register.
11438 @xref{Page Control}, for more information.
11440 Since the @code{.ne} register is only set by traps it doesn't make
11441 much sense to use it outside of trap macros.
11445 @cindex @code{ne} request, and the @code{.trunc} register
11446 @cindex truncated vertical space register (@code{.trunc})
11447 A read-only register containing the amount of vertical space truncated
11448 by the most recently sprung vertical position trap, or, if the trap was
11449 sprung by an @code{ne} request, minus the amount of vertical motion
11450 produced by the @code{ne} request. In other words, at the point a trap
11451 is sprung, it represents the difference of what the vertical position
11452 would have been but for the trap, and what the vertical position
11455 Since the @code{.trunc} register is only set by traps and it doesn't make
11456 much sense to use it outside of trap macros.
11460 @cindex @code{bp} request, and traps (@code{.pe})
11461 @cindex traps, sprung by @code{bp} request (@code{.pe})
11462 @cindex page ejecting register (@code{.pe})
11463 A read-only register which is set to@tie{}1 while a page is ejected with
11464 the @code{bp} request (or by the end of input).
11466 Outside of traps this register is always zero. In the following example,
11467 only the second call to@tie{}@code{x} is caused by @code{bp}.
11488 @cindex diversions, and traps
11489 @cindex traps, and diversions
11490 An important fact to consider while designing macros is that diversions and
11491 traps do not interact normally. For example, if a trap invokes a header
11492 macro (while outputting a diversion) which tries to change the font on the
11493 current page, the effect will not be visible before the diversion has
11494 completely been printed (except for input protected with @code{\!} or
11495 @code{\?}) since the data in the diversion is already formatted. In most
11496 cases, this is not the expected behaviour.
11498 @c ---------------------------------------------------------------------
11500 @node Diversion Traps, Input Line Traps, Page Location Traps, Traps
11501 @subsection Diversion Traps
11502 @cindex diversion traps
11503 @cindex traps, diversion
11505 @Defreq {dt, dist macro}
11506 @cindex @code{.t} register, and diversions
11507 @cindex setting diversion trap (@code{dt})
11508 @cindex diversion trap, setting (@code{dt})
11509 @cindex trap, diversion, setting (@code{dt})
11510 Set a trap @emph{within} a diversion.
11511 @var{dist} is the location of the trap
11512 (identical to the @code{wh} request; default scaling indicator is
11513 @samp{v}) and @var{macro} is the name of the macro to be invoked. The
11514 number register @code{.t} still works within diversions.
11515 @xref{Diversions}, for more information.
11518 @c ---------------------------------------------------------------------
11520 @node Input Line Traps, Blank Line Traps, Diversion Traps, Traps
11521 @subsection Input Line Traps
11522 @cindex input line traps
11523 @cindex traps, input line
11525 @DefreqList {it, n macro}
11526 @DefreqItem {itc, n macro}
11527 @cindex setting input line trap (@code{it})
11528 @cindex input line trap, setting (@code{it})
11529 @cindex trap, input line, setting (@code{it})
11530 Set an input line trap.
11531 @var{n}@tie{}is the number of lines of input which may be read before
11532 springing the trap, @var{macro} is the macro to be invoked.
11533 Request lines are not counted as input lines.
11535 For example, one possible use is to have a macro which prints the
11536 next @var{n}@tie{}lines in a bold font.
11549 @cindex input line traps and interrupted lines (@code{itc})
11550 @cindex interrupted lines and input line traps (@code{itc})
11551 @cindex traps, input line, and interrupted lines (@code{itc})
11552 @cindex lines, interrupted, and input line traps (@code{itc})
11553 The @code{itc} request is identical
11554 except that an interrupted text line (ending with @code{\c})
11555 is not counted as a separate line.
11557 Both requests are associated with the current environment
11558 (@pxref{Environments}); switching to another environment disables the
11559 current input trap, and going back reactivates it, restoring the number
11560 of already processed lines.
11563 @c ---------------------------------------------------------------------
11565 @node Blank Line Traps, End-of-input Traps, Input Line Traps, Traps
11566 @subsection Blank Line Traps
11567 @cindex blank line traps
11568 @cindex traps, blank line
11570 @Defreq {blm, macro}
11571 @cindex blank line macro (@code{blm})
11572 Set a blank line trap.
11573 @code{gtroff} executes @var{macro} when it encounters a blank line in
11577 @c ---------------------------------------------------------------------
11579 @node End-of-input Traps, , Blank Line Traps, Traps
11580 @subsection End-of-input Traps
11581 @cindex end-of-input traps
11582 @cindex traps, end-of-input
11584 @Defreq {em, macro}
11585 @cindex setting end-of-input trap (@code{em})
11586 @cindex end-of-input trap, setting (@code{em})
11587 @cindex trap, end-of-input, setting (@code{em})
11588 @cindex end-of-input macro (@code{em})
11589 @cindex macro, end-of-input (@code{em})
11590 Set a trap at the end of input. @var{macro} is executed after the
11591 last line of the input file has been processed.
11593 For example, if the document had to have a section at the bottom of the
11594 last page for someone to approve it, the @code{em} request could be
11600 . sp |(\\n[.t] - 6v)
11614 @c =====================================================================
11616 @node Diversions, Environments, Traps, gtroff Reference
11617 @section Diversions
11620 In @code{gtroff} it is possible to @dfn{divert} text into a named
11621 storage area. Due to the similarity to defining macros it is sometimes
11622 said to be stored in a macro. This is used for saving text for output
11623 at a later time, which is useful for keeping blocks of text on the same
11624 page, footnotes, tables of contents, and indices.
11626 @cindex top-level diversion
11627 @cindex diversion, top-level
11628 For orthogonality it is said that @code{gtroff} is in the @dfn{top-level
11629 diversion} if no diversion is active (i.e., the data is diverted to the
11632 @DefreqList {di, macro}
11633 @DefreqListEnd {da, macro}
11634 @cindex beginning diversion (@code{di})
11635 @cindex diversion, beginning (@code{di})
11636 @cindex ending diversion (@code{di})
11637 @cindex diversion, ending (@code{di})
11638 @cindex appending to a diversion (@code{da})
11639 @cindex diversion, appending (@code{da})
11640 Begin a diversion. Like the @code{de}
11641 request, it takes an argument of a macro name to divert subsequent text
11642 into. The @code{da} macro appends to an existing diversion.
11644 @code{di} or @code{da} without an argument ends the diversion.
11647 @DefreqList {box, macro}
11648 @DefreqListEnd {boxa, macro}
11649 Begin (or appends to) a diversion like the
11650 @code{di} and @code{da} requests.
11651 The difference is that @code{box} and @code{boxa}
11652 do not include a partially-filled line in the diversion.
11664 @result{} Before the box. After the box.
11666 @result{} In the box.
11673 Before the diversion.
11678 After the diversion.
11680 @result{} After the diversion.
11682 @result{} Before the diversion. In the diversion.
11685 @code{box} or @code{boxa} without an argument ends the diversion.
11689 @DefregListEnd {.d}
11690 @cindex @code{nl} register, and @code{.d}
11691 @cindex nested diversions
11692 @cindex diversion, nested
11693 @cindex diversion name register (@code{.z})
11694 @cindex vertical position in diversion register (@code{.d})
11695 @cindex position, vertical, in diversion, register (@code{.d})
11696 @cindex diversion, vertical position in, register (@code{.d})
11697 Diversions may be nested. The read-only number register @code{.z}
11698 contains the name of the current diversion (this is a string-valued
11699 register). The read-only number register @code{.d} contains the current
11700 vertical place in the diversion. If not in a diversion it is the same
11701 as register @code{nl}.
11705 @cindex high-water mark register (@code{.h})
11706 @cindex mark, high-water, register (@code{.h})
11707 @cindex position of lowest text line (@code{.h})
11708 @cindex text line, position of lowest (@code{.h})
11709 The @dfn{high-water mark} on the current page. It corresponds to the
11710 text baseline of the lowest line on the page. This is a read-only
11714 .tm .h==\n[.h], nl==\n[nl]
11715 @result{} .h==0, nl==-1
11719 .tm .h==\n[.h], nl==\n[nl]
11720 @result{} .h==40, nl==120
11723 @cindex @code{.h} register, difference to @code{nl}
11724 @cindex @code{nl} register, difference to @code{.h}
11726 As can be seen in the previous example, empty lines are not considered
11727 in the return value of the @code{.h} register.
11731 @DefregListEnd {dl}
11732 @cindex @code{dn} register, and @code{da} (@code{boxa})
11733 @cindex @code{dl} register, and @code{da} (@code{boxa})
11734 @cindex @code{da} request, and @code{dn} (@code{dl})
11735 @cindex @code{boxa} request, and @code{dn} (@code{dl})
11736 After completing a diversion, the read-write number registers @code{dn}
11737 and @code{dl} contain the vertical and horizontal size of the diversion.
11738 Note that only the just processed lines are counted: For the computation
11739 of @code{dn} and @code{dl}, the requests @code{da} and @code{boxa} are
11740 handled as if @code{di} and @code{box} had been used -- lines which have
11741 been already stored in a macro are not taken into account.
11744 .\" Center text both horizontally & vertically
11746 .\" Enclose macro definitions in .eo and .ec
11747 .\" to avoid the doubling of the backslash
11749 .\" macro .(c starts centering mode
11760 .\" macro .)c terminates centering mode
11765 . nr @@s (((\n[.t]u - \n[dn]u) / 2u) - 1v)
11777 .\" End of macro definitions, restore escape mechanism
11782 @DefescList {\\!, , , }
11783 @DefescListEnd {\\?, , anything, \\?}
11784 @cindex transparent output (@code{\!}, @code{\?})
11785 @cindex output, transparent (@code{\!}, @code{\?})
11786 Prevent requests, macros, and escapes from being
11787 interpreted when read into a diversion. Both escapes take the given text
11788 and @dfn{transparently} embed it into the diversion. This is useful for
11789 macros which shouldn't be invoked until the diverted text is actually
11792 The @code{\!} escape transparently embeds text up to
11793 and including the end of the line.
11794 The @code{\?} escape transparently embeds text until the next
11795 occurrence of the @code{\?} escape. Example:
11802 @var{anything} may not contain newlines; use @code{\!} to embed
11803 newlines in a diversion. The escape sequence @code{\?} is also
11804 recognized in copy mode and turned into a single internal code; it is
11805 this code that terminates @var{anything}. Thus the following example
11812 \?\\?\\\\?\\\\\\\\nx\\\\?\\?\?
11826 Both escapes read the data in copy mode.
11828 @cindex @code{\!}, in top-level diversion
11829 @cindex top-level diversion, and @code{\!}
11830 @cindex diversion, top-level, and @code{\!}
11831 If @code{\!} is used in the top-level diversion, its argument is
11832 directly embedded into the @code{gtroff} intermediate output. This can
11833 be used for example to control a postprocessor which processes the data
11834 before it is sent to the device driver.
11836 @cindex @code{\?}, in top-level diversion
11837 @cindex top-level diversion, and @code{\?}
11838 @cindex diversion, top-level, and @code{\?}
11839 The @code{\?} escape used in the top-level diversion produces no output
11840 at all; its argument is simply ignored.
11843 @cindex @code{\!}, and @code{output}
11844 @cindex @code{output} request, and @code{\!}
11845 @Defreq {output, string}
11846 Emit @var{string} directly to the @code{gtroff} intermediate output
11847 (subject to copy-mode interpretation); this is similar to @code{\!} used
11848 at the top level. An initial double quote in @var{string} is stripped off
11849 to allow initial blanks.
11851 This request can't be used before the first page has started -- if you get
11852 an error, simply insert @code{.br} before the @code{output} request.
11854 Without argument, @code{output} is ignored.
11856 Use with caution! It is normally only needed for mark-up used by a
11857 postprocessor which does something with the output before sending it to
11858 the output device, filtering out @var{string} again.
11861 @Defreq {asciify, div}
11862 @cindex unformatting diversions (@code{asciify})
11863 @cindex diversion, unformatting (@code{asciify})
11864 @cindex @code{trin} request, and @code{asciify}
11865 @dfn{Unformat} the diversion specified by @var{div}
11866 in such a way that @acronym{ASCII} characters, characters translated with
11867 the @code{trin} request, space characters, and some escape sequences that
11868 were formatted and diverted are treated like ordinary input
11869 characters when the diversion is reread. It can be also used for gross
11870 hacks; for example, the following sets register@tie{}@code{n} to@tie{}1.
11883 @xref{Copy-in Mode}.
11886 @Defreq {unformat, div}
11887 Like @code{asciify}, unformat the specified diversion.
11888 However, @code{unformat} only unformats spaces and tabs
11890 Unformatted tabs are treated as input tokens,
11891 and spaces are stretchable again.
11893 The vertical size of lines is not preserved; glyph information (font,
11894 font size, space width, etc.)@: is retained.
11898 @c =====================================================================
11900 @node Environments, Suppressing output, Diversions, gtroff Reference
11901 @section Environments
11902 @cindex environments
11904 It happens frequently that some text should be printed in a certain
11905 format regardless of what may be in effect at the time, for example, in
11906 a trap invoked macro to print headers and footers. To solve this
11907 @code{gtroff} processes text in @dfn{environments}. An
11908 environment contains most of the parameters that control text
11909 processing. It is possible to switch amongst these environments; by
11910 default @code{gtroff} processes text in environment@tie{}0. The
11911 following is the information kept in an environment.
11915 font parameters (size, family, style, glyph height and slant, space
11916 and sentence space size)
11919 page parameters (line length, title length, vertical spacing,
11920 line spacing, indentation, line numbering, centering, right-justifying,
11921 underlining, hyphenation data)
11924 fill and adjust mode
11927 tab stops, tab and leader characters, escape character,
11928 no-break and hyphen indicators, margin character data
11931 partially collected lines
11937 drawing and fill colours
11940 These environments may be given arbitrary names (see @ref{Identifiers},
11941 for more info). Old versions of @code{troff} only had environments
11942 named @samp{0}, @samp{1}, and @samp{2}.
11944 @DefreqList {ev, [@Var{env}]}
11945 @DefregListEnd {.ev}
11946 @cindex switching environments (@code{ev})
11947 @cindex environment, switching (@code{ev})
11948 @cindex environment number/name register (@code{.ev})
11949 Switch to another environment. The argument @var{env} is the name of
11950 the environment to switch to. With no argument, @code{gtroff} switches
11951 back to the previous environment. There is no limit on the number of
11952 named environments; they are created the first time that they are
11953 referenced. The @code{.ev} read-only register contains the name or
11954 number of the current environment. This is a string-valued register.
11956 Note that a call to @code{ev} (with argument) pushes the previously
11957 active environment onto a stack. If, say, environments @samp{foo},
11958 @samp{bar}, and @samp{zap} are called (in that order), the first
11959 @code{ev} request without parameter switches back to environment
11960 @samp{bar} (which is popped off the stack), and a second call
11961 switches back to environment @samp{foo}.
11963 Here is an example:
11976 \(dg Note the large, friendly letters.
11982 @cindex copying environment (@code{evc})
11983 @cindex environment, copying (@code{evc})
11984 Copy the environment @var{env} into the current environment.
11986 The following environment data is not copied:
11990 Partially filled lines.
11993 The status whether the previous line was interrupted.
11996 The number of lines still to center, or to right-justify, or to underline
11997 (with or without underlined spaces); they are set to zero.
12000 The status whether a temporary indent is active.
12003 Input traps and its associated data.
12006 Line numbering mode is disabled; it can be reactivated with
12010 The number of consecutive hyphenated lines (set to zero).
12017 @DefregListEnd {.csk}
12018 @cindex environment, dimensions of last glyph (@code{.w}, @code{.cht}, @code{.cdp}, @code{.csk})
12019 @cindex width, of last glyph (@code{.w})
12020 @cindex height, of last glyph (@code{.cht})
12021 @cindex depth, of last glyph (@code{.cdp})
12022 @cindex skew, of last glyph (@code{.csk})
12023 @cindex last glyph, dimensions (@code{.w}, @code{.cht}, @code{.cdp}, @code{.csk})
12024 @cindex glyph, last, dimensions (@code{.w}, @code{.cht}, @code{.cdp}, @code{.csk})
12025 The @code{\n[.w]} register contains the
12026 width of the last glyph added to the current environment.
12028 The @code{\n[.cht]} register contains the
12029 height of the last glyph added to the current environment.
12031 The @code{\n[.cdp]} register contains the
12032 depth of the last glyph added to the current environment.
12033 It is positive for glyphs extending below the baseline.
12035 The @code{\n[.csk]} register contains the
12036 @dfn{skew} (how far to the right of the glyph's center
12037 that @code{gtroff} should place an accent)
12038 of the last glyph added to the current environment.
12042 @cindex environment, previous line length (@code{.n})
12043 @cindex line length, previous (@code{.n})
12044 @cindex length of previous line (@code{.n})
12045 @cindex previous line length (@code{.n})
12046 The @code{\n[.n]} register contains the
12047 length of the previous output line in the current environment.
12051 @c =====================================================================
12053 @node Suppressing output, Colors, Environments, gtroff Reference
12054 @section Suppressing output
12056 @Defesc {\\O, , num, }
12057 @cindex suppressing output (@code{\O})
12058 @cindex output, suppressing (@code{\O})
12059 Disable or enable output depending on the value of @var{num}:
12063 Disable any glyphs from being emitted to the device driver, provided that
12064 the escape occurs at the outer level (see @code{\O[3]} and @code{\O[4]}).
12065 Motion is not suppressed so effectively @code{\O[0]} means @emph{pen up}.
12068 Enable output of glyphs, provided that the escape occurs at the outer
12076 @code{\O0} and @code{\O1} also reset the four registers @samp{opminx},
12077 @samp{opminy}, @samp{opmaxx}, and @samp{opmaxy} to @minus{}1.
12078 @xref{Register Index}. These four registers mark the top left and
12079 bottom right hand corners of a box which encompasses all written glyphs.
12081 For example the input text:
12084 Hello \O[0]world \O[1]this is a test.
12088 produces the following output:
12091 Hello this is a test.
12096 Provided that the escape occurs at the outer level, enable output of
12097 glyphs and also write out to @code{stderr} the page number and four
12098 registers encompassing the glyphs previously written since the last call
12102 Begin a nesting level. At start-up, @code{gtroff} is at outer level.
12105 End a nesting level.
12107 @item \O[5@var{P}@var{filename}]
12108 This escape is @code{grohtml} specific. Provided that this escape
12109 occurs at the outer nesting level write the @code{filename} to
12110 @code{stderr}. The position of the image, @var{P}, must be specified
12111 and must be one of @code{l}, @code{r}, @code{c}, or@tie{}@code{i} (left,
12112 right, centered, inline). @var{filename} will be associated with the
12113 production of the next inline image.
12117 @c =====================================================================
12119 @node Colors, I/O, Suppressing output, gtroff Reference
12123 @DefreqList {color, [@Var{n}]}
12124 @DefregListEnd {.color}
12125 If @var{n} is missing or non-zero, activate colors (this is the default);
12126 otherwise, turn it off.
12128 The read-only number register @code{.color} is@tie{}1 if colors are active,
12131 Internally, @code{color} sets a global flag; it does not produce a token.
12132 Similar to the @code{cp} request, you should use it at the beginning of
12133 your document to control color output.
12135 Colors can be also turned off with the @option{-c} command line option.
12138 @Defreq {defcolor, ident scheme color_components}
12139 Define color with name @var{ident}. @var{scheme} can be one of the
12140 following values: @code{rgb} (three components), @code{cmy} (three
12141 components), @code{cmyk} (four components), and @code{gray} or
12142 @code{grey} (one component).
12144 @cindex default color
12145 @cindex color, default
12146 Color components can be given either as a hexadecimal string or as
12147 positive decimal integers in the range 0--65535. A hexadecimal string
12148 contains all color components concatenated. It must start with either
12149 @code{#} or @code{##}; the former specifies hex values in the range
12150 0--255 (which are internally multiplied by@tie{}257), the latter in the
12151 range 0--65535. Examples: @code{#FFC0CB} (pink), @code{##ffff0000ffff}
12152 (magenta). The default color name @c{default} can't be redefined; its
12153 value is device-specific (usually black). It is possible that the
12154 default color for @code{\m} and @code{\M} is not identical.
12156 @cindex @code{f} unit, and colors
12157 @cindex unit, @code{f}, and colors
12158 A new scaling indicator@tie{}@code{f} has been introduced which multiplies
12159 its value by 65536; this makes it convenient to specify color components
12160 as fractions in the range 0 to@tie{}1 (1f equals 65536u). Example:
12163 .defcolor darkgreen rgb 0.1f 0.5f 0.2f
12166 Note that @code{f} is the default scaling indicator for the
12167 @code{defcolor} request, thus the above statement is equivalent to
12170 .defcolor darkgreen rgb 0.1 0.5 0.2
12174 @DefescList {\\m, , c, }
12175 @DefescItem {\\m, @lparen{}, co, }
12176 @DefescListEnd {\\m, @lbrack{}, color, @rbrack}
12177 Set drawing color. The following example shows how to turn the next four
12181 \m[red]these are in red\m[] and these words are in black.
12184 The escape @code{\m[]} returns to the previous color.
12186 The drawing color is associated with the current environment
12187 (@pxref{Environments}).
12189 Note that @code{\m} doesn't produce an input token in @code{gtroff}.
12190 As a consequence, it can be used in requests like @code{mc} (which
12191 expects a single character as an argument) to change the color on
12199 @DefescList {\\M, , c, }
12200 @DefescItem {\\M, @lparen{}, co, }
12201 @DefescListEnd {\\M, @lbrack{}, color, @rbrack}
12202 Set background color for filled objects drawn with the
12203 @code{\D'@dots{}'} commands.
12205 A red ellipse can be created with the following code:
12208 \M[red]\h'0.5i'\D'E 2i 1i'\M[]
12211 The escape @code{\M[]} returns to the previous fill color.
12213 The fill color is associated with the current environment
12214 (@pxref{Environments}).
12216 Note that @code{\M} doesn't produce an input token in @code{gtroff}.
12220 @c =====================================================================
12222 @node I/O, Postprocessor Access, Colors, gtroff Reference
12225 @cindex input and output requests
12226 @cindex requests for input and output
12227 @cindex output and input requests
12229 @code{gtroff} has several requests for including files:
12232 @cindex including a file (@code{so})
12233 @cindex file, inclusion (@code{so})
12234 Read in the specified @var{file} and
12235 includes it in place of the @code{so} request. This is quite useful for
12236 large documents, e.g.@: keeping each chapter in a separate file.
12237 @xref{gsoelim}, for more information.
12239 Since @code{gtroff} replaces the @code{so} request with the contents
12240 of @code{file}, it makes a difference whether the data is terminated with
12241 a newline or not: Assuming that file @file{xxx} contains the word
12242 @samp{foo} without a final newline, this
12251 yields @samp{This is foobar}.
12254 @Defreq {pso, command}
12255 Read the standard output from the specified @var{command}
12256 and includes it in place of the @code{pso} request.
12259 @cindex mode, safer
12260 @cindex unsafe mode
12261 @cindex mode, unsafe
12262 This request causes an error if used in safer mode (which is the default).
12263 Use @code{groff}'s or @code{troff}'s @option{-U} option to activate unsafe
12266 The comment regarding a final newline for the @code{so} request is valid
12267 for @code{pso} also.
12270 @Defreq {mso, file}
12271 Identical to the @code{so} request except that @code{gtroff} searches for
12272 the specified @var{file} in the same directories as macro files for the
12273 the @option{-m} command line option. If the file name to be included
12274 has the form @file{@var{name}.tmac} and it isn't found, @code{mso} tries
12275 to include @file{tmac.@var{name}} and vice versa.
12278 @DefreqList {trf, file}
12279 @DefreqListEnd {cf, file}
12280 @cindex transparent output (@code{cf}, @code{trf})
12281 @cindex output, transparent (@code{cf}, @code{trf})
12282 Transparently output the contents of @var{file}. Each line is output
12283 as if it were preceded by @code{\!}; however, the lines are not subject
12284 to copy mode interpretation. If the file does not end with a newline,
12285 then a newline is added (@code{trf} only). For example, to define a
12286 macro@tie{}@code{x} containing the contents of file@tie{}@file{f}, use
12294 Both @code{trf} and @code{cf}, when used in a diversion,
12295 embeds an object in the diversion which, when reread, causes the
12296 contents of @var{file} to be transparently copied through to the
12297 output. In @acronym{UNIX} @code{troff}, the contents of @var{file}
12298 is immediately copied through to the output regardless of whether there
12299 is a current diversion; this behaviour is so anomalous that it must be
12302 @cindex @code{trf} request, and invalid characters
12303 @cindex characters, invalid for @code{trf} request
12304 @cindex invalid characters for @code{trf} request
12305 While @code{cf} copies the contents of @var{file} completely unprocessed,
12306 @code{trf} disallows characters such as NUL that are not valid
12307 @code{gtroff} input characters (@pxref{Identifiers}).
12309 Both requests cause a line break.
12312 @Defreq {nx, [@Var{file}]}
12313 @cindex processing next file (@code{nx})
12314 @cindex file, processing next (@code{nx})
12315 @cindex next file, processing (@code{nx})
12316 Force @code{gtroff} to continue processing of
12317 the file specified as an argument. If no argument is given, immediately
12318 jump to the end of file.
12321 @Defreq {rd, [@Var{prompt} [@Var{arg1} @Var{arg2} @dots{}]]}
12322 @cindex reading from standard input (@code{rd})
12323 @cindex standard input, reading from (@code{rd})
12324 @cindex input, standard, reading from (@code{rd})
12325 Read from standard input, and include what is read as though it
12326 were part of the input file. Text is read until a blank line
12329 If standard input is a TTY input device (keyboard), write @var{prompt}
12330 to standard error, followed by a colon (or send BEL for a beep if no
12331 argument is given).
12333 Arguments after @var{prompt} are available for the input. For example,
12340 with the input @w{@samp{This is \$2.}} prints
12347 @cindex form letters
12348 @cindex letters, form
12349 Using the @code{nx} and @code{rd} requests,
12350 it is easy to set up form letters. The form
12351 letter template is constructed like this, putting the following lines
12352 into a file called @file{repeat.let}:
12368 @cindex @code{ex} request, used with @code{nx} and @code{rd}
12370 When this is run, a file containing the following lines should be
12371 redirected in. Note that requests included in this file are executed
12372 as though they were part of the form letter. The last block of input
12373 is the @code{ex} request which tells @code{groff} to stop processing. If
12374 this was not there, @code{groff} would not know when to stop.
12378 708 NW 19th Av., #202
12385 San Diego, CA 92103
12393 Pipe the output of @code{gtroff} to the shell command(s)
12394 specified by @var{pipe}. This request must occur before
12395 @code{gtroff} has a chance to print anything.
12398 @cindex mode, safer
12399 @cindex unsafe mode
12400 @cindex mode, unsafe
12401 @code{pi} causes an error if used in safer mode (which is the default).
12402 Use @code{groff}'s or @code{troff}'s @option{-U} option to activate unsafe
12405 Multiple calls to @code{pi} are allowed, acting as a chain. For example,
12413 is the same as @w{@samp{.pi foo | bar}}.
12415 @cindex @code{groff}, and @code{pi} request
12416 @cindex @code{pi} request, and @code{groff}
12417 Note that the intermediate output format of @code{gtroff} is piped to
12418 the specified commands. Consequently, calling @code{groff} without the
12419 @option{-Z} option normally causes a fatal error.
12422 @DefreqList {sy, cmds}
12423 @DefregListEnd {systat}
12424 Execute the shell command(s) specified by @var{cmds}. The output is not
12425 saved anyplace, so it is up to the user to do so.
12428 @cindex mode, safer
12429 @cindex unsafe mode
12430 @cindex mode, unsafe
12431 This request causes an error if used in safer mode (which is the default).
12432 Use @code{groff}'s or @code{troff}'s @option{-U} option to activate unsafe
12435 For example, the following code fragment introduces the current time into a
12438 @cindex time, current
12439 @cindex current time
12442 .sy perl -e 'printf ".nr H %d\\n.nr M %d\\n.nr S %d\\n",\
12443 (localtime(time))[2,1,0]' > /tmp/x\n[$$]
12445 .sy rm /tmp/x\n[$$]
12450 Note that this works by having the @code{perl} script (run by @code{sy})
12451 print out the @code{nr} requests which set the number registers
12452 @code{H}, @code{M}, and @code{S}, and then reads those commands in with
12453 the @code{so} request.
12455 For most practical purposes, the number registers @code{seconds},
12456 @code{minutes}, and @code{hours} which are initialized at start-up of
12457 @code{gtroff} should be sufficient. Use the @code{af} request to get a
12464 \n[hours]:\n[minutes]:\n[seconds]
12467 @cindex @code{system()} return value register (@code{systat})
12468 The @code{systat} read-write number register contains the return value
12469 of the @code{system()} function executed by the last @code{sy} request.
12472 @DefreqList {open, stream file}
12473 @DefreqListEnd {opena, stream file}
12474 @cindex opening file (@code{open})
12475 @cindex file, opening (@code{open})
12476 @cindex appending to a file (@code{opena})
12477 @cindex file, appending to (@code{opena})
12478 Open the specified @var{file} for writing and
12479 associates the specified @var{stream} with it.
12481 The @code{opena} request is like @code{open}, but if the file exists,
12482 append to it instead of truncating it.
12485 @cindex mode, safer
12486 @cindex unsafe mode
12487 @cindex mode, unsafe
12488 Both @code{open} and @code{opena} cause an error if used in safer mode
12489 (which is the default). Use @code{groff}'s or @code{troff}'s @option{-U}
12490 option to activate unsafe mode.
12493 @DefreqList {write, stream data}
12494 @DefreqListEnd {writec, stream data}
12495 @cindex copy-in mode, and @code{write} requests
12496 @cindex mode, copy-in, and @code{write} requests
12497 @cindex writing to file (@code{write})
12498 @cindex file, writing to (@code{write})
12499 Write to the file associated with the specified @var{stream}.
12500 The stream must previously have
12501 been the subject of an open request. The remainder of the line is
12502 interpreted as the @code{ds} request reads its second argument: A
12503 leading @samp{"} is stripped, and it is read in copy-in mode.
12505 The @code{writec} request is like @code{write}, but only
12506 @code{write} appends a newline to the data.
12509 @Defreq {writem, stream xx}
12510 @cindex @code{asciify} request, and @code{writem}
12511 Write the contents of the macro or string @var{xx}
12512 to the file associated with the specified @var{stream}.
12514 @var{xx} is read in copy mode, i.e., already formatted elements are
12515 ignored. Consequently, diversions must be unformatted with the
12516 @code{asciify} request before calling @code{writem}. Usually, this
12517 means a loss of information.
12520 @Defreq {close, stream}
12521 @cindex closing file (@code{close})
12522 @cindex file, closing (@code{close})
12523 Close the specified @var{stream};
12524 the stream is no longer an acceptable argument to the
12525 @code{write} request.
12527 Here a simple macro to write an index entry.
12533 . write idx \\n[%] \\$*
12542 @DefescList {\\V, , e, }
12543 @DefescItem {\\V, @lparen{}, ev, }
12544 @DefescListEnd {\\V, @lbrack{}, env, @rbrack}
12545 Interpolate the contents of the specified environment variable
12546 @var{env} (one-character name@tie{}@var{e}, two-character name @var{ev})
12547 as returned by the function @code{getenv}. @code{\V} is interpreted
12552 @c =====================================================================
12554 @node Postprocessor Access, Miscellaneous, I/O, gtroff Reference
12555 @section Postprocessor Access
12556 @cindex postprocessor access
12557 @cindex access of postprocessor
12559 There are two escapes which give information directly to the
12560 postprocessor. This is particularly useful for embedding
12561 @sc{PostScript} into the final document.
12563 @Defesc {\\X, ', xxx, '}
12564 Embeds its argument into the @code{gtroff}
12565 output preceded with @w{@samp{x X}}.
12567 @cindex @code{\&}, in @code{\X}
12568 @cindex @code{\)}, in @code{\X}
12569 @cindex @code{\%}, in @code{\X}
12571 @cindex @code{\:}, in @code{\X}
12574 @cindex @code{\@r{<colon>}}, in @code{\X}
12576 The escapes @code{\&}, @code{\)}, @code{\%}, and @code{\:} are ignored
12577 within @code{\X}, @w{@samp{\ }} and @code{\~} are converted to single
12578 space characters. All other escapes (except @code{\\} which produces a
12579 backslash) cause an error.
12581 @kindex use_charnames_in_special
12582 @pindex DESC@r{, and @code{use_charnames_in_special}}
12583 @cindex @code{\X}, and special characters
12584 If the @samp{use_charnames_in_special} keyword is set in the @file{DESC}
12585 file, special characters no longer cause an error; the name @var{xx} is
12586 represented as @samp{\(@var{xx})} in the @w{@samp{x X}} output command.
12587 Additionally, the backslash is represented as @code{\\}.
12589 @samp{use_charnames_in_special} is currently used by @code{grohtml} only.
12592 @DefescList {\\Y, , n, }
12593 @DefescItem {\\Y, @lparen{}, nm, }
12594 @DefescListEnd {\\Y, @lbrack{}, name, @rbrack}
12595 This is approximately equivalent to @samp{\X'\*[@var{name}]'}
12596 (one-character name@tie{}@var{n}, two-character name @var{nm}).
12597 However, the contents of the string or macro @var{name} are not
12598 interpreted; also it is permitted for @var{name} to have been defined
12599 as a macro and thus contain newlines (it is not permitted for the
12600 argument to @code{\X} to contain newlines). The inclusion of
12601 newlines requires an extension to the @acronym{UNIX} @code{troff}
12602 output format, and confuses drivers that do not know about this
12603 extension (@pxref{Device Control Commands}).
12606 @xref{Output Devices}.
12609 @c =====================================================================
12611 @node Miscellaneous, Gtroff Internals, Postprocessor Access, gtroff Reference
12612 @section Miscellaneous
12614 This section documents parts of @code{gtroff} which cannot (yet) be
12615 categorized elsewhere in this manual.
12617 @Defreq {nm, [@Var{start} [@Var{inc} [@Var{space} [@Var{indent}]]]]}
12618 @cindex printing line numbers (@code{nm})
12619 @cindex line numbers, printing (@code{nm})
12620 @cindex numbers, line, printing (@code{nm})
12621 Print line numbers.
12622 @var{start} is the line number of the @emph{next}
12623 output line. @var{inc} indicates which line numbers are printed.
12624 For example, the value@tie{}5 means to emit only line numbers which
12625 are multiples of@tie{}5; this defaults to@tie{}1. @var{space} is the
12626 space to be left between the number and the text; this defaults to
12627 one digit space. The fourth argument is the indentation of the line
12628 numbers, defaulting to zero. Both @var{space} and @var{indent} are
12629 given as multiples of digit spaces; they can be negative also.
12630 Without any arguments, line numbers are turned off.
12632 @code{gtroff} reserves three digit spaces for the line number (which is
12633 printed right-justified) plus the amount given by @var{indent}; the
12634 output lines are concatenated to the line numbers, separated by
12635 @var{space}, and @emph{without} reducing the line length. Depending
12636 on the value of the horizontal page offset (as set with the
12637 @code{po} request), line numbers which are longer than the reserved
12638 space stick out to the left, or the whole line is moved to the right.
12640 Parameters corresponding to missing arguments are not changed; any
12641 non-digit argument (to be more precise, any argument starting with a
12642 character valid as a delimiter for identifiers) is also treated as
12645 If line numbering has been disabled with a call to @code{nm} without
12646 an argument, it can be reactivated with @samp{.nm +0}, using the
12647 previously active line numbering parameters.
12649 The parameters of @code{nm} are associated with the current environment
12650 (@pxref{Environments}). The current output line number is available
12651 in the number register @code{ln}.
12656 This test shows how line numbering works with groff.
12658 This test shows how line numbering works with groff.
12662 This test shows how line numbering works with groff.
12664 This test shows how line numbering works with groff.
12668 And here the result:
12671 This test shows how
12672 line numbering works
12673 999 with groff. This
12674 1000 test shows how line
12675 1001 numbering works with
12677 This test shows how
12680 This test shows how
12681 1005 line numbering
12686 @Defreq {nn, [@Var{skip}]}
12687 Temporarily turn off line numbering. The argument is the number
12688 of lines not to be numbered; this defaults to@tie{}1.
12691 @Defreq {mc, glyph [@Var{dist}]}
12692 @cindex margin glyph (@code{mc})
12693 @cindex glyph, for margins (@code{mc})
12694 Print a @dfn{margin character} to the right of the
12695 text.@footnote{@dfn{Margin character} is a misnomer since it is an
12696 output glyph.} The first argument is the glyph to be
12697 printed. The second argument is the distance away from the right
12698 margin. If missing, the previously set value is used; default is
12699 10@dmn{pt}). For text lines that are too long (that is, longer than
12700 the text length plus @var{dist}), the margin character is directly
12701 appended to the lines.
12703 With no arguments the margin character is turned off.
12704 If this occurs before a break, no margin character is printed.
12706 @cindex @code{tl} request, and @code{mc}
12707 For empty lines and lines produced by the @code{tl} request no margin
12708 character is emitted.
12710 The margin character is associated with the current environment
12711 (@pxref{Environments}).
12715 This is quite useful for indicating text that has changed, and, in fact,
12716 there are programs available for doing this (they are called
12717 @code{nrchbar} and @code{changebar} and can be found in any
12718 @samp{comp.sources.unix} archive.
12723 This paragraph is highlighted with a margin
12726 Note that vertical space isn't marked.
12730 But we can fake it with `\&'.
12736 This paragraph is highlighted |
12737 with a margin character. |
12739 Note that vertical space isn't |
12742 But we can fake it with `\&'. |
12746 @DefreqList {psbb, filename}
12750 @DefregListEnd {ury}
12751 @cindex PostScript, bounding box
12752 @cindex bounding box
12753 Retrieve the bounding box of the PostScript image
12754 found in @var{filename}.
12755 The file must conform to
12756 Adobe's @dfn{Document Structuring Conventions} (DSC);
12757 the command searches for a @code{%%BoundingBox} comment
12758 and extracts the bounding box values into the number registers
12759 @code{llx}, @code{lly}, @code{urx}, and @code{ury}.
12760 If an error occurs (for example, @code{psbb} cannot find
12761 the @code{%%BoundingBox} comment),
12762 it sets the four number registers to zero.
12766 @c =====================================================================
12768 @node Gtroff Internals, Debugging, Miscellaneous, gtroff Reference
12769 @section @code{gtroff} Internals
12771 @cindex input token
12772 @cindex token, input
12773 @cindex output node
12774 @cindex node, output
12775 @code{gtroff} processes input in three steps. One or more input
12776 characters are converted to an @dfn{input token}.@footnote{Except the
12777 escapes @code{\f}, @code{\F}, @code{\H}, @code{\m}, @code{\M}, @code{\R},
12778 @code{\s}, and @code{\S} which are processed immediately if not in
12779 copy-in mode.} Then, one or more input tokens are converted to an
12780 @dfn{output node}. Finally, output nodes are converted to the
12781 intermediate output language understood by all output devices.
12783 Actually, before step one happens, @code{gtroff} converts certain
12784 escape sequences into reserved input characters (not accessible by
12785 the user); such reserved characters are used for other internal
12786 processing also -- this is the very reason why not all characters
12787 are valid input. @xref{Identifiers}, for more on this topic.
12789 For example, the input string @samp{fi\[:u]} is converted into a
12790 character token @samp{f}, a character token @samp{i}, and a special
12791 token @samp{:u} (representing u@tie{}umlaut). Later on, the character
12792 tokens @samp{f} and @samp{i} are merged to a single output node
12793 representing the ligature glyph @samp{fi} (provided the current font
12794 has a glyph for this ligature); the same happens with @samp{:u}. All
12795 output glyph nodes are `processed' which means that they are invariably
12796 associated with a given font, font size, advance width, etc. During
12797 the formatting process, @code{gtroff} itself adds various nodes to
12798 control the data flow.
12800 Macros, diversions, and strings collect elements in two chained lists:
12801 a list of input tokens which have been passed unprocessed, and a list
12802 of output nodes. Consider the following the diversion.
12814 It contains these elements.
12816 @multitable {@i{vertical size node}} {token list} {element number}
12817 @item node list @tab token list @tab element number
12819 @item @i{line start node} @tab --- @tab 1
12820 @item @i{glyph node @code{a}} @tab --- @tab 2
12821 @item @i{word space node} @tab --- @tab 3
12822 @item --- @tab @code{b} @tab 4
12823 @item --- @tab @code{\n} @tab 5
12824 @item @i{glyph node @code{c}} @tab --- @tab 6
12825 @item @i{vertical size node} @tab --- @tab 7
12826 @item @i{vertical size node} @tab --- @tab 8
12827 @item --- @tab @code{\n} @tab 9
12830 @cindex @code{\v}, internal representation
12832 Elements 1, 7, and@tie{}8 are inserted by @code{gtroff}; the latter two
12833 (which are always present) specify the vertical extent of the last
12834 line, possibly modified by @code{\x}. The @code{br} request finishes
12835 the current partial line, inserting a newline input token which is
12836 subsequently converted to a space when the diversion is reread. Note
12837 that the word space node has a fixed width which isn't stretchable
12838 anymore. To convert horizontal space nodes back to input tokens, use
12839 the @code{unformat} request.
12841 Macros only contain elements in the token list (and the node list is
12842 empty); diversions and strings can contain elements in both lists.
12844 Note that the @code{chop} request simply reduces the number of elements in a
12845 macro, string, or diversion by one. Exceptions are @dfn{compatibility save}
12846 and @dfn{compatibility ignore} input tokens which are ignored. The
12847 @code{substring} request also ignores those input tokens.
12849 Some requests like @code{tr} or @code{cflags} work on glyph
12850 identifiers only; this means that the associated glyph can be changed
12851 without destroying this association. This can be very helpful for
12852 substituting glyphs. In the following example, we assume that
12853 glyph @samp{foo} isn't available by default, so we provide a
12854 substitution using the @code{fchar} request and map it to input
12855 character @samp{x}.
12863 Now let us assume that we install an additional special font
12864 @samp{bar} which has glyph @samp{foo}.
12872 Since glyphs defined with @code{fchar} are searched before glyphs
12873 in special fonts, we must call @code{rchar} to remove the definition
12874 of the fallback glyph. Anyway, the translation is still active;
12875 @samp{x} now maps to the real glyph @samp{foo}.
12878 @c =====================================================================
12880 @node Debugging, Implementation Differences, Gtroff Internals, gtroff Reference
12884 @code{gtroff} is not easy to debug, but there are some useful features
12885 and strategies for debugging.
12887 @Defreq {lf, line [@Var{filename}]}
12889 @cindex multi-file documents
12890 @cindex documents, multi-file
12891 @cindex setting input line number (@code{lf})
12892 @cindex input line number, setting (@code{lf})
12893 @cindex number, input line, setting (@code{lf})
12894 Change the line number and optionally the file name @code{gtroff} shall
12895 use for error and warning messages. @var{line} is the input line number
12896 of the @emph{next} line.
12898 Without argument, the request is ignored.
12900 This is a debugging aid for documents which are split into many files,
12901 then put together with @code{soelim} and other preprocessors. Usually,
12902 it isn't invoked manually.
12904 Note that other @code{troff} implementations (including the original
12905 @acronym{AT&T} version) handle @code{lf} differently. For them,
12906 @var{line} changes the line number of the @emph{current} line.
12909 @DefreqList {tm, string}
12910 @DefreqItem {tm1, string}
12911 @DefreqListEnd {tmc, string}
12912 @cindex printing to stderr (@code{tm}, @code{tm1}, @code{tmc})
12913 @cindex stderr, printing to (@code{tm}, @code{tm1}, @code{tmc})
12914 Send @var{string} to the standard error output;
12915 this is very useful for printing debugging messages among other things.
12917 @var{string} is read in copy mode.
12919 The @code{tm} request ignores leading spaces of @var{string}; @code{tm1}
12920 handles its argument similar to the @code{ds} request: a leading double
12921 quote in @var{string} is stripped to allow initial blanks.
12923 The @code{tmc} request is similar to @code{tm1} but does
12924 not append a newline (as is done in @code{tm} and @code{tm1}).
12927 @Defreq {ab, [@Var{string}]}
12928 @cindex aborting (@code{ab})
12929 Similar to the @code{tm} request, except that
12930 it causes @code{gtroff} to stop processing. With no argument it
12931 prints @samp{User Abort.} to standard error.
12935 @cindex @code{ex} request, use in debugging
12936 @cindex exiting (@code{ex})
12937 The @code{ex} request also causes @code{gtroff} to stop processing;
12938 see also @ref{I/O}.
12941 When doing something involved it is useful to leave the debugging
12942 statements in the code and have them turned on by a command line flag.
12945 .if \n(DB .tm debugging output
12949 To activate these statements say
12955 If it is known in advance that there will be many errors and no useful
12956 output, @code{gtroff} can be forced to suppress formatted output with
12957 the @option{-z} flag.
12960 @cindex dumping symbol table (@code{pm})
12961 @cindex symbol table, dumping (@code{pm})
12962 Print the entire symbol table on @code{stderr}. Names of all defined
12963 macros, strings, and diversions are print together with their size in
12964 bytes. Since @code{gtroff} sometimes adds nodes by itself, the
12965 returned size can be larger than expected.
12967 This request differs from @acronym{UNIX} @code{troff}: @code{gtroff}
12968 reports the sizes of diversions, ignores an additional argument to
12969 print only the total of the sizes, and the size isn't returned in
12970 blocks of 128 characters.
12974 @cindex dumping number registers (@code{pnr})
12975 @cindex number registers, dumping (@code{pnr})
12976 Print the names and contents of all
12977 currently defined number registers on @code{stderr}.
12981 @cindex dumping traps (@code{ptr})
12982 @cindex traps, dumping (@code{ptr})
12983 Print the names and positions of all traps
12984 (not including input line traps and diversion traps) on @code{stderr}.
12985 Empty slots in the page trap list are printed as well, because they can
12986 affect the priority of subsequently planted traps.
12990 @cindex flush output (@code{fl})
12991 @cindex output, flush (@code{fl})
12992 @cindex interactive use of @code{gtroff}
12993 @cindex @code{gtroff}, interactive use
12994 Instruct @code{gtroff} to flush its output immediately. The intent
12995 is for interactive use, but this behaviour is currently not
12996 implemented in @code{gtroff}. Contrary to @acronym{UNIX} @code{troff},
12997 TTY output is sent to a device driver also (@code{grotty}), making it
12998 non-trivial to communicate interactively.
13000 This request causes a line break.
13003 @Defreq {backtrace, }
13004 @cindex backtrace of input stack (@code{backtrace})
13005 @cindex input stack, backtrace (@code{backtrace})
13006 Print a backtrace of the input stack to the standard error stream.
13008 Consider the following in file @file{test}:
13022 On execution, @code{gtroff} prints the following:
13025 test:2: backtrace: macro `xxx'
13026 test:5: backtrace: macro `yyy'
13027 test:8: backtrace: file `test'
13030 The option @option{-b} of @code{gtroff} internally calls a variant of
13031 this request on each error and warning.
13035 @cindex input stack, setting limit
13036 Use the @code{slimit} number register
13037 to set the maximum number of objects on the input stack.
13038 If @code{slimit} is less than or equal to@tie{}0,
13039 there is no limit set.
13040 With no limit, a buggy recursive macro can exhaust virtual memory.
13042 The default value is 1000; this is a compile-time constant.
13045 @Defreq {warnscale, si}
13046 Set the scaling indicator used in warnings to @var{si}. Valid values for
13047 @var{si} are @samp{u}, @samp{i}, @samp{c}, @samp{p}, and @samp{P}. At
13048 startup, it is set to @samp{i}.
13051 @Defreq {spreadwarn, [@Var{limit}]}
13052 Make @code{gtroff} emit a warning if the additional space inserted for
13053 each space between words in an output line is larger or equal to
13054 @var{limit}. A negative value is changed to zero; no argument toggles the
13055 warning on and off without changing @var{limit}. The default scaling
13056 indicator is @samp{m}. At startup, @code{spreadwarn} is deactivated, and
13057 @var{limit} is set to 3@dmn{m}.
13066 will cause a warning if @code{gtroff} must add 0.2@dmn{m} or more for each
13067 interword space in a line.
13069 This request is active only if text is justified to both margins (using
13074 @code{gtroff} has command line options for printing out more warnings
13075 (@option{-w}) and for printing backtraces (@option{-b}) when a warning
13076 or an error occurs. The most verbose level of warnings is @option{-ww}.
13078 @DefreqList {warn, [@Var{flags}]}
13079 @DefregListEnd {.warn}
13080 @cindex level of warnings (@code{warn})
13081 @cindex warnings, level (@code{warn})
13082 Control the level of warnings checked for. The @var{flags} are the sum
13083 of the numbers associated with each warning that is to be enabled; all
13084 other warnings are disabled. The number associated with each warning is
13085 listed below. For example, @w{@code{.warn 0}} disables all warnings,
13086 and @w{@code{.warn 1}} disables all warnings except that about missing
13087 glyphs. If no argument is given, all warnings are enabled.
13089 The read-only number register @code{.warn} contains the current warning
13097 @c ---------------------------------------------------------------------
13099 @node Warnings, , Debugging, Debugging
13100 @subsection Warnings
13103 The warnings that can be given to @code{gtroff} are divided into the
13104 following categories. The name associated with each warning is used by
13105 the @option{-w} and @option{-W} options; the number is used by the
13106 @code{warn} request and by the @code{.warn} register.
13111 Non-existent glyphs.@footnote{@code{char} is a misnomer since it reports
13112 missing glyphs -- there aren't missing input characters, only invalid
13113 ones.} This is enabled by default.
13117 Invalid numeric expressions. This is enabled by default.
13118 @xref{Expressions}.
13124 In fill mode, lines which could not be broken so that their length was
13125 less than the line length. This is enabled by default.
13129 Missing or mismatched closing delimiters.
13133 @cindex @code{ie} request, and warnings
13134 @cindex @code{el} request, and warnings
13135 Use of the @code{el} request with no matching @code{ie} request.
13140 Meaningless scaling indicators.
13144 Out of range arguments.
13148 Dubious syntax in numeric expressions.
13152 @cindex @code{di} request, and warnings
13153 @cindex @code{da} request, and warnings
13154 Use of @code{di} or @code{da} without an argument when there is no
13159 @cindex @code{de}, @code{de1}, @code{dei} requests, and warnings
13160 @cindex @code{am}, @code{am1}, @code{ami} requests, and warnings
13161 @cindex @code{ds}, @code{ds1} requests, and warnings
13162 @cindex @code{as}, @code{as1} requests, and warnings
13163 @cindex @code{di} request, and warnings
13164 @cindex @code{da} request, and warnings
13165 @cindex @code{box}, @code{boxa} requests, and warnings
13166 @cindex @code{\*}, and warnings
13167 Use of undefined strings, macros and diversions. When an undefined
13168 string, macro, or diversion is used, that string is automatically
13169 defined as empty. So, in most cases, at most one warning is given
13174 @cindex @code{nr} request, and warnings
13175 @cindex @code{\R}, and warnings
13176 @cindex @code{\n}, and warnings
13177 Use of undefined number registers. When an undefined number register is
13178 used, that register is automatically defined to have a value of@tie{}0.
13179 So, in most cases, at most one warning is given for use of a particular
13184 @cindex @code{\t}, and warnings
13185 Use of a tab character where a number was expected.
13189 @cindex @code{\@}}, and warnings
13190 Use of @code{\@}} where a number was expected.
13194 Requests that are missing non-optional arguments.
13198 Invalid input characters.
13202 Unrecognized escape sequences. When an unrecognized escape sequence
13203 @code{\@var{X}} is encountered, the escape character is ignored, and
13204 @var{X} is printed.
13208 @cindex compatibility mode
13209 Missing space between a request or macro and its argument. This warning
13210 is given when an undefined name longer than two characters is
13211 encountered, and the first two characters of the name make a defined
13212 name. The request or macro is not invoked. When this warning is
13213 given, no macro is automatically defined. This is enabled by default.
13214 This warning never occurs in compatibility mode.
13218 Non-existent fonts. This is enabled by default.
13222 Invalid escapes in text ignored with the @code{ig} request. These are
13223 conditions that are errors when they do not occur in ignored text.
13227 Color related warnings.
13230 All warnings except @samp{di}, @samp{mac} and @samp{reg}. It is
13231 intended that this covers all warnings that are useful with traditional
13239 @c =====================================================================
13241 @node Implementation Differences, , Debugging, gtroff Reference
13242 @section Implementation Differences
13243 @cindex implementation differences
13244 @cindex differences in implementation
13245 @cindex incompatibilities with @acronym{AT&T} @code{troff}
13246 @cindex compatibility mode
13247 @cindex mode, compatibility
13249 GNU @code{troff} has a number of features which cause incompatibilities
13250 with documents written with old versions of @code{troff}.
13253 @cindex names, long
13254 Long names cause some incompatibilities. @acronym{UNIX} @code{troff}
13261 @cindex @code{\*}, incompatibilities with @acronym{AT&T} @code{troff}
13262 @cindex @code{\n}, incompatibilities with @acronym{AT&T} @code{troff}
13264 as defining a string @samp{ab} with contents @samp{cd}. Normally, GNU
13265 @code{troff} interprets this as a call of a macro named
13266 @code{dsabcd}. Also @acronym{UNIX} @code{troff} interprets
13267 @code{\*[} or @code{\n[} as references to a string or number register
13268 called @samp{[}. In GNU @code{troff}, however, this is normally
13269 interpreted as the start of a long name. In compatibility mode GNU
13270 @code{troff} interprets long names in the traditional way
13271 (which means that they are not recognized as names).
13273 @DefreqList {cp, [@Var{n}]}
13274 @DefreqItem {do, cmd}
13275 @DefregListEnd {.C}
13276 If @var{n} is missing or non-zero, turn on compatibility mode;
13277 otherwise, turn it off.
13279 The read-only number register @code{.C} is@tie{}1 if compatibility mode is
13280 on, 0@tie{}otherwise.
13282 Compatibility mode can be also turned on with the @option{-C} command line
13285 The @code{do} request turns off compatibility mode
13286 while executing its arguments as a @code{gtroff} command.
13293 executes the @code{fam} request when compatibility mode
13296 @code{gtroff} restores the previous compatibility setting
13297 before interpreting any files sourced by the @var{cmd}.
13300 @cindex input level in delimited arguments
13301 @cindex delimited arguments, incompatibilities with @acronym{AT&T} @code{troff}
13302 Two other features are controlled by @option{-C}. If not in
13303 compatibility mode, GNU @code{troff} preserves the input level in
13304 delimited arguments:
13312 In compatibility mode, the string @samp{72def'} is returned; without
13313 @option{-C} the resulting string is @samp{168} (assuming a TTY output
13316 @cindex @code{\f}, incompatibilities with @acronym{AT&T} @code{troff}
13317 @cindex @code{\H}, incompatibilities with @acronym{AT&T} @code{troff}
13318 @cindex @code{\s}, incompatibilities with @acronym{AT&T} @code{troff}
13319 @cindex @code{\S}, incompatibilities with @acronym{AT&T} @code{troff}
13320 Finally, the escapes @code{\f}, @code{\H}, @code{\m}, @code{\M},
13321 @code{\R}, @code{\s}, and @code{\S} are transparent for recognizing the
13322 beginning of a line only in compatibility mode (this is a rather obscure
13323 feature). For example, the code
13333 prints @samp{Hallo!} in bold face if in compatibility mode, and
13334 @samp{.xx} in bold face otherwise.
13336 @cindex @code{\A}, incompatibilities with @acronym{AT&T} @code{troff}
13337 @cindex @code{\|}, incompatibilities with @acronym{AT&T} @code{troff}
13338 @cindex @code{\^}, incompatibilities with @acronym{AT&T} @code{troff}
13339 @cindex @code{\&}, incompatibilities with @acronym{AT&T} @code{troff}
13340 @cindex @code{\@{}, incompatibilities with @acronym{AT&T} @code{troff}
13341 @cindex @code{\@}}, incompatibilities with @acronym{AT&T} @code{troff}
13342 @cindex @code{\@key{SP}}, incompatibilities with @acronym{AT&T} @code{troff}
13343 @cindex @code{\'}, incompatibilities with @acronym{AT&T} @code{troff}
13344 @cindex @code{\`}, incompatibilities with @acronym{AT&T} @code{troff}
13345 @cindex @code{\-}, incompatibilities with @acronym{AT&T} @code{troff}
13346 @cindex @code{\_}, incompatibilities with @acronym{AT&T} @code{troff}
13347 @cindex @code{\!}, incompatibilities with @acronym{AT&T} @code{troff}
13348 @cindex @code{\%}, incompatibilities with @acronym{AT&T} @code{troff}
13349 @cindex @code{\c}, incompatibilities with @acronym{AT&T} @code{troff}
13350 GNU @code{troff} does not allow the use of the escape sequences
13351 @code{\|}, @code{\^}, @code{\&}, @code{\@{}, @code{\@}},
13352 @code{\@key{SP}}, @code{\'}, @code{\`}, @code{\-}, @code{\_}, @code{\!},
13353 @code{\%}, and @code{\c} in names of strings, macros, diversions, number
13354 registers, fonts or environments; @acronym{UNIX} @code{troff} does. The
13355 @code{\A} escape sequence (@pxref{Identifiers}) may be helpful in
13356 avoiding use of these escape sequences in names.
13358 @cindex fractional point sizes
13359 @cindex fractional type sizes
13360 @cindex point sizes, fractional
13361 @cindex type sizes, fractional
13362 @cindex sizes, fractional
13363 @cindex @code{ps} request, incompatibilities with @acronym{AT&T} @code{troff}
13364 Fractional point sizes cause one noteworthy incompatibility. In
13365 @acronym{UNIX} @code{troff} the @code{ps} request ignores scale
13366 indicators and thus
13373 sets the point size to 10@tie{}points, whereas in GNU @code{troff} it
13374 sets the point size to 10@tie{}scaled points. @xref{Fractional Type
13375 Sizes}, for more information.
13377 @cindex @code{bd} request, incompatibilities with @acronym{AT&T} @code{troff}
13378 @cindex @code{cs} request, incompatibilities with @acronym{AT&T} @code{troff}
13379 @cindex @code{tr} request, incompatibilities with @acronym{AT&T} @code{troff}
13380 @cindex @code{fp} request, incompatibilities with @acronym{AT&T} @code{troff}
13381 @cindex input characters and output glyphs, compatibility with @acronym{AT&T} @code{troff}
13382 @cindex output glyphs, and input characters,compatibility with @acronym{AT&T} @code{troff}
13383 @cindex characters, input, and output glyphs, compatibility with @acronym{AT&T} @code{troff}
13384 @cindex glyphs, output, and input characters, compatibility with @acronym{AT&T} @code{troff}
13385 In GNU @code{troff} there is a fundamental difference between
13386 (unformatted) input characters and (formatted) output glyphs.
13387 Everything that affects how a glyph is output is stored
13388 with the glyph node; once a glyph node has been constructed it is
13389 unaffected by any subsequent requests that are executed, including
13390 @code{bd}, @code{cs}, @code{tkf}, @code{tr}, or @code{fp} requests.
13391 Normally glyphs are constructed from input characters at the
13392 moment immediately before the glyph is added to the current output
13393 line. Macros, diversions and strings are all, in fact, the same type of
13394 object; they contain lists of input characters and glyph nodes in
13395 any combination. A glyph node does not behave like an input
13396 character for the purposes of macro processing; it does not inherit any
13397 of the special properties that the input character from which it was
13398 constructed might have had. For example,
13408 @cindex printing backslash (@code{\\}, @code{\e}, @code{\E}, @code{\[rs]})
13409 @cindex backslash, printing (@code{\\}, @code{\e}, @code{\E}, @code{\[rs]})
13410 @cindex @code{\e}, incompatibilities with @acronym{AT&T} @code{troff}
13411 @cindex @code{\!}, incompatibilities with @acronym{AT&T} @code{troff}
13412 @cindex @code{\?}, incompatibilities with @acronym{AT&T} @code{troff}
13413 @cindex transparent output, incompatibilities with @acronym{AT&T} @code{troff}
13414 @cindex output, transparent, incompatibilities with @acronym{AT&T} @code{troff}
13416 prints @samp{\\} in GNU @code{troff}; each pair of input backslashes
13417 is turned into one output backslash and the resulting output backslashes
13418 are not interpreted as escape characters when they are reread.
13419 @acronym{UNIX} @code{troff} would interpret them as escape characters
13420 when they were reread and would end up printing one @samp{\}. The
13421 correct way to obtain a printable backslash is to use the @code{\e}
13422 escape sequence: This always prints a single instance of the current
13423 escape character, regardless of whether or not it is used in a
13424 diversion; it also works in both GNU @code{troff} and @acronym{UNIX}
13425 @code{troff}.@footnote{To be completely independent of the current
13426 escape character, use @code{\(rs} which represents a reverse solidus
13427 (backslash) glyph.} To store, for some reason, an escape sequence in a
13428 diversion that will be interpreted when the diversion is reread, either
13429 use the traditional @code{\!} transparent output facility, or, if this
13430 is unsuitable, the new @code{\?} escape sequence.
13432 @xref{Diversions}, and @ref{Gtroff Internals}, for more information.
13436 @c =====================================================================
13437 @c =====================================================================
13439 @node Preprocessors, Output Devices, gtroff Reference, Top
13440 @chapter Preprocessors
13441 @cindex preprocessors
13443 This chapter describes all preprocessors that come with @code{groff} or
13444 which are freely available.
13457 @c =====================================================================
13459 @node geqn, gtbl, Preprocessors, Preprocessors
13460 @section @code{geqn}
13461 @cindex @code{eqn}, the program
13462 @cindex @code{geqn}, the program
13470 @c ---------------------------------------------------------------------
13472 @node Invoking geqn, , geqn, geqn
13473 @subsection Invoking @code{geqn}
13474 @cindex invoking @code{geqn}
13475 @cindex @code{geqn}, invoking
13480 @c =====================================================================
13482 @node gtbl, gpic, geqn, Preprocessors
13483 @section @code{gtbl}
13484 @cindex @code{tbl}, the program
13485 @cindex @code{gtbl}, the program
13493 @c ---------------------------------------------------------------------
13495 @node Invoking gtbl, , gtbl, gtbl
13496 @subsection Invoking @code{gtbl}
13497 @cindex invoking @code{gtbl}
13498 @cindex @code{gtbl}, invoking
13503 @c =====================================================================
13505 @node gpic, ggrn, gtbl, Preprocessors
13506 @section @code{gpic}
13507 @cindex @code{pic}, the program
13508 @cindex @code{gpic}, the program
13516 @c ---------------------------------------------------------------------
13518 @node Invoking gpic, , gpic, gpic
13519 @subsection Invoking @code{gpic}
13520 @cindex invoking @code{gpic}
13521 @cindex @code{gpic}, invoking
13526 @c =====================================================================
13528 @node ggrn, grap, gpic, Preprocessors
13529 @section @code{ggrn}
13530 @cindex @code{grn}, the program
13531 @cindex @code{ggrn}, the program
13539 @c ---------------------------------------------------------------------
13541 @node Invoking ggrn, , ggrn, ggrn
13542 @subsection Invoking @code{ggrn}
13543 @cindex invoking @code{ggrn}
13544 @cindex @code{ggrn}, invoking
13549 @c =====================================================================
13551 @node grap, grefer, ggrn, Preprocessors
13552 @section @code{grap}
13553 @cindex @code{grap}, the program
13555 A free implementation of @code{grap}, written by Ted Faber,
13556 is available as an extra package from the following address:
13559 @uref{http://www.lunabase.org/~faber/Vault/software/grap/}
13563 @c =====================================================================
13565 @node grefer, gsoelim, grap, Preprocessors
13566 @section @code{grefer}
13567 @cindex @code{refer}, the program
13568 @cindex @code{grefer}, the program
13573 * Invoking grefer::
13576 @c ---------------------------------------------------------------------
13578 @node Invoking grefer, , grefer, grefer
13579 @subsection Invoking @code{grefer}
13580 @cindex invoking @code{grefer}
13581 @cindex @code{grefer}, invoking
13586 @c =====================================================================
13588 @node gsoelim, , grefer, Preprocessors
13589 @section @code{gsoelim}
13590 @cindex @code{soelim}, the program
13591 @cindex @code{gsoelim}, the program
13596 * Invoking gsoelim::
13599 @c ---------------------------------------------------------------------
13601 @node Invoking gsoelim, , gsoelim, gsoelim
13602 @subsection Invoking @code{gsoelim}
13603 @cindex invoking @code{gsoelim}
13604 @cindex @code{gsoelim}, invoking
13610 @c =====================================================================
13611 @c =====================================================================
13613 @node Output Devices, File formats, Preprocessors, Top
13614 @chapter Output Devices
13615 @cindex output devices
13616 @cindex devices for output
13621 * Special Characters::
13632 @c =====================================================================
13634 @node Special Characters, grotty, Output Devices, Output Devices
13635 @section Special Characters
13636 @cindex special characters
13637 @cindex characters, special
13644 @c =====================================================================
13646 @node grotty, grops, Special Characters, Output Devices
13647 @section @code{grotty}
13648 @cindex @code{grotty}, the program
13653 * Invoking grotty::
13656 @c ---------------------------------------------------------------------
13658 @node Invoking grotty, , grotty, grotty
13659 @subsection Invoking @code{grotty}
13660 @cindex invoking @code{grotty}
13661 @cindex @code{grotty}, invoking
13665 @c The following is no longer true; fix and extend it.
13668 @c @cindex Teletype
13669 @c @cindex ISO 6249 SGR
13670 @c @cindex terminal control sequences
13671 @c @cindex control sequences, for terminals
13672 @c For TTY output devices, underlining is done by emitting sequences of
13673 @c @samp{_} and @samp{\b} (the backspace character) before the actual
13674 @c character. Literally, this is printing an underline character, then
13675 @c moving back one character position, and printing the actual character
13676 @c at the same position as the underline character (similar to a
13677 @c typewriter). Usually, a modern terminal can't interpret this (and the
13678 @c original Teletype machines for which this sequence was appropriate are
13679 @c no longer in use). You need a pager program like @code{less} which
13680 @c translates this into ISO 6429 SGR sequences to control terminals.
13683 @c =====================================================================
13685 @node grops, grodvi, grotty, Output Devices
13686 @section @code{grops}
13687 @cindex @code{grops}, the program
13693 * Embedding PostScript::
13696 @c ---------------------------------------------------------------------
13698 @node Invoking grops, Embedding PostScript, grops, grops
13699 @subsection Invoking @code{grops}
13700 @cindex invoking @code{grops}
13701 @cindex @code{grops}, invoking
13705 @c ---------------------------------------------------------------------
13707 @node Embedding PostScript, , Invoking grops, grops
13708 @subsection Embedding @sc{PostScript}
13709 @cindex embedding PostScript
13710 @cindex PostScript, embedding
13715 @c =====================================================================
13717 @node grodvi, grolj4, grops, Output Devices
13718 @section @code{grodvi}
13719 @cindex @code{grodvi}, the program
13724 * Invoking grodvi::
13727 @c ---------------------------------------------------------------------
13729 @node Invoking grodvi, , grodvi, grodvi
13730 @subsection Invoking @code{grodvi}
13731 @cindex invoking @code{grodvi}
13732 @cindex @code{grodvi}, invoking
13737 @c =====================================================================
13739 @node grolj4, grolbp, grodvi, Output Devices
13740 @section @code{grolj4}
13741 @cindex @code{grolj4}, the program
13746 * Invoking grolj4::
13749 @c ---------------------------------------------------------------------
13751 @node Invoking grolj4, , grolj4, grolj4
13752 @subsection Invoking @code{grolj4}
13753 @cindex invoking @code{grolj4}
13754 @cindex @code{grolj4}, invoking
13759 @c =====================================================================
13761 @node grolbp, grohtml, grolj4, Output Devices
13762 @section @code{grolbp}
13763 @cindex @code{grolbp}, the program
13768 * Invoking grolbp::
13771 @c ---------------------------------------------------------------------
13773 @node Invoking grolbp, , grolbp, grolbp
13774 @subsection Invoking @code{grolbp}
13775 @cindex invoking @code{grolbp}
13776 @cindex @code{grolbp}, invoking
13781 @c =====================================================================
13783 @node grohtml, gxditview, grolbp, Output Devices
13784 @section @code{grohtml}
13785 @cindex @code{grohtml}, the program
13790 * Invoking grohtml::
13791 * grohtml specific registers and strings::
13794 @c ---------------------------------------------------------------------
13796 @node Invoking grohtml, grohtml specific registers and strings, grohtml, grohtml
13797 @subsection Invoking @code{grohtml}
13798 @cindex invoking @code{grohtml}
13799 @cindex @code{grohtml}, invoking
13803 @c ---------------------------------------------------------------------
13805 @node grohtml specific registers and strings, , Invoking grohtml, grohtml
13806 @subsection @code{grohtml} specific registers and strings
13807 @cindex registers specific to @code{grohtml}
13808 @cindex strings specific to @code{grohtml}
13809 @cindex @code{grohtml}, registers and strings
13811 @DefmpregList {ps4html, grohtml}
13812 @DefstrListEnd {www-image-template, grohtml}
13813 The registers @code{ps4html} and @code{www-image-template} are defined
13814 by the @code{pre-grohtml} preprocessor. @code{pre-grohtml} reads in
13815 the @code{troff} input, marks up the inline equations and passes the
13819 troff -Tps -rps4html=1 -dwww-image-template=@var{template}
13829 The PostScript device is used to create all the image files, and the
13830 register @code{ps4html} enables the macro sets to ignore floating
13831 keeps, footers, and headings.
13833 The register @code{www-image-template} is set to the user specified
13834 template name or the default name.
13838 @c =====================================================================
13840 @node gxditview, , grohtml, Output Devices
13841 @section @code{gxditview}
13842 @cindex @code{gxditview}, the program
13847 * Invoking gxditview::
13850 @c ---------------------------------------------------------------------
13852 @node Invoking gxditview, , gxditview, gxditview
13853 @subsection Invoking @code{gxditview}
13854 @cindex invoking @code{gxditview}
13855 @cindex @code{gxditview}, invoking
13862 @c =====================================================================
13863 @c =====================================================================
13865 @node File formats, Installation, Output Devices, Top
13866 @chapter File formats
13867 @cindex file formats
13868 @cindex formats, file
13870 All files read and written by @code{gtroff} are text files. The
13871 following two sections describe their format.
13879 @c =====================================================================
13881 @node gtroff Output, Font Files, File formats, File formats
13882 @section @code{gtroff} Output
13883 @cindex @code{gtroff}, output
13884 @cindex output, @code{gtroff}
13886 This section describes the intermediate output format of GNU
13887 @code{troff}. This output is produced by a run of @code{gtroff}
13888 before it is fed into a device postprocessor program.
13890 As @code{groff} is a wrapper program around @code{gtroff} that
13891 automatically calls a postprocessor, this output does not show up
13892 normally. This is why it is called @dfn{intermediate}.
13893 @code{groff} provides the option @option{-Z} to inhibit postprocessing,
13894 such that the produced intermediate output is sent to standard output
13895 just like calling @code{gtroff} manually.
13897 @cindex troff output
13898 @cindex output, troff
13899 @cindex intermediate output
13900 @cindex output, intermediate
13901 Here, the term @dfn{troff output} describes what is output by
13902 @code{gtroff}, while @dfn{intermediate output} refers to the language
13903 that is accepted by the parser that prepares this output for the
13904 postprocessors. This parser is smarter on whitespace and implements
13905 obsolete elements for compatibility, otherwise both formats are the
13906 same.@footnote{The parser and postprocessor for intermediate output
13907 can be found in the file@*
13908 @file{@var{groff-source-dir}/src/libs/libdriver/input.cpp}.}
13910 The main purpose of the intermediate output concept is to facilitate
13911 the development of postprocessors by providing a common programming
13912 interface for all devices. It has a language of its own that is
13913 completely different from the @code{gtroff} language. While the
13914 @code{gtroff} language is a high-level programming language for text
13915 processing, the intermediate output language is a kind of low-level
13916 assembler language by specifying all positions on the page for writing
13919 The intermediate output produced by @code{gtroff} is fairly readable,
13920 while output from @acronym{AT&T} @code{troff} is rather hard to
13921 understand because of strange habits that are still supported, but not
13922 used any longer by @code{gtroff}.
13925 * Language Concepts::
13926 * Command Reference::
13927 * Intermediate Output Examples::
13928 * Output Language Compatibility::
13931 @c ---------------------------------------------------------------------
13933 @node Language Concepts, Command Reference, gtroff Output, gtroff Output
13934 @subsection Language Concepts
13936 During the run of @code{gtroff}, the input data is cracked down to the
13937 information on what has to be printed at what position on the intended
13938 device. So the language of the intermediate output format can be quite
13939 small. Its only elements are commands with and without arguments.
13940 In this section, the term @dfn{command} always refers to the intermediate
13941 output language, and never to the @code{gtroff} language used for document
13942 formatting. There are commands for positioning and text writing, for drawing, and
13943 for device controlling.
13951 @node Separation, Argument Units, Language Concepts, Language Concepts
13952 @subsubsection Separation
13954 @acronym{AT&T} @code{troff} output has strange requirements on whitespace.
13955 The @code{gtroff} output parser, however, is smart about whitespace by
13956 making it maximally optional. The whitespace characters, i.e., the
13957 tab, space, and newline characters, always have a syntactical meaning.
13958 They are never printable because spacing within the output is always
13959 done by positioning commands.
13961 Any sequence of space or tab characters is treated as a single
13962 @dfn{syntactical space}. It separates commands and arguments, but is
13963 only required when there would occur a clashing between the command code
13964 and the arguments without the space. Most often, this happens when
13965 variable-length command names, arguments, argument lists, or command
13966 clusters meet. Commands and arguments with a known, fixed length need
13967 not be separated by syntactical space.
13969 A line break is a syntactical element, too. Every command argument can be
13970 followed by whitespace, a comment, or a newline character. Thus a
13971 @dfn{syntactical line break} is defined to consist of optional
13972 syntactical space that is optionally followed by a comment, and a
13975 The normal commands, those for positioning and text, consist of a
13976 single letter taking a fixed number of arguments. For historical reasons,
13977 the parser allows to stack such commands on the same line, but
13978 fortunately, in @code{gtroff}'s intermediate output, every command with
13979 at least one argument is followed by a line break, thus providing
13980 excellent readability.
13982 The other commands -- those for drawing and device controlling --
13983 have a more complicated structure; some recognize long command names,
13984 and some take a variable number of arguments. So all @samp{D} and
13985 @samp{x} commands were designed to request a syntactical line break
13986 after their last argument. Only one command, @w{@samp{x X}},
13987 has an argument that can stretch over several lines; all other
13988 commands must have all of their arguments on the same line as the
13989 command, i.e., the arguments may not be splitted by a line break.
13991 Empty lines (these are lines containing only space and/or a comment), can
13992 occur everywhere. They are just ignored.
13994 @node Argument Units, Document Parts, Separation, Language Concepts
13995 @subsubsection Argument Units
13997 Some commands take integer arguments that are assumed to represent
13998 values in a measurement unit, but the letter for the corresponding
13999 scale indicator is not written with the output command arguments.
14000 Most commands assume the scale indicator @samp{u}, the basic unit of
14001 the device, some use @samp{z}, the scaled point unit of the device,
14002 while others, such as the color commands, expect plain integers.
14004 Note that single characters can have the eighth bit set, as can the
14005 names of fonts and special characters. The names of characters and
14006 fonts can be of arbitrary length. A character that is to be printed
14007 will always be in the current font.
14009 A string argument is always terminated by the next whitespace
14010 character (space, tab, or newline); an embedded @samp{#} character is
14011 regarded as part of the argument, not as the beginning of a comment
14012 command. An integer argument is already terminated by the next
14013 non-digit character, which then is regarded as the first character of
14014 the next argument or command.
14016 @node Document Parts, , Argument Units, Language Concepts
14017 @subsubsection Document Parts
14019 A correct intermediate output document consists of two parts, the
14020 @dfn{prologue} and the @dfn{body}.
14022 The task of the prologue is to set the general device parameters
14023 using three exactly specified commands. @code{gtroff}'s prologue
14024 is guaranteed to consist of the following three lines (in that order):
14028 x res @var{n} @var{h} @var{v}
14033 with the arguments set as outlined in @ref{Device Control Commands}.
14034 Note that the parser for the intermediate output format is able to
14035 swallow additional whitespace and comments as well even in the
14038 The body is the main section for processing the document data.
14039 Syntactically, it is a sequence of any commands different from the
14040 ones used in the prologue. Processing is terminated as soon as the
14041 first @w{@samp{x stop}} command is encountered; the last line of any
14042 @code{gtroff} intermediate output always contains such a command.
14044 Semantically, the body is page oriented. A new page is started by a
14045 @samp{p} command. Positioning, writing, and drawing commands are
14046 always done within the current page, so they cannot occur before the
14047 first @samp{p} command. Absolute positioning (by the @samp{H} and
14048 @samp{V} commands) is done relative to the current page; all other
14049 positioning is done relative to the current location within this page.
14051 @c ---------------------------------------------------------------------
14053 @node Command Reference, Intermediate Output Examples, Language Concepts, gtroff Output
14054 @subsection Command Reference
14056 This section describes all intermediate output commands, both from
14057 @acronym{AT&T} @code{troff} as well as the @code{gtroff} extensions.
14060 * Comment Command::
14061 * Simple Commands::
14062 * Graphics Commands::
14063 * Device Control Commands::
14064 * Obsolete Command::
14067 @node Comment Command, Simple Commands, Command Reference, Command Reference
14068 @subsubsection Comment Command
14071 @item #@var{anything}@angles{end of line}
14072 A comment. Ignore any characters from the @samp{#} character up to
14073 the next newline character.
14075 This command is the only possibility for commenting in the intermediate
14076 output. Each comment can be preceded by arbitrary syntactical space;
14077 every command can be terminated by a comment.
14080 @node Simple Commands, Graphics Commands, Comment Command, Command Reference
14081 @subsubsection Simple Commands
14083 The commands in this subsection have a command code consisting of a
14084 single character, taking a fixed number of arguments. Most of them
14085 are commands for positioning and text writing. These commands are
14086 smart about whitespace. Optionally, syntactical space can be inserted
14087 before, after, and between the command letter and its arguments.
14088 All of these commands are stackable, i.e., they can be preceded by
14089 other simple commands or followed by arbitrary other commands on the
14090 same line. A separating syntactical space is only necessary when two
14091 integer arguments would clash or if the preceding argument ends with a
14096 .if (\n[@USE_ENV_STACK] == 1) \{\
14098 Open a new environment by copying the actual device configuration data
14099 to the environment stack.
14101 The current environment is setup by the device specification and
14102 manipulated by the setting commands.
14106 Close the actual environment (opened by a preceding
14108 and restore the previous environment from the environment
14109 stack as the actual device configuration data.
14111 \} \" endif @USE_ENV_STACK
14114 @item C @var{xxx}@angles{whitespace}
14115 Print a special character named @var{xxx}. The trailing
14116 syntactical space or line break is necessary to allow glyph names
14117 of arbitrary length. The glyph is printed at the current print
14118 position; the glyph's size is read from the font file. The print
14119 position is not changed.
14122 Print glyph@tie{}@var{g} at the current print position;@footnote{@samp{c}
14123 is actually a misnomer since it outputs a glyph.} the glyph's size is
14124 read from the font file. The print position is not changed.
14127 Set font to font number@tie{}@var{n} (a non-negative integer).
14130 Move right to the absolute vertical position@tie{}@var{n} (a
14131 non-negative integer in basic units @samp{u} relative to left edge
14135 Move @var{n} (a non-negative integer) basic units @samp{u} horizontally
14136 to the right. The original @acronym{UNIX} troff manual allows negative
14137 values for @var{n} also, but @code{gtroff} doesn't use this.
14139 @item m @var{color-scheme} @r{[}@var{component} @dots{}@r{]}
14140 Set the color for text (glyphs), line drawing, and the outline of
14141 graphic objects using different color schemes; the analoguous command
14142 for the filling color of graphic objects is @samp{DF}. The color
14143 components are specified as integer arguments between 0 and 65536.
14144 The number of color components and their meaning vary for the
14145 different color schemes. These commands are generated by
14146 @code{gtroff}'s escape sequence @code{\m}. No position changing.
14147 These commands are a @code{gtroff} extension.
14150 @item mc @var{cyan} @var{magenta} @var{yellow}
14151 Set color using the CMY color scheme, having the 3@tie{}color components
14152 @var{cyan}, @var{magenta}, and @var{yellow}.
14155 Set color to the default color value (black in most cases).
14156 No component arguments.
14158 @item mg @var{gray}
14159 Set color to the shade of gray given by the argument, an integer
14160 between 0 (black) and 65536 (white).
14162 @item mk @var{cyan} @var{magenta} @var{yellow} @var{black}
14163 Set color using the CMYK color scheme, having the 4@tie{}color components
14164 @var{cyan}, @var{magenta}, @var{yellow}, and @var{black}.
14166 @item mr @var{red} @var{green} @var{blue}
14167 Set color using the RGB color scheme, having the 3@tie{}color components
14168 @var{red}, @var{green}, and @var{blue}.
14173 Print glyph with index@tie{}@var{n} (a non-negative integer) of the
14174 current font. This command is a @code{gtroff} extension.
14176 @item n @var{b} @var{a}
14177 Inform the device about a line break, but no positioning is done by
14178 this command. In @acronym{AT&T} @code{troff}, the integer arguments
14179 @var{b} and@tie{}@var{a} informed about the space before and after the
14180 current line to make the intermediate output more human readable
14181 without performing any action. In @code{groff}, they are just ignored, but
14182 they must be provided for compatibility reasons.
14185 Begin a new page in the outprint. The page number is set
14186 to@tie{}@var{n}. This page is completely independent of pages formerly
14187 processed even if those have the same page number. The vertical
14188 position on the outprint is automatically set to@tie{}0. All
14189 positioning, writing, and drawing is always done relative to a page,
14190 so a @samp{p} command must be issued before any of these commands.
14193 Set point size to @var{n}@tie{}scaled points (this is unit @samp{z}).
14194 @acronym{AT&T} @code{troff} used the unit points (@samp{p}) instead.
14195 @xref{Output Language Compatibility}.
14197 @item t @var{xxx}@angles{whitespace}
14198 @itemx t @var{xxx} @var{dummy-arg}@angles{whitespace}
14199 Print a word, i.e., a sequence of characters @var{xxx} representing
14200 output glyphs which names are single characters, terminated by
14201 a space character or a line break; an optional second integer argument
14202 is ignored (this allows the formatter to generate an even number of
14203 arguments). The first glyph should be printed at the current
14204 position, the current horizontal position should then be increased by
14205 the width of the first glyph, and so on for each glyph.
14206 The widths of the glyphs are read from the font file, scaled for the
14207 current point size, and rounded to a multiple of the horizontal
14208 resolution. Special characters cannot be printed using this command
14209 (use the @samp{C} command for special characters). This command is a
14210 @code{gtroff} extension; it is only used for devices whose @file{DESC}
14211 file contains the @code{tcommand} keyword (@pxref{DESC File Format}).
14213 @item u @var{n} @var{xxx}@angles{whitespace}
14214 Print word with track kerning. This is the same as the @samp{t}
14215 command except that after printing each glyph, the current
14216 horizontal position is increased by the sum of the width of that
14217 glyph and@tie{}@var{n} (an integer in basic units @samp{u}).
14218 This command is a @code{gtroff} extension; it is only used for devices
14219 whose @file{DESC} file contains the @code{tcommand} keyword
14220 (@pxref{DESC File Format}).
14223 Move down to the absolute vertical position@tie{}@var{n} (a
14224 non-negative integer in basic units @samp{u}) relative to upper edge
14228 Move @var{n}@tie{}basic units @samp{u} down (@var{n} is a non-negative
14229 integer). The original @acronym{UNIX} troff manual allows negative
14230 values for @var{n} also, but @code{gtroff} doesn't use this.
14233 Informs about a paddable white space to increase readability.
14234 The spacing itself must be performed explicitly by a move command.
14238 @node Graphics Commands, Device Control Commands, Simple Commands, Command Reference
14239 @subsubsection Graphics Commands
14241 Each graphics or drawing command in the intermediate output starts
14242 with the letter @samp{D}, followed by one or two characters that
14243 specify a subcommand; this is followed by a fixed or variable number
14244 of integer arguments that are separated by a single space character.
14245 A @samp{D} command may not be followed by another command on the same line
14246 (apart from a comment), so each @samp{D} command is terminated by a
14247 syntactical line break.
14249 @code{gtroff} output follows the classical spacing rules (no space
14250 between command and subcommand, all arguments are preceded by a
14251 single space character), but the parser allows optional space between
14252 the command letters and makes the space before the first argument
14253 optional. As usual, each space can be any sequence of tab and space
14256 Some graphics commands can take a variable number of arguments.
14257 In this case, they are integers representing a size measured in basic
14258 units @samp{u}. The arguments called @var{h1}, @var{h2}, @dots{},
14259 @var{hn} stand for horizontal distances where positive means right,
14260 negative left. The arguments called @var{v1}, @var{v2}, @dots{},
14261 @var{vn} stand for vertical distances where positive means down,
14262 negative up. All these distances are offsets relative to the current
14265 Each graphics command directly corresponds to a similar @code{gtroff}
14266 @code{\D} escape sequence. @xref{Drawing Requests}.
14268 Unknown @samp{D} commands are assumed to be device-specific.
14269 Its arguments are parsed as strings; the whole information is then
14270 sent to the postprocessor.
14272 In the following command reference, the syntax element
14273 @angles{line break} means a syntactical line break as defined above.
14276 @item D~ @var{h1} @var{v1} @var{h2} @var{v2} @dots{} @var{hn} @var{vn}@angles{line break}
14277 Draw B-spline from current position to offset (@var{h1},@var{v1}),
14278 then to offset (@var{h2},@var{v2}), if given, etc.@: up to
14279 (@var{hn},@var{vn}). This command takes a variable number of argument
14280 pairs; the current position is moved to the terminal point of the drawn
14283 @item Da @var{h1} @var{v1} @var{h2} @var{v2}@angles{line break}
14284 Draw arc from current position to
14285 (@var{h1},@var{v1})@math{+}(@var{h2},@var{v2}) with center at
14286 (@var{h1},@var{v1}); then move the current position to the final point
14289 @item DC @var{d}@angles{line break}
14290 @itemx DC @var{d} @var{dummy-arg}@angles{line break}
14291 Draw a solid circle using the current fill color with
14292 diameter@tie{}@var{d} (integer in basic units @samp{u}) with leftmost
14293 point at the current position; then move the current position to the
14294 rightmost point of the circle. An optional second integer argument is
14295 ignored (this allows the formatter to generate an even number of
14296 arguments). This command is a @code{gtroff} extension.
14298 @item Dc @var{d}@angles{line break}
14299 Draw circle line with diameter@tie{}@var{d} (integer in basic units
14300 @samp{u}) with leftmost point at the current position; then move the
14301 current position to the rightmost point of the circle.
14303 @item DE @var{h} @var{v}@angles{line break}
14304 Draw a solid ellipse in the current fill color with a horizontal
14305 diameter of@tie{}@var{h} and a vertical diameter of@tie{}@var{v} (both
14306 integers in basic units @samp{u}) with the leftmost point at the
14307 current position; then move to the rightmost point of the ellipse.
14308 This command is a @code{gtroff} extension.
14310 @item De @var{h} @var{v}@angles{line break}
14311 Draw an outlined ellipse with a horizontal diameter of@tie{}@var{h}
14312 and a vertical diameter of@tie{}@var{v} (both integers in basic units
14313 @samp{u}) with the leftmost point at current position; then move to
14314 the rightmost point of the ellipse.
14316 @item DF @var{color-scheme} @r{[}@var{component} @dots{}@r{]}@angles{line break}
14317 Set fill color for solid drawing objects using different color
14318 schemes; the analoguous command for setting the color of text, line
14319 graphics, and the outline of graphic objects is @samp{m}.
14320 The color components are specified as integer arguments between 0 and
14321 65536. The number of color components and their meaning vary for the
14322 different color schemes. These commands are generated by @code{gtroff}'s
14323 escape sequences @w{@code{\D'F @dots{}'}} and @code{\M} (with no other
14324 corresponding graphics commands). No position changing. This command
14325 is a @code{gtroff} extension.
14328 @item DFc @var{cyan} @var{magenta} @var{yellow}@angles{line break}
14329 Set fill color for solid drawing objects using the CMY color scheme,
14330 having the 3@tie{}color components @var{cyan}, @var{magenta}, and
14333 @item DFd@angles{line break}
14334 Set fill color for solid drawing objects to the default fill color value
14335 (black in most cases). No component arguments.
14337 @item DFg @var{gray}@angles{line break}
14338 Set fill color for solid drawing objects to the shade of gray given by
14339 the argument, an integer between 0 (black) and 65536 (white).
14341 @item DFk @var{cyan} @var{magenta} @var{yellow} @var{black}@angles{line break}
14342 Set fill color for solid drawing objects using the CMYK color scheme,
14343 having the 4@tie{}color components @var{cyan}, @var{magenta}, @var{yellow},
14346 @item DFr @var{red} @var{green} @var{blue}@angles{line break}
14347 Set fill color for solid drawing objects using the RGB color scheme,
14348 having the 3@tie{}color components @var{red}, @var{green}, and @var{blue}.
14352 @item Df @var{n}@angles{line break}
14353 The argument@tie{}@var{n} must be an integer in the range @math{-32767}
14357 @item @math{0 @LE @var{n} @LE 1000}
14358 Set the color for filling solid drawing objects to a shade of gray,
14359 where 0 corresponds to solid white, 1000 (the default) to solid black,
14360 and values in between to intermediate shades of gray; this is
14361 obsoleted by command @samp{DFg}.
14363 @item @math{@var{n} < 0} or @math{@var{n} > 1000}
14364 Set the filling color to the color that is currently being used for
14365 the text and the outline, see command @samp{m}. For example, the
14374 sets all colors to blue.
14379 No position changing. This command is a @code{gtroff} extension.
14381 @item Dl @var{h} @var{v}@angles{line break}
14382 Draw line from current position to offset (@var{h},@var{v}) (integers
14383 in basic units @samp{u}); then set current position to the end of the
14386 @item Dp @var{h1} @var{v1} @var{h2} @var{v2} @dots{} @var{hn} @var{vn}@angles{line break}
14387 Draw a polygon line from current position to offset (@var{h1},@var{v1}),
14388 from there to offset (@var{h2},@var{v2}), etc.@: up to offset
14389 (@var{hn},@var{vn}), and from there back to the starting position.
14390 For historical reasons, the position is changed by adding the sum of
14391 all arguments with odd index to the actual horizontal position and the
14392 even ones to the vertical position. Although this doesn't make sense
14393 it is kept for compatibility.
14395 As the polygon is closed, the end of drawing is the starting point, so
14396 the position doesn't change.
14398 This command is a @code{gtroff} extension.
14400 @item Dp @var{h1} @var{v1} @var{h2} @var{v2} @dots{} @var{hn} @var{vn}@angles{line break}
14401 Draw a solid polygon in the current fill color rather than an outlined
14402 polygon, using the same arguments and positioning as the corresponding
14405 No position changing.
14407 This command is a @code{gtroff} extension.
14409 @item Dt @var{n}@angles{line break}
14410 Set the current line thickness to@tie{}@var{n} (an integer in basic
14411 units @samp{u}) if @math{@var{n}>0}; if @math{@var{n}=0} select the
14412 smallest available line thickness; if @math{@var{n}<0} set the line
14413 thickness proportional to the point size (this is the default before
14414 the first @samp{Dt} command was specified). For historical reasons,
14415 the horizontal position is changed by adding the argument to the actual
14416 horizontal position, while the vertical position is not changed.
14417 Although this doesn't make sense it is kept for compatibility.
14419 No position changing.
14421 This command is a @code{gtroff} extension.
14425 @node Device Control Commands, Obsolete Command, Graphics Commands, Command Reference
14426 @subsubsection Device Control Commands
14428 Each device control command starts with the letter @samp{x},
14429 followed by a space character (optional or arbitrary space or tab in
14430 @code{gtroff}) and a subcommand letter or word; each argument (if any)
14431 must be preceded by a syntactical space. All @samp{x} commands are
14432 terminated by a syntactical line break; no device control command can
14433 be followed by another command on the same line (except a comment).
14435 The subcommand is basically a single letter, but to increase
14436 readability, it can be written as a word, i.e., an arbitrary sequence
14437 of characters terminated by the next tab, space, or newline character.
14438 All characters of the subcommand word but the first are simply ignored.
14439 For example, @code{gtroff} outputs the initialization command
14440 @w{@samp{x i}} as @w{@samp{x init}} and the resolution command
14441 @w{@samp{x r}} as @w{@samp{x res}}.
14443 In the following, the syntax element @angles{line break} means a
14444 syntactical line break (@pxref{Separation}).
14447 @item xF @var{name}@angles{line break}
14448 The @samp{F} stands for @var{Filename}.
14450 Use @var{name} as the intended name for the current file in error
14451 reports. This is useful for remembering the original file name when
14452 @code{gtroff} uses an internal piping mechanism. The input file is
14453 not changed by this command. This command is a @code{gtroff} extension.
14455 @item xf @var{n} @var{s}@angles{line break}
14456 The @samp{f} stands for @var{font}.
14458 Mount font position@tie{}@var{n} (a non-negative integer) with font
14459 named@tie{}@var{s} (a text word). @xref{Font Positions}.
14461 @item xH @var{n}@angles{line break}
14462 The @samp{H} stands for @var{Height}.
14464 Set glyph height to@tie{}@var{n} (a positive integer in scaled
14465 points @samp{z}). @acronym{AT&T} @code{troff} uses the unit points
14466 (@samp{p}) instead. @xref{Output Language Compatibility}.
14468 @item xi@angles{line break}
14469 The @samp{i} stands for @var{init}.
14471 Initialize device. This is the third command of the prologue.
14473 @item xp@angles{line break}
14474 The @samp{p} stands for @var{pause}.
14476 Parsed but ignored. The original @acronym{UNIX} troff manual writes
14479 pause device, can be restarted
14482 @item xr @var{n} @var{h} @var{v}@angles{line break}
14483 The @samp{r} stands for @var{resolution}.
14485 Resolution is@tie{}@var{n}, while @var{h} is the minimal horizontal
14486 motion, and @var{v} the minimal vertical motion possible with this
14487 device; all arguments are positive integers in basic units @samp{u}
14488 per inch. This is the second command of the prologue.
14490 @item xS @var{n}@angles{line break}
14491 The @samp{S} stands for @var{Slant}.
14493 Set slant to@tie{}@var{n} (an integer in basic units @samp{u}).
14495 @item xs@angles{line break}
14496 The @samp{s} stands for @var{stop}.
14498 Terminates the processing of the current file; issued as the last
14499 command of any intermediate troff output.
14501 @item xt@angles{line break}
14502 The @samp{t} stands for @var{trailer}.
14504 Generate trailer information, if any. In @var{gtroff}, this is
14505 actually just ignored.
14507 @item xT @var{xxx}@angles{line break}
14508 The @samp{T} stands for @var{Typesetter}.
14510 Set name of device to word @var{xxx}, a sequence of characters ended
14511 by the next white space character. The possible device names coincide
14512 with those from the @code{groff} @option{-T} option. This is the first
14513 command of the prologue.
14515 @item xu @var{n}@angles{line break}
14516 The @samp{u} stands for @var{underline}.
14518 Configure underlining of spaces. If @var{n} is@tie{}1, start
14519 underlining of spaces; if @var{n} is@tie{}0, stop underlining of spaces.
14520 This is needed for the @code{cu} request in nroff mode and is ignored
14521 otherwise. This command is a @code{gtroff} extension.
14523 @item xX @var{anything}@angles{line break}
14524 The @samp{x} stands for @var{X-escape}.
14526 Send string @var{anything} uninterpreted to the device. If the line
14527 following this command starts with a @samp{+} character this line is
14528 interpreted as a continuation line in the following sense. The
14529 @samp{+} is ignored, but a newline character is sent instead to the
14530 device, the rest of the line is sent uninterpreted. The same applies
14531 to all following lines until the first character of a line is not a
14532 @samp{+} character. This command is generated by the @code{gtroff}
14533 escape sequence @code{\X}. The line-continuing feature is a
14534 @code{gtroff} extension.
14538 @node Obsolete Command, , Device Control Commands, Command Reference
14539 @subsubsection Obsolete Command
14540 In @acronym{AT&T} @code{troff} output, the writing of a single
14541 glyph is mostly done by a very strange command that combines a
14542 horizontal move and a single character giving the glyph name. It
14543 doesn't have a command code, but is represented by a 3-character
14544 argument consisting of exactly 2@tie{}digits and a character.
14547 @item @var{dd}@var{g}
14548 Move right @var{dd} (exactly two decimal digits) basic units @samp{u},
14549 then print glyph@tie{}@var{g} (represented as a single character).
14551 In @code{gtroff}, arbitrary syntactical space around and within this
14552 command is allowed to be added. Only when a preceding command on the
14553 same line ends with an argument of variable length a separating space
14554 is obligatory. In @acronym{AT&T} @code{troff}, large clusters of these
14555 and other commands are used, mostly without spaces; this made such output
14560 For modern high-resolution devices, this command does not make sense
14561 because the width of the glyphs can become much larger than two
14562 decimal digits. In @code{gtroff}, this is only used for the devices
14563 @code{X75}, @code{X75-12}, @code{X100}, and @code{X100-12}. For other
14564 devices, the commands @samp{t} and @samp{u} provide a better
14567 @c ---------------------------------------------------------------------
14569 @node Intermediate Output Examples, Output Language Compatibility, Command Reference, gtroff Output
14570 @subsection Intermediate Output Examples
14572 This section presents the intermediate output generated from the same
14573 input for three different devices. The input is the sentence
14574 @samp{hell world} fed into @code{gtroff} on the command line.
14577 @item High-resolution device @code{ps}
14579 This is the standard output of @code{gtroff} if no @option{-T} option
14584 shell> echo "hell world" | groff -Z -T ps
14610 This output can be fed into @code{grops} to get its representation as
14613 @item Low-resolution device @code{latin1}
14615 This is similar to the high-resolution device except that the
14616 positioning is done at a minor scale. Some comments (lines starting
14617 with @samp{#}) were added for clarification; they were not generated
14622 shell> echo "hell world" | groff -Z -T latin1
14635 # initial positioning on the page
14638 # write text `hell'
14640 # inform about space, and issue a horizontal jump
14642 # write text `world'
14644 # announce line break, but do nothing because ...
14647 # ... the end of the document has been reached
14655 This output can be fed into @code{grotty} to get a formatted text
14658 @item @acronym{AT&T} @code{troff} output
14659 Since a computer monitor has a very low resolution compared to modern
14660 printers the intermediate output for the X@tie{}Window devices can use
14661 the jump-and-write command with its 2-digit displacements.
14665 shell> echo "hell world" | groff -Z -T X100
14677 # write text with jump-and-write commands
14678 ch07e07l03lw06w11o07r05l03dh7
14688 This output can be fed into @code{xditview} or @code{gxditview}
14689 for displaying in@tie{}X.
14691 Due to the obsolete jump-and-write command, the text clusters in the
14692 @acronym{AT&T} @code{troff} output are almost unreadable.
14696 @c ---------------------------------------------------------------------
14698 @node Output Language Compatibility, , Intermediate Output Examples, gtroff Output
14699 @subsection Output Language Compatibility
14701 The intermediate output language of @acronym{AT&T} @code{troff}
14702 was first documented in the @acronym{UNIX} troff manual, with later
14703 additions documented in @cite{A Typesetter-indenpendent TROFF},
14704 written by Brian Kernighan.
14706 The @code{gtroff} intermediate output format is compatible with this
14707 specification except for the following features.
14711 The classical quasi device independence is not yet implemented.
14714 The old hardware was very different from what we use today. So the
14715 @code{groff} devices are also fundamentally different from the ones in
14716 @acronym{AT&T} @code{troff}. For example, the @acronym{AT&T}
14717 PostScript device is called @code{post} and has a resolution of only
14718 720 units per inch, suitable for printers 20 years ago, while
14719 @code{groff}'s @code{ps} device has a resolution of
14720 72000 units per inch. Maybe, by implementing some rescaling
14721 mechanism similar to the classical quasi device independence,
14722 @code{groff} could emulate @acronym{AT&T}'s @code{post} device.
14725 The B-spline command @samp{D~} is correctly handled by the
14726 intermediate output parser, but the drawing routines aren't
14727 implemented in some of the postprocessor programs.
14730 The argument of the commands @samp{s} and @w{@samp{x H}} has the
14731 implicit unit scaled point @samp{z} in @code{gtroff}, while
14732 @acronym{AT&T} @code{troff} has point (@samp{p}). This isn't an
14733 incompatibility but a compatible extension, for both units coincide
14734 for all devices without a @code{sizescale} parameter in the @file{DESC}
14735 file, including all postprocessors from @acronym{AT&T} and
14736 @code{groff}'s text devices. The few @code{groff} devices with
14737 a @code{sizescale} parameter either do not exist for @acronym{AT&T}
14738 @code{troff}, have a different name, or seem to have a different
14739 resolution. So conflicts are very unlikely.
14742 The position changing after the commands @samp{Dp}, @samp{DP}, and
14743 @samp{Dt} is illogical, but as old versions of @code{gtroff} used this
14744 feature it is kept for compatibility reasons.
14747 Temporarily, there existed some confusion on the positioning after the
14748 @samp{D} commands that are groff extensions. This has been clarified
14749 by establishing the classical rule for all @code{groff} drawing commands:
14753 The position after a graphic object has been drawn is at its end;
14754 for circles and ellipses, the `end' is at the right side.
14757 From this, the positionings specified for the drawing commands above
14758 follow quite naturally.
14765 @c =====================================================================
14767 @node Font Files, , gtroff Output, File formats
14768 @section Font Files
14770 @cindex files, font
14772 The @code{gtroff} font format is roughly a superset of the
14773 @code{ditroff} font format (as used in later versions of @acronym{AT&T}
14774 @code{troff} and its descendants). Unlike the @code{ditroff} font
14775 format, there is no associated binary format; all files are text
14776 files.@footnote{Plan@tie{}9 @code{troff} has also abandoned the binary
14777 format.} The font files for device @var{name} are stored in a directory
14778 @file{dev@var{name}}. There are two types of file: a device description
14779 file called @file{DESC} and for each font@tie{}@var{f} a font file
14780 called@tie{}@file{@var{f}}.
14783 * DESC File Format::
14784 * Font File Format::
14787 @c ---------------------------------------------------------------------
14789 @node DESC File Format, Font File Format, Font Files, Font Files
14790 @subsection @file{DESC} File Format
14791 @cindex @file{DESC} file, format
14792 @cindex font description file, format
14793 @cindex format of font description file
14794 @pindex DESC@r{ file format}
14796 The @file{DESC} file can contain the following types of line. Except
14797 for the @code{charset} keyword which must comes last (if at all), the
14798 order of the lines is not important.
14803 @cindex device resolution
14804 @cindex resolution, device
14805 There are @var{n}@tie{}machine units per inch.
14809 @cindex horizontal resolution
14810 @cindex resolution, horizontal
14811 The horizontal resolution is @var{n}@tie{}machine units. All horizontal
14812 quantities are rounded to be multiples of this value.
14816 @cindex vertical resolution
14817 @cindex resolution, vertical
14818 The vertical resolution is @var{n}@tie{}machine units. All vertical
14819 quantities are rounded to be multiples of this value.
14821 @item sizescale @var{n}
14823 The scale factor for point sizes. By default this has a value of@tie{}1.
14824 One scaled point is equal to one point/@var{n}. The arguments to the
14825 @code{unitwidth} and @code{sizes} commands are given in scaled points.
14826 @xref{Fractional Type Sizes}, for more information.
14828 @item unitwidth @var{n}
14830 Quantities in the font files are given in machine units for fonts whose
14831 point size is @var{n}@tie{}scaled points.
14833 @item prepro @var{program}
14835 Call @var{program} as a preprocessor. Currently, this keyword is used
14836 by @code{groff} with option @option{-Thtml} only.
14838 @item postpro @var{program}
14840 Call @var{program} as a postprocessor. For example, the line
14847 in the file @file{devdvi/DESC} makes @code{groff} call @code{grodvi}
14848 if option @option{-Tdvi} is given (and @option{-Z} isn't used).
14852 This means that the postprocessor can handle the @samp{t} and @samp{u}
14853 intermediate output commands.
14855 @item sizes @var{s1} @var{s2} @dots{} @var{sn} 0
14857 This means that the device has fonts at @var{s1}, @var{s2}, @dots{}
14858 @var{sn} scaled points. The list of sizes must be terminated by@tie{}0
14859 (this is digit zero). Each @var{si} can also be a range of sizes
14860 @var{m}-@var{n}. The list can extend over more than one line.
14862 @item styles @var{S1} @var{S2} @dots{} @var{Sm}
14864 The first @var{m}@tie{}font positions are associated with styles
14865 @var{S1} @dots{} @var{Sm}.
14867 @item fonts @var{n} @var{F1} @var{F2} @var{F3} @dots{} @var{Fn}
14869 Fonts @var{F1} @dots{} @var{Fn} are mounted in the font positions
14870 @var{m}+1, @dots{}, @var{m}+@var{n} where @var{m} is the number of
14871 styles. This command may extend over more than one line. A font name
14872 of@tie{}0 means no font is mounted on the corresponding font position.
14874 @item family @var{fam}
14876 The default font family is @var{fam}.
14878 @item use_charnames_in_special
14879 @kindex use_charnames_in_special
14880 This command indicates that @code{gtroff} should encode special
14881 characters inside special commands. Currently, this is only used
14882 by the @acronym{HTML} output device. @xref{Postprocessor Access}.
14884 @item papersize @var{string} @dots{}
14886 Select a paper size. Valid values for @var{string} are the ISO paper
14887 types @code{A0}-@code{A7}, @code{B0}-@code{B7}, @code{C0}-@code{C7},
14888 @code{D0}-@code{D7}, @code{DL}, and the US paper types @code{letter},
14889 @code{legal}, @code{tabloid}, @code{ledger}, @code{statement},
14890 @code{executive}, @code{com10}, and @code{monarch}. Case is not significant
14891 for @var{string} if it holds predefined paper types. Alternatively,
14892 @var{string} can be a file name (e.g.@: @file{/etc/papersize}); if the file
14893 can be opened, @code{groff} reads the first line and tests for the above
14894 paper sizes. Finally, @var{string} can be a custom paper size in the format
14895 @code{@var{length},@var{width}} (no spaces before and after the comma).
14896 Both @var{length} and @var{width} must have a unit appended; valid values
14897 are @samp{i} for inches, @samp{C} for centimeters, @samp{p} for points, and
14898 @samp{P} for picas. Example: @code{12c,235p}. An argument which starts
14899 with a digit is always treated as a custom paper format. @code{papersize}
14900 sets both the vertical and horizontal dimension of the output medium.
14902 More than one argument can be specified; @code{groff} scans from left to
14903 right and uses the first valid paper specification.
14905 @item pass_filenames
14906 @kindex pass_filenames
14907 Tell @code{gtroff} to emit the name of the source file currently
14908 being processed. This is achieved by the intermediate output command
14909 @samp{F}. Currently, this is only used by the @acronym{HTML} output
14912 @item print @var{program}
14914 Use @var{program} as a spooler program for printing. If omitted,
14915 the @option{-l} and @option{-L} options of @code{groff} are ignored.
14919 This line and everything following in the file are ignored. It is
14920 allowed for the sake of backwards compatibility.
14923 The @code{res}, @code{unitwidth}, @code{fonts}, and @code{sizes} lines
14924 are mandatory. Other commands are ignored by @code{gtroff} but may be
14925 used by postprocessors to store arbitrary information about the device
14926 in the @file{DESC} file.
14930 @kindex biggestfont
14931 Here a list of obsolete keywords which are recognized by @code{groff}
14932 but completely ignored: @code{spare1}, @code{spare2},
14933 @code{biggestfont}.
14935 @c ---------------------------------------------------------------------
14937 @node Font File Format, , DESC File Format, Font Files
14938 @subsection Font File Format
14939 @cindex font file, format
14940 @cindex font description file, format
14941 @cindex format of font files
14942 @cindex format of font description files
14944 A @dfn{font file}, also (and probably better) called a @dfn{font
14945 description file}, has two sections. The first section is a sequence
14946 of lines each containing a sequence of blank delimited words; the first
14947 word in the line is a key, and subsequent words give a value for that
14953 The name of the font is@tie{}@var{f}.
14955 @item spacewidth @var{n}
14957 The normal width of a space is@tie{}@var{n}.
14959 @item slant @var{n}
14961 The glyphs of the font have a slant of @var{n}@tie{}degrees.
14962 (Positive means forward.)
14964 @item ligatures @var{lig1} @var{lig2} @dots{} @var{lign} [0]
14966 Glyphs @var{lig1}, @var{lig2}, @dots{}, @var{lign} are ligatures;
14967 possible ligatures are @samp{ff}, @samp{fi}, @samp{fl}, @samp{ffi} and
14968 @samp{ffl}. For backwards compatibility, the list of ligatures may be
14969 terminated with a@tie{}0. The list of ligatures may not extend over more
14973 @cindex special fonts
14975 The font is @dfn{special}; this means that when a glyph is requested
14976 that is not present in the current font, it is searched for in any
14977 special fonts that are mounted.
14980 Other commands are ignored by @code{gtroff} but may be used by
14981 postprocessors to store arbitrary information about the font in the font
14984 @cindex comments in font files
14985 @cindex font files, comments
14987 The first section can contain comments which start with the @samp{#}
14988 character and extend to the end of a line.
14990 The second section contains one or two subsections. It must contain a
14991 @code{charset} subsection and it may also contain a @code{kernpairs}
14992 subsection. These subsections can appear in any order. Each
14993 subsection starts with a word on a line by itself.
14996 The word @code{charset} starts the character set
14997 subsection.@footnote{This keyword is misnamed since it starts a list
14998 of ordered glyphs, not characters.} The @code{charset} line is
14999 followed by a sequence of lines. Each line gives information for one
15000 glyph. A line comprises a number of fields separated by blanks or
15001 tabs. The format is
15004 @var{name} @var{metrics} @var{type} @var{code}
15005 [@var{entity-name}] [@code{--} @var{comment}]
15008 @cindex 8-bit input
15009 @cindex input, 8-bit
15010 @cindex accessing unnamed glyphs with @code{\N}
15011 @cindex unnamed glyphs, accessing with @code{\N}
15012 @cindex characters, unnamed, accessing with @code{\N}
15013 @cindex glyphs, unnamed, accessing with @code{\N}
15016 @var{name} identifies the glyph name@footnote{The distinction between
15017 input, characters, and output, glyphs, is not clearly separated in the
15018 terminology of @code{groff}; for example, the @code{char} request
15019 should be called @code{glyph} since it defines an output entity.}:
15020 If @var{name} is a single character@tie{}@var{c} then it corresponds
15021 to the @code{gtroff} input character@tie{}@var{c}; if it is of the form
15022 @samp{\@var{c}} where @var{c} is a single character, then it
15023 corresponds to the special character @code{\[@var{c}]}; otherwise it
15024 corresponds to the special character @samp{\[@var{name}]}. If it
15025 is exactly two characters @var{xx} it can be entered as
15026 @samp{\(@var{xx}}. Note that single-letter special characters can't
15027 be accessed as @samp{\@var{c}}; the only exception is @samp{\-} which
15028 is identical to @code{\[-]}.
15030 @code{gtroff} supports 8-bit input characters; however some utilities
15031 have difficulties with eight-bit characters. For this reason, there is
15032 a convention that the entity name @samp{char@var{n}} is equivalent to
15033 the single input character whose code is@tie{}@var{n}. For example,
15034 @samp{char163} would be equivalent to the character with code@tie{}163
15035 which is the pounds sterling sign in the ISO@tie{}@w{Latin-1} character set.
15036 You shouldn't use @samp{char@var{n}} entities in font description files
15037 since they are related to input, not output. Otherwise, you get
15038 hard-coded connections between input and output encoding which
15039 prevents use of different (input) character sets.
15041 The name @samp{---} is special and indicates that the glyph is
15042 unnamed; such glyphs can only be used by means of the @code{\N}
15043 escape sequence in @code{gtroff}.
15045 The @var{type} field gives the glyph type:
15049 the glyph has a descender, for example, @samp{p};
15052 the glyph has an ascender, for example, @samp{b};
15055 the glyph has both an ascender and a descender, for example, @samp{(}.
15058 The @var{code} field gives the code which the postprocessor uses to
15059 print the glyph. The glyph can also be input to @code{gtroff}
15060 using this code by means of the @code{\N} escape sequence. @var{code}
15061 can be any integer. If it starts with @samp{0} it is interpreted as
15062 octal; if it starts with @samp{0x} or @samp{0X} it is interpreted as
15063 hexadecimal. Note, however, that the @code{\N} escape sequence only
15064 accepts a decimal integer.
15066 The @var{entity-name} field gives an @acronym{ASCII} string
15067 identifying the glyph which the postprocessor uses to print the
15068 @code{gtroff} glyph @var{name}. This field is optional and has been
15069 introduced so that the @acronym{HTML} device driver can encode its
15070 character set. For example, the glyph @samp{\[Po]} is
15071 represented as @samp{£} in @acronym{HTML} 4.0.
15073 Anything on the line after the @var{entity-name} field resp.@: after
15074 @samp{--} will be ignored.
15076 The @var{metrics} field has the form:
15080 @var{width}[@code{,}@var{height}[@code{,}@var{depth}[@code{,}@var{italic-correction}
15081 [@code{,}@var{left-italic-correction}[@code{,}@var{subscript-correction}]]]]]
15086 There must not be any spaces between these subfields (it has been split
15087 here into two lines for better legibility only). Missing subfields are
15088 assumed to be@tie{}0. The subfields are all decimal integers. Since
15089 there is no associated binary format, these values are not required to
15090 fit into a variable of type @samp{char} as they are in @code{ditroff}.
15091 The @var{width} subfield gives the width of the glyph. The @var{height}
15092 subfield gives the height of the glyph (upwards is positive); if a
15093 glyph does not extend above the baseline, it should be given a zero
15094 height, rather than a negative height. The @var{depth} subfield gives
15095 the depth of the glyph, that is, the distance from the baseline to the
15096 lowest point below the baseline to which the glyph extends (downwards is
15097 positive); if a glyph does not extend below the baseline, it should be
15098 given a zero depth, rather than a negative depth. The
15099 @var{italic-correction} subfield gives the amount of space that should
15100 be added after the glyph when it is immediately to be followed by a
15101 glyph from a roman font. The @var{left-italic-correction} subfield
15102 gives the amount of space that should be added before the glyph when it
15103 is immediately to be preceded by a glyph from a roman font. The
15104 @var{subscript-correction} gives the amount of space that should be
15105 added after a glyph before adding a subscript. This should be less
15106 than the italic correction.
15108 A line in the @code{charset} section can also have the format
15115 This indicates that @var{name} is just another name for the glyph
15116 mentioned in the preceding line.
15119 The word @code{kernpairs} starts the kernpairs section. This contains a
15120 sequence of lines of the form:
15123 @var{c1} @var{c2} @var{n}
15127 This means that when glyph @var{c1} appears next to glyph @var{c2}
15128 the space between them should be increased by@tie{}@var{n}. Most
15129 entries in the kernpairs section have a negative value for@tie{}@var{n}.
15133 @c =====================================================================
15134 @c =====================================================================
15136 @node Installation, Copying This Manual, File formats, Top
15137 @chapter Installation
15138 @cindex installation
15144 @c =====================================================================
15145 @c =====================================================================
15147 @node Copying This Manual, Request Index, Installation, Top
15148 @appendix Copying This Manual
15151 * GNU Free Documentation License:: License for copying this manual.
15158 @c =====================================================================
15159 @c =====================================================================
15161 @node Request Index, Escape Index, Copying This Manual, Top
15162 @appendix Request Index
15164 Requests appear without the leading control character (normally either
15165 @samp{.} or @samp{'}).
15171 @c =====================================================================
15172 @c =====================================================================
15174 @node Escape Index, Operator Index, Request Index, Top
15175 @appendix Escape Index
15177 Any escape sequence @code{\@var{X}} with @var{X} not in the list below
15178 emits a warning, printing glyph @var{X}.
15184 @c =====================================================================
15185 @c =====================================================================
15187 @node Operator Index, Register Index, Escape Index, Top
15188 @appendix Operator Index
15194 @c =====================================================================
15195 @c =====================================================================
15197 @node Register Index, Macro Index, Operator Index, Top
15198 @appendix Register Index
15200 The macro package or program a specific register belongs to is appended in
15203 A register name@tie{}@code{x} consisting of exactly one character can be
15204 accessed as @samp{\nx}. A register name @code{xx} consisting of exactly
15205 two characters can be accessed as @samp{\n(xx}. Register names @code{xxx}
15206 of any length can be accessed as @samp{\n[xxx]}.
15212 @c =====================================================================
15213 @c =====================================================================
15215 @node Macro Index, String Index, Register Index, Top
15216 @appendix Macro Index
15218 The macro package a specific macro belongs to is appended in brackets.
15219 They appear without the leading control character (normally @samp{.}).
15225 @c =====================================================================
15226 @c =====================================================================
15228 @node String Index, Glyph Name Index, Macro Index, Top
15229 @appendix String Index
15231 The macro package or program a specific string belongs to is appended in
15234 A string name@tie{}@code{x} consisting of exactly one character can be
15235 accessed as @samp{\*x}. A string name @code{xx} consisting of exactly
15236 two characters can be accessed as @samp{\*(xx}. String names @code{xxx}
15237 of any length can be accessed as @samp{\*[xxx]}.
15244 @c =====================================================================
15245 @c =====================================================================
15247 @node Glyph Name Index, Font File Keyword Index, String Index, Top
15248 @appendix Glyph Name Index
15250 A glyph name @code{xx} consisting of exactly two characters can be
15251 accessed as @samp{\(xx}. Glyph names @code{xxx} of any length can be
15252 accessed as @samp{\[xxx]}.
15258 @c =====================================================================
15259 @c =====================================================================
15261 @node Font File Keyword Index, Program and File Index, Glyph Name Index, Top
15262 @appendix Font File Keyword Index
15268 @c =====================================================================
15269 @c =====================================================================
15271 @node Program and File Index, Concept Index, Font File Keyword Index, Top
15272 @appendix Program and File Index
15278 @c =====================================================================
15279 @c =====================================================================
15281 @node Concept Index, , Program and File Index, Top
15282 @appendix Concept Index