1 \input texinfo @c -*-texinfo-*-
4 @c Please convert this manual with `texi2dvi -e groff.texinfo' due to a bug
5 @c in texinfo regarding expansion of user-defined macros.
7 @c You need texinfo 4.2 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.18.
26 Copyright @copyright{} 1994-2000, 2001, 2002 Free Software Foundation, Inc.
29 Permission is granted to copy, distribute and/or modify this document
30 under the terms of the GNU Free Documentation License, Version 1.1 or
31 any later version published by the Free Software Foundation; with no
32 Invariant Sections, with the Front-Cover texts being `A GNU Manual,''
33 and with the Back-Cover Texts as in (a) below. A copy of the
34 license is included in the section entitled `GNU Free Documentation
37 (a) The FSF's Back-Cover Text is: `You have freedom to copy and modify
38 this GNU Manual, like GNU software. Copies published by the Free
39 Software Foundation raise funds for GNU development.''
44 @c We use the following indices:
50 @c kindex: commands in font files
51 @c pindex: programs and files
52 @c tindex: environment variables
57 @c tindex and cindex are merged.
67 @c to avoid uppercasing in @deffn while converting to info, we define
70 @c due to a (not officially documented) `feature' in makeinfo 4.0,
71 @c macros are not expanded in @deffn (but the macro definition is
72 @c properly removed), so we have to define @Var{} directly in TeX also
82 @c To assure correct HTML translation, some ugly hacks are necessary.
83 @c While processing a @def... request, the HTML translator looks at the
84 @c next line to decide whether it should start indentation or not. If
85 @c it is something starting with @def... (e.g. @deffnx), it doesn't.
86 @c So we must assure during macro expansion that a @def... is seen.
88 @c The following macros have to be used:
107 @c The definition block must end with
111 @c The above is valid for texinfo 4.0f.
114 @c a dummy macro to assure the `@def...'
120 @c definition of requests
122 @macro Defreq{name, arg}
123 @deffn Request @t{.\name\} \arg\
127 @macro DefreqList{name, arg}
128 @deffn Request @t{.\name\} \arg\
133 @macro DefreqItem{name, arg}
134 @deffnx Request @t{.\name\} \arg\
139 @macro DefreqListEnd{name, arg}
140 @deffnx Request @t{.\name\} \arg\
149 @c definition of escapes
151 @macro Defesc{name, delimI, arg, delimII}
152 @deffn Escape @t{\name\\delimI\}@var{\arg\}@t{\delimII\}
156 @macro DefescList{name, delimI, arg, delimII}
157 @deffn Escape @t{\name\\delimI\}@var{\arg\}@t{\delimII\}
162 @macro DefescItem{name, delimI, arg, delimII}
163 @deffnx Escape @t{\name\\delimI\}@var{\arg\}@t{\delimII\}
168 @macro DefescListEnd{name, delimI, arg, delimII}
169 @deffnx Escape @t{\name\\delimI\}@var{\arg\}@t{\delimII\}
178 @c definition of registers
181 @deffn Register @t{\\n[\name\]}
185 @macro DefregList{name}
186 @deffn Register @t{\\n[\name\]}
191 @macro DefregItem{name}
192 @deffnx Register @t{\\n[\name\]}
197 @macro DefregListEnd{name}
198 @deffnx Register @t{\\n[\name\]}
207 @c definition of registers specific to macro packages, preprocessors, etc.
209 @macro Defmpreg{name, package}
210 @deffn Register @t{\\n[\name\]}
211 @vindex \name\ @r{[}\package\@r{]}
214 @macro DefmpregList{name, package}
215 @deffn Register @t{\\n[\name\]}
217 @vindex \name\ @r{[}\package\@r{]}
220 @macro DefmpregItem{name, package}
221 @deffnx Register @t{\\n[\name\]}
223 @vindex \name\ @r{[}\package\@r{]}
226 @macro DefmpregListEnd{name, package}
227 @deffnx Register @t{\\n[\name\]}
228 @vindex \name\ @r{[}\package\@r{]}
236 @c definition of macros
238 @macro Defmac{name, arg, package}
239 @defmac @t{.\name\} \arg\
240 @maindex \name\ @r{[}\package\@r{]}
243 @macro DefmacList{name, arg, package}
244 @defmac @t{.\name\} \arg\
246 @maindex \name\ @r{[}\package\@r{]}
249 @macro DefmacItem{name, arg, package}
250 @defmacx @t{.\name\} \arg\
252 @maindex \name\ @r{[}\package\@r{]}
255 @macro DefmacListEnd{name, arg, package}
256 @defmacx @t{.\name\} \arg\
257 @maindex \name\ @r{[}\package\@r{]}
265 @c definition of strings
267 @macro Defstr{name, package}
268 @deffn String @t{\\*[\name\]}
269 @stindex \name\ @r{[}\package\@r{]}
272 @macro DefstrList{name, package}
273 @deffn String @t{\\*[\name\]}
275 @stindex \name\ @r{[}\package\@r{]}
278 @macro DefstrItem{name, package}
279 @deffnx String @t{\\*[\name\]}
281 @stindex \name\ @r{[}\package\@r{]}
284 @macro DefstrListEnd{name, package}
285 @deffnx String @t{\\*[\name\]}
286 @stindex \name\ @r{[}\package\@r{]}
310 \gdef\angles#1{\angleleft{}\r{#1}\angleright{}}
329 @c due to a bug in texinfo 4.2, the spacing of `<' is bad in @item
340 @c We need special parentheses and brackets:
342 @c . Real parentheses in @deffn produce an error while compiling with
344 @c . Real brackets use the wrong font in @deffn, overriding @t{}.
346 @c Since macros aren't expanded in @deffn during -E, the following
347 @c definitions are for non-TeX only.
349 @c This is true for texinfo 4.0.
366 \gdef\gobblefirst#1#2{#2}
367 \gdef\putwordAppendix{\gobblefirst}
371 @c Note: We say `Roman numerals' but `roman font'.
374 @dircategory Miscellaneous
376 * Groff: (groff). The GNU troff document formatting system.
382 @subtitle The GNU implementation of @code{troff}
383 @subtitle Edition 1.18
384 @subtitle Spring 2002
385 @author by Trent A.@w{ }Fisher
386 @author and Werner Lemberg (@email{bug-groff@@gnu.org})
389 @vskip 0pt plus 1filll
397 @node Top, Introduction, (dir), (dir)
404 @node Top, Introduction, (dir), (dir)
413 * Tutorial for Macro Users::
420 * Copying This Manual::
428 * Font File Keyword Index::
429 * Program and File Index::
435 @c =====================================================================
436 @c =====================================================================
438 @node Introduction, Invoking groff, Top, Top
439 @chapter Introduction
442 GNU @code{troff} (or @code{groff}) is a system for typesetting
443 documents. @code{troff} is very flexible and has been in existence (and
444 use) for about 3@w{ }decades. It is quite widespread and firmly
445 entrenched in the @acronym{UNIX} community.
450 * groff Capabilities::
451 * Macro Package Intro::
452 * Preprocessor Intro::
453 * Output device intro::
458 @c =====================================================================
460 @node What Is groff?, History, Introduction, Introduction
461 @section What Is @code{groff}?
462 @cindex what is @code{groff}?
463 @cindex @code{groff} -- what is it?
465 @code{groff} belongs to an older generation of document preparation
466 systems, which operate more like compilers than the more recent
467 interactive @acronym{WYSIWYG}@footnote{What You See Is What You Get}
468 systems. @code{groff} and its contemporary counterpart, @TeX{}, both
469 work using a @dfn{batch} paradigm: The input (or @dfn{source}) files are
470 normal text files with embedded formatting commands. These files can
471 then be processed by @code{groff} to produce a typeset document on a
474 Likewise, @code{groff} should not be confused with a @dfn{word
475 processor}, since that term connotes an integrated system that includes
476 an editor and a text formatter. Also, many word processors follow the
477 @acronym{WYSIWYG} paradigm discussed earlier.
479 Although @acronym{WYSIWYG} systems may be easier to use, they have a
480 number of disadvantages compared to @code{troff}:
484 They must be used on a graphics display to work on a document.
487 Most of the @acronym{WYSIWYG} systems are either non-free or are not
491 @code{troff} is firmly entrenched in all @acronym{UNIX} systems.
494 It is difficult to have a wide range of capabilities available within
495 the confines of a GUI/window system.
498 It is more difficult to make global changes to a document.
502 ``GUIs normally make it simple to accomplish simple actions and
503 impossible to accomplish complex actions.'' --Doug Gwyn (22/Jun/91 in
504 @code{comp.unix.wizards})
508 @c =====================================================================
510 @node History, groff Capabilities, What Is groff?, Introduction
514 @cindex @code{runoff}, the program
515 @cindex @code{rf}, the program
516 @code{troff} can trace its origins back to a formatting program called
517 @code{runoff}, written by J.@w{ }E.@w{ }Saltzer, which ran on MIT's CTSS
518 operating system in the mid-sixties. This name came from the common
519 phrase of the time ``I'll run off a document.'' Bob Morris ported it to
520 the 635 architecture and called the program @code{roff} (an abbreviation
521 of @code{runoff}). It was rewritten as @code{rf} for the @w{PDP-7}
522 (before having @acronym{UNIX}), and at the same time (1969), Doug
523 McIllroy rewrote an extended and simplified version of @code{roff} in
524 the @acronym{BCPL} programming language.
526 @cindex @code{roff}, the program
527 The first version of @acronym{UNIX} was developed on a @w{PDP-7} which
528 was sitting around Bell Labs. In 1971 the developers wanted to get a
529 @w{PDP-11} for further work on the operating system. In order to
530 justify the cost for this system, they proposed that they would
531 implement a document formatting system for the @acronym{AT&T} patents
532 division. This first formatting program was a reimplementation of
533 McIllroy's @code{roff}, written by J.@w{ }F.@w{ }Ossanna.
535 @cindex @code{nroff}, the program
536 When they needed a more flexible language, a new version of @code{roff}
537 called @code{nroff} (``Newer @code{roff}'') was written. It had a much
538 more complicated syntax, but provided the basis for all future versions.
539 When they got a Graphic Systems CAT Phototypesetter, Ossanna wrote a
540 version of @code{nroff} that would drive it. It was dubbed
541 @code{troff}, for ``typesetter @code{roff}'', although many people have
542 speculated that it actually means ``Times @code{roff}'' because of the
543 use of the Times font family in @code{troff} by default. As such, the
544 name @code{troff} is pronounced `@w{t-roff}' rather than `trough'.
546 With @code{troff} came @code{nroff} (they were actually the same program
547 except for some @samp{#ifdef}s), which was for producing output for line
548 printers and character terminals. It understood everything @code{troff}
549 did, and ignored the commands which were not applicable (e.g.@: font
552 Since there are several things which cannot be done easily in
553 @code{troff}, work on several preprocessors began. These programs would
554 transform certain parts of a document into @code{troff}, which made a
555 very natural use of pipes in @acronym{UNIX}.
557 The @code{eqn} preprocessor allowed mathematical formul@ae{} to be
558 specified in a much simpler and more intuitive manner. @code{tbl} is a
559 preprocessor for formatting tables. The @code{refer} preprocessor (and
560 the similar program, @code{bib}) processes citations in a document
561 according to a bibliographic database.
563 Unfortunately, Ossanna's @code{troff} was written in @w{PDP-11} assembly
564 language and produced output specifically for the CAT phototypesetter.
565 He rewrote it in C, although it was now 7000@w{ }lines of uncommented
566 code and still dependent on the CAT. As the CAT became less common, and
567 was no longer supported by the manufacturer, the need to make it support
568 other devices became a priority. However, before this could be done,
569 Ossanna was killed in a car accident.
572 @cindex @code{ditroff}, the program
573 So, Brian Kernighan took on the task of rewriting @code{troff}. The
574 newly rewritten version produced device independent code which was
575 very easy for postprocessors to read and translate to the appropriate
576 printer codes. Also, this new version of @code{troff} (called
577 @code{ditroff} for ``device independent @code{troff}'') had several
578 extensions, which included drawing functions.
580 Due to the additional abilities of the new version of @code{troff},
581 several new preprocessors appeared. The @code{pic} preprocessor
582 provides a wide range of drawing functions. Likewise the @code{ideal}
583 preprocessor did the same, although via a much different paradigm. The
584 @code{grap} preprocessor took specifications for graphs, but, unlike
585 other preprocessors, produced @code{pic} code.
587 James Clark began work on a GNU implementation of @code{ditroff} in
588 early@w{ }1989. The first version, @code{groff}@w{ }0.3.1, was released
589 June@w{ }1990. @code{groff} included:
593 A replacement for @code{ditroff} with many extensions.
596 The @code{soelim}, @code{pic}, @code{tbl}, and @code{eqn} preprocessors.
599 Postprocessors for character devices, @sc{PostScript}, @TeX{} DVI, and
600 X@w{ }Windows. GNU @code{troff} also eliminated the need for a
601 separate @code{nroff} program with a postprocessor which would produce
602 @acronym{ASCII} output.
605 A version of the @file{me} macros and an implementation of the
609 Also, a front-end was included which could construct the, sometimes
610 painfully long, pipelines required for all the post- and preprocessors.
612 Development of GNU @code{troff} progressed rapidly, and saw the
613 additions of a replacement for @code{refer}, an implementation of the
614 @file{ms} and @file{mm} macros, and a program to deduce how to format a
615 document (@code{grog}).
617 It was declared a stable (i.e.@: non-beta) package with the release of
618 version@w{ }1.04 around November@w{ }1991.
620 Beginning in@w{ }1999, @code{groff} has new maintainers (the package was
621 an orphan for a few years). As a result, new features and programs like
622 @code{grn}, a preprocessor for gremlin images, and an output device to
623 produce @acronym{HTML} output have been added.
626 @c =====================================================================
628 @node groff Capabilities, Macro Package Intro, History, Introduction
629 @section @code{groff} Capabilities
630 @cindex @code{groff} capabilities
631 @cindex capabilities of @code{groff}
633 So what exactly is @code{groff} capable of doing? @code{groff} provides
634 a wide range of low-level text formatting operations. Using these, it
635 is possible to perform a wide range of formatting tasks, such as
636 footnotes, table of contents, multiple columns, etc. Here's a list of
637 the most important operations supported by @code{groff}:
641 text filling, adjusting, and centering
650 font and glyph size control
653 vertical spacing (e.g.@: double-spacing)
656 line length and indenting
659 macros, strings, diversions, and traps
665 tabs, leaders, and fields
668 input and output conventions and character translation
671 overstrike, bracket, line drawing, and zero-width functions
674 local horizontal and vertical motions and the width function
680 output line numbering
683 conditional acceptance of input
686 environment switching
689 insertions from the standard input
692 input/output file switching
695 output and error messages
699 @c =====================================================================
701 @node Macro Package Intro, Preprocessor Intro, groff Capabilities, Introduction
702 @section Macro Packages
703 @cindex macro packages
705 Since @code{groff} provides such low-level facilities, it can be quite
706 difficult to use by itself. However, @code{groff} provides a
707 @dfn{macro} facility to specify how certain routine operations (e.g.@w{
708 }starting paragraphs, printing headers and footers, etc.)@: should be
709 done. These macros can be collected together into a @dfn{macro
710 package}. There are a number of macro packages available; the most
711 common (and the ones described in this manual) are @file{man},
712 @file{mdoc}, @file{me}, @file{ms}, and @file{mm}.
715 @c =====================================================================
717 @node Preprocessor Intro, Output device intro, Macro Package Intro, Introduction
718 @section Preprocessors
719 @cindex preprocessors
721 Although @code{groff} provides most functions needed to format a
722 document, some operations would be unwieldy (e.g.@: to draw pictures).
723 Therefore, programs called @dfn{preprocessors} were written which
724 understand their own language and produce the necessary @code{groff}
725 operations. These preprocessors are able to differentiate their own
726 input from the rest of the document via markers.
728 To use a preprocessor, @acronym{UNIX} pipes are used to feed the output
729 from the preprocessor into @code{groff}. Any number of preprocessors
730 may be used on a given document; in this case, the preprocessors are
731 linked together into one pipeline. However, with @code{groff}, the user
732 does not need to construct the pipe, but only tell @code{groff} what
733 preprocessors to use.
735 @code{groff} currently has preprocessors for producing tables
736 (@code{tbl}), typesetting equations (@code{eqn}), drawing pictures
737 (@code{pic} and @code{grn}), and for processing bibliographies
738 (@code{refer}). An associated program which is useful when dealing with
739 preprocessors is @code{soelim}.
741 A free implementation of @code{grap}, a preprocessor for drawing graphs,
742 can be obtained as an extra package; @code{groff} can use @code{grap}
745 There are other preprocessors in existence, but, unfortunately, no free
746 implementations are available. Among them are preprocessors for drawing
747 mathematical pictures (@code{ideal}) and chemical structures
751 @c =====================================================================
753 @node Output device intro, Credits, Preprocessor Intro, Introduction
754 @section Output Devices
755 @cindex postprocessors
756 @cindex output devices
757 @cindex devices for output
759 @code{groff} actually produces device independent code which may be
760 fed into a postprocessor to produce output for a particular device.
761 Currently, @code{groff} has postprocessors for @sc{PostScript}
762 devices, character terminals, X@w{ }Windows (for previewing), @TeX{}
763 DVI format, HP LaserJet@w{ }4 and Canon LBP printers (which use
764 @acronym{CAPSL}), and @acronym{HTML}.
767 @c =====================================================================
769 @node Credits, , Output device intro, Introduction
773 Large portions of this manual were taken from existing documents, most
774 notably, the manual pages for the @code{groff} package by James Clark,
775 and Eric Allman's papers on the @file{me} macro package.
777 The section on the @file{man} macro package is partly based on Susan@w{
778 }G.@: Kleinmann's @file{groff_man} manual page written for the Debian
781 Larry Kollar contributed the section in the @file{ms} macro package.
785 @c =====================================================================
786 @c =====================================================================
788 @node Invoking groff, Tutorial for Macro Users, Introduction, Top
789 @chapter Invoking @code{groff}
790 @cindex invoking @code{groff}
791 @cindex @code{groff} invocation
793 This section focuses on how to invoke the @code{groff} front end. This
794 front end takes care of the details of constructing the pipeline among
795 the preprocessors, @code{gtroff} and the postprocessor.
797 It has become a tradition that GNU programs get the prefix @samp{g} to
798 distinguish it from its original counterparts provided by the host (see
799 @ref{Environment}, for more details). Thus, for example, @code{geqn} is
800 GNU @code{eqn}. On operating systems like GNU/Linux or the Hurd, which
801 don't contain proprietary versions of @code{troff}, and on
802 MS-DOS/MS-Windows, where @code{troff} and associated programs are not
803 available at all, this prefix is omitted since GNU @code{troff} is the
804 only used incarnation of @code{troff}. Exception: @samp{groff} is never
805 replaced by @samp{roff}.
807 In this document, we consequently say @samp{gtroff} when talking about
808 the GNU @code{troff} program. All other implementations of @code{troff}
809 are called @acronym{AT&T} @code{troff} which is the common origin of
810 all @code{troff} derivates (with more or less compatible changes).
811 Similarly, we say @samp{gpic}, @samp{geqn}, etc.
816 * Macro Directories::
818 * Invocation Examples::
822 @c =====================================================================
824 @node Groff Options, Environment, Invoking groff, Invoking groff
837 @code{groff} normally runs the @code{gtroff} program and a postprocessor
838 appropriate for the selected device. The default device is @samp{ps}
839 (but it can be changed when @code{groff} is configured and built). It
840 can optionally preprocess with any of @code{gpic}, @code{geqn},
841 @code{gtbl}, @code{ggrn}, @code{grap}, @code{grefer}, or @code{gsoelim}.
843 This section only documents options to the @code{groff} front end. Many
844 of the arguments to @code{groff} are passed on to @code{gtroff},
845 therefore those are also included. Arguments to pre- or postprocessors
846 can be found in @ref{Invoking gpic}, @ref{Invoking geqn}, @ref{Invoking
847 gtbl}, @ref{Invoking ggrn}, @ref{Invoking grefer}, @ref{Invoking
848 gsoelim}, @ref{Invoking grotty}, @ref{Invoking grops}, @ref{Invoking
849 grohtml}, @ref{Invoking grodvi}, @ref{Invoking grolj4}, @ref{Invoking
850 grolbp}, and @ref{Invoking gxditview}.
852 The command line format for @code{groff} is:
855 groff [ -abceghilpstvzCEGNRSUVXZ ] [ -F@var{dir} ] [ -m@var{name} ]
856 [ -T@var{def} ] [ -f@var{fam} ] [ -w@var{name} ] [ -W@var{name} ]
857 [ -M@var{dir} ] [ -d@var{cs} ] [ -r@var{cn} ] [ -n@var{num} ]
858 [ -o@var{list} ] [ -P@var{arg} ] [ -L@var{arg} ] [ -I@var{dir} ]
859 [ @var{files}@dots{} ]
862 The command line format for @code{gtroff} is as follows.
865 gtroff [ -abcivzCERU ] [ -w@var{name} ] [ -W@var{name} ] [ -d@var{cs} ]
866 [ -f@var{fam} ] [ -m@var{name} ] [ -n@var{num} ]
867 [ -o@var{list} ] [ -r@var{cn} ] [ -T@var{name} ]
868 [ -F@var{dir} ] [ -M@var{dir} ] [ @var{files}@dots{} ]
872 Obviously, many of the options to @code{groff} are actually passed on to
875 Options without an argument can be grouped behind a single@w{ }@option{-}.
876 A filename of@w{ }@file{-} denotes the standard input. It is possible to
877 have whitespace between an option and its parameter.
879 The @code{grog} command can be used to guess the correct @code{groff}
880 command to format a file.
882 Here's the description of the command-line options:
884 @cindex command-line options
887 Print a help message.
890 Preprocess with @code{geqn}.
893 Preprocess with @code{gtbl}.
896 Preprocess with @code{ggrn}.
899 Preprocess with @code{grap}.
902 Preprocess with @code{gpic}.
905 Preprocess with @code{gsoelim}.
908 Suppress color output.
911 Preprocess with @code{grefer}. No mechanism is provided for passing
912 arguments to @code{grefer} because most @code{grefer} options have
913 equivalent commands which can be included in the file. @xref{grefer},
918 Note that @code{gtroff} also accepts a @option{-R} option, which is not
919 accessible via @code{groff}. This option prevents the loading of the
920 @file{troffrc} and @file{troffrc-end} files.
923 Make programs run by @code{groff} print out their version number.
926 Print the pipeline on @code{stdout} instead of executing it.
929 Suppress output from @code{gtroff}. Only error messages are printed.
932 Do not postprocess the output of @code{gtroff}. Normally @code{groff}
933 automatically runs the appropriate postprocessor.
936 Pass @var{arg} to the postprocessor. Each argument should be passed
937 with a separate @option{-P} option. Note that @code{groff} does not
938 prepend @samp{-} to @var{arg} before passing it to the postprocessor.
941 Send the output to a spooler for printing. The command used for this is
942 specified by the @code{print} command in the device description file
943 (see @ref{Font Files}, for more info). If not present, @option{-l} is
947 Pass @var{arg} to the spooler. Each argument should be passed with a
948 separate @option{-L} option. Note that @code{groff} does not prepend
949 a @samp{-} to @var{arg} before passing it to the postprocessor.
950 If the @code{print} keyword in the device description file is missing,
951 @option{-L} is ignored.
954 Prepare output for device @var{dev}. The default device is @samp{ps},
955 unless changed when @code{groff} was configured and built. The
956 following are the output devices currently available:
960 For @sc{PostScript} printers and previewers.
963 For @TeX{} DVI format.
966 For a 75@dmn{dpi} X11 previewer.
969 For a 75@dmn{dpi} X11 previewer with a 12@dmn{pt} base font in the
973 For a 100@dmn{dpi} X11 previewer.
976 For a 100@dmn{dpi} X11 previewer with a 12@dmn{pt} base font in the
980 @cindex encoding, @acronym{ASCII}
981 @cindex @acronym{ASCII}, encoding
982 For typewriter-like devices using the (7-bit) @acronym{ASCII}
986 @cindex encoding, latin-1
987 @cindex latin-1, encoding
988 For typewriter-like devices that support the @w{Latin-1} (@w{ISO
989 8859-1}) character set.
992 @cindex encoding, utf-8
993 @cindex utf-8, encoding
994 For typewriter-like devices which use the Unicode (@w{ISO 10646})
995 character set with @w{UTF-8} encoding.
998 @cindex @acronym{EBCDIC} encoding
999 @cindex encoding, @acronym{EBCDIC}
1000 @cindex encoding, cp1047
1003 For typewriter-like devices which use the @acronym{EBCDIC} encoding IBM
1007 For HP LaserJet4-compatible (or other PCL5-compatible) printers.
1010 For Canon @acronym{CAPSL} printers (@w{LBP-4} and @w{LBP-8} series laser
1014 @pindex post-grohtml
1015 @cindex @code{grohtml}, the program
1017 To produce @acronym{HTML} output. Note that the @acronym{HTML} driver
1018 consists of two parts, a preprocessor (@code{pre-grohtml}) and a
1019 postprocessor (@code{post-grohtml}).
1022 @cindex output device name string register (@code{.T})
1023 @cindex output device usage number register (@code{.T})
1024 The predefined @code{gtroff} string register @code{.T} contains the
1025 current output device; the read-only number register @code{.T} is set
1026 to@w{ }1 if this option is used (which is always true if @code{groff} is
1027 used to call @code{gtroff}). @xref{Built-in Registers}.
1029 The postprocessor to be used for a device is specified by the
1030 @code{postpro} command in the device description file. (@xref{Font
1031 Files}, for more info.) This can be overridden with the @option{-X}
1035 Preview with @code{gxditview} instead of using the usual postprocessor.
1036 This is unlikely to produce good results except with @option{-Tps}.
1038 Note that this is not the same as using @option{-TX75} or
1039 @option{-TX100} to view a document with @code{gxditview}: The former
1040 uses the metrics of the specified device, whereas the latter uses
1041 X-specific fonts and metrics.
1044 Don't allow newlines with @code{eqn} delimiters. This is the same as
1045 the @option{-N} option in @code{geqn}.
1048 @cindex @code{open} request, and safer mode
1049 @cindex @code{opena} request, and safer mode
1050 @cindex @code{pso} request, and safer mode
1051 @cindex @code{sy} request, and safer mode
1052 @cindex @code{pi} request, and safer mode
1055 Safer mode. Pass the @option{-S} option to @code{gpic} and disable the
1056 @code{open}, @code{opena}, @code{pso}, @code{sy}, and @code{pi}
1057 requests. For security reasons, this is enabled by default.
1060 @cindex mode, unsafe
1062 Unsafe mode. This enables the @code{open}, @code{opena}, @code{pso},
1063 @code{sy}, and @code{pi} requests.
1066 @cindex @acronym{ASCII} approximation output register (@code{.A})
1067 Generate an @acronym{ASCII} approximation of the typeset output. The
1068 read-only register @code{.A} is then set to@w{ }1. @xref{Built-in
1069 Registers}. A typical example is
1072 groff -a -man -Tdvi troff.man | less
1076 which shows how lines are broken for the DVI device. Note that this
1077 option is rather useless today since graphic output devices are
1078 available virtually everywhere.
1081 Print a backtrace with each warning or error message. This backtrace
1082 should help track down the cause of the error. The line numbers given
1083 in the backtrace may not always be correct: @code{gtroff} can get
1084 confused by @code{as} or @code{am} requests while counting line numbers.
1087 Read the standard input after all the named input files have been
1091 Enable warning @var{name}. Available warnings are described in
1092 @ref{Debugging}. Multiple @option{-w} options are allowed.
1095 Inhibit warning @var{name}. Multiple @option{-W} options are allowed.
1098 Inhibit all error messages.
1101 Enable compatibility mode. @xref{Implementation Differences}, for the
1102 list of incompatibilities between @code{groff} and @acronym{AT&T}
1105 @item -d@var{c}@var{s}
1106 @itemx -d@var{name}=@var{s}
1107 Define @var{c} or @var{name} to be a string@w{ }@var{s}. @var{c}@w{ }must
1108 be a one-letter name; @var{name} can be of arbitrary length. All string
1109 assignments happen before loading any macro file (including the start-up
1113 Use @var{fam} as the default font family. @xref{Font Families}.
1116 Read in the file @file{@var{name}.tmac}. Normally @code{groff} searches
1117 for this in its macro directories. If it isn't found, it tries
1118 @file{tmac.@var{name}} (searching in the same directories).
1121 Number the first page @var{num}.
1124 @cindex print current page register (@code{.P})
1125 Output only pages in @var{list}, which is a comma-separated list of page
1126 ranges; @samp{@var{n}} means print page@w{ }@var{n}, @samp{@var{m}-@var{n}}
1127 means print every page between @var{m} and@w{ }@var{n}, @samp{-@var{n}}
1128 means print every page up to@w{ }@var{n}, @samp{@var{n}-} means print every
1129 page beginning with@w{ }@var{n}. @code{gtroff} exits after printing the
1130 last page in the list. All the ranges are inclusive on both ends.
1132 Within @code{gtroff}, this information can be extracted with the
1133 @samp{.P} register. @xref{Built-in Registers}.
1135 If your document restarts page numbering at the beginning of each
1136 chapter, then @code{gtroff} prints the specified page range for each
1139 @item -r@var{c}@var{n}
1140 @itemx -r@var{name}=@var{n}
1141 Set number register@w{ }@var{c} or @var{name} to the value@w{ }@var{n}.
1142 @var{c}@w{ }must be a one-letter name; @var{name} can be of arbitrary
1143 length. @var{n}@w{ }can be any @code{gtroff} numeric expression. All
1144 register assignments happen before loading any macro file (including
1148 Search @file{@var{dir}} for subdirectories @file{dev@var{name}}
1149 (@var{name} is the name of the device), for the @file{DESC} file, and
1150 for font files before looking in the standard directories (@pxref{Font
1151 Directories}). This option is passed to all pre- and postprocessors
1152 using the @env{GROFF_FONT_PATH} environment variable.
1155 Search directory @file{@var{dir}} for macro files before the standard
1156 directories (@pxref{Macro Directories}).
1159 This option is as described in @ref{gsoelim}. It implies the
1164 @c =====================================================================
1166 @node Environment, Macro Directories, Groff Options, Invoking groff
1167 @section Environment
1168 @cindex environment variables
1169 @cindex variables in environment
1171 There are also several environment variables (of the operating system,
1172 not within @code{gtroff}) which can modify the behavior of @code{groff}.
1175 @item GROFF_COMMAND_PREFIX
1176 @tindex GROFF_COMMAND_PREFIX@r{, environment variable}
1177 @cindex command prefix
1178 @cindex prefix, for commands
1179 If this is set to@w{ }@var{X}, then @code{groff} runs @code{@var{X}troff}
1180 instead of @code{gtroff}. This also applies to @code{tbl}, @code{pic},
1181 @code{eqn}, @code{grn}, @code{refer}, and @code{soelim}. It does not
1182 apply to @code{grops}, @code{grodvi}, @code{grotty}, @code{pre-grohtml},
1183 @code{post-grohtml}, @code{grolj4}, and @code{gxditview}.
1185 The default command prefix is determined during the installation process.
1186 If a non-GNU troff system is found, prefix @samp{g} is used, none
1189 @item GROFF_TMAC_PATH
1190 @tindex GROFF_TMAC_PATH@r{, environment variable}
1191 A colon-separated list of directories in which to search for macro files
1192 (before the default directories are tried). @xref{Macro Directories}.
1194 @item GROFF_TYPESETTER
1195 @tindex GROFF_TYPESETTER@r{, environment variable}
1196 The default output device.
1198 @item GROFF_FONT_PATH
1199 @tindex GROFF_FONT_PATH@r{, environment variable}
1200 A colon-separated list of directories in which to search for the
1201 @code{dev}@var{name} directory (before the default directories are
1202 tried). @xref{Font Directories}.
1204 @item GROFF_BIN_PATH
1205 @tindex GROFF_BIN_PATH@r{, environment variable}
1206 This search path, followed by @code{PATH}, is used for commands executed
1210 @tindex GROFF_TMPDIR@r{, environment variable}
1211 @tindex TMPDIR@r{, environment variable}
1212 The directory in which @code{groff} creates temporary files. If this is
1213 not set and @env{TMPDIR} is set, temporary files are created in that
1214 directory. Otherwise temporary files are created in a system-dependent
1215 default directory (on Unix and GNU/Linux systems, this is usually
1216 @file{/tmp}). @code{grops}, @code{grefer}, @code{pre-grohtml}, and
1217 @code{post-grohtml} can create temporary files in this directory.
1220 Note that MS-DOS and MS-Windows ports of @code{groff} use semi-colons,
1221 rather than colons, to separate the directories in the lists described
1225 @c =====================================================================
1227 @node Macro Directories, Font Directories, Environment, Invoking groff
1228 @section Macro Directories
1229 @cindex macro directories
1230 @cindex directories for macros
1231 @cindex searching macros
1232 @cindex macros, searching
1234 All macro file names must be named @code{@var{name}.tmac} or
1235 @code{tmac.@var{name}} to make the @option{-m@var{name}} command line
1236 option work. The @code{mso} request doesn't have this restriction; any
1237 file name can be used, and @code{gtroff} won't try to append or prepend
1238 the @samp{tmac} string.
1240 @cindex tmac, directory
1241 @cindex directory, for tmac files
1243 @cindex path, for tmac files
1244 @cindex searching macro files
1245 @cindex macro files, searching
1246 @cindex files, macro, searching
1247 Macro files are kept in the @dfn{tmac directories}, all of which
1248 constitute the @dfn{tmac path}. The elements of the search path for
1249 macro files are (in that order):
1253 The directories specified with @code{gtroff}'s or @code{groff}'s
1254 @option{-M} command line option.
1257 @tindex GROFF_TMAC_PATH@r{, environment variable}
1258 The directories given in the @env{GROFF_TMAC_PATH} environment
1265 @cindex mode, unsafe
1266 @cindex current directory
1267 @cindex directory, current
1268 The current directory (only if in unsafe mode using the @option{-U}
1269 command line switch).
1272 @cindex home directory
1273 @cindex directory, home
1277 @cindex site-specific directory
1278 @cindex directory, site-specific
1279 @cindex platform-specific directory
1280 @cindex directory, platform-specific
1281 A platform-dependent directory, a site-specific (platform-independent)
1282 directory, and the main tmac directory; the default locations are
1285 /usr/local/lib/groff/site-tmac
1286 /usr/local/share/groff/site-tmac
1287 /usr/local/share/groff/1.18/tmac
1291 assuming that the version of @code{groff} is 1.18, and the installation
1292 prefix was @file{/usr/local}. It is possible to fine-tune those
1293 directories during the installation process.
1297 @c =====================================================================
1299 @node Font Directories, Invocation Examples, Macro Directories, Invoking groff
1300 @section Font Directories
1301 @cindex font directories
1302 @cindex directories for fonts
1303 @cindex searching fonts
1304 @cindex fonts, searching
1306 Basically, there is no restriction how font files for @code{groff} are
1307 named and how long font names are; however, to make the font family
1308 mechanism work (@pxref{Font Families}), fonts within a family should
1309 start with the family name, followed by the shape. For example, the
1310 Times family uses @samp{T} for the family name and @samp{R}, @samp{B},
1311 @samp{I}, and @samp{BI} to indicate the shapes `roman', `bold',
1312 `italic', and `bold italic', respectively. Thus the final font names
1313 are @samp{TR}, @samp{TB}, @samp{TI}, and @samp{TBI}.
1316 @cindex path, for font files
1317 All font files are kept in the @dfn{font directories} which constitute
1318 the @dfn{font path}. The file search functions will always append the
1319 directory @code{dev}@var{name}, where @var{name} is the name of the
1320 output device. Assuming, say, DVI output, and @file{/foo/bar} as a
1321 font directory, the font files for @code{grodvi} must be in
1322 @file{/foo/bar/devdvi}.
1324 The elements of the search path for font files are (in that order):
1328 The directories specified with @code{gtroff}'s or @code{groff}'s
1329 @option{-F} command line option. All device drivers and some
1330 preprocessors also have this option.
1333 @tindex GROFF_FONT_PATH@r{, environment variable}
1334 The directories given in the @env{GROFF_FONT_PATH} environment
1338 @cindex site-specific directory
1339 @cindex directory, site-specific
1340 A site-specific directory and the main font directory; the default
1344 /usr/local/share/groff/site-font
1345 /usr/local/share/groff/1.18/font
1349 assuming that the version of @code{groff} is 1.18, and the installation
1350 prefix was @file{/usr/local}. It is possible to fine-tune those
1351 directories during the installation process.
1355 @c =====================================================================
1357 @node Invocation Examples, , Font Directories, Invoking groff
1358 @section Invocation Examples
1359 @cindex invocation examples
1360 @cindex examples of invocation
1362 This section lists several common uses of @code{groff} and the
1363 corresponding command lines.
1370 This command processes @file{file} without a macro package or a
1371 preprocessor. The output device is the default, @samp{ps}, and the
1372 output is sent to @code{stdout}.
1375 groff -t -mandoc -Tascii file | less
1379 This is basically what a call to the @code{man} program does.
1380 @code{gtroff} processes the manual page @file{file} with the
1381 @file{mandoc} macro file (which in turn either calls the @file{man} or
1382 the @file{mdoc} macro package), using the @code{tbl} preprocessor and
1383 the @acronym{ASCII} output device. Finally, the @code{less} pager
1384 displays the result.
1391 Preview @file{file} with @code{gxditview}, using the @file{me} macro
1392 package. Since no @option{-T} option is specified, use the default
1393 device (@samp{ps}). Note that you can either say @w{@samp{-m me}} or
1394 @w{@samp{-me}}; the latter is an anachronism from the early days of
1395 @acronym{UNIX}.@footnote{The same is true for the other main macro
1396 packages that come with @code{groff}: @file{man}, @file{mdoc},
1397 @file{ms}, @file{mm}, and @file{mandoc}. This won't work in general;
1398 for example, to load @file{trace.tmac}, either @samp{-mtrace} or
1399 @w{@samp{-m trace}} must be used.}
1402 groff -man -rD1 -z file
1406 Check @file{file} with the @file{man} macro package, forcing
1407 double-sided printing -- don't produce any output.
1413 @c ---------------------------------------------------------------------
1415 @node grog, , Invocation Examples, Invocation Examples
1416 @subsection @code{grog}
1419 @code{grog} reads files, guesses which of the @code{groff} preprocessors
1420 and/or macro packages are required for formatting them, and prints the
1421 @code{groff} command including those options on the standard output. It
1422 generates one or more of the options @option{-e}, @option{-man},
1423 @option{-me}, @option{-mm}, @option{-mom}, @option{-ms}, @option{-mdoc},
1424 @option{-mdoc-old}, @option{-p}, @option{-R}, @option{-g}, @option{-G},
1425 @option{-s}, and @option{-t}.
1427 A special file name@w{ }@file{-} refers to the standard input. Specifying
1428 no files also means to read the standard input. Any specified options
1429 are included in the printed command. No space is allowed between
1430 options and their arguments. The only options recognized are
1431 @option{-C} (which is also passed on) to enable compatibility mode, and
1432 @option{-v} to print the version number and exit.
1441 guesses the appropriate command to print @file{paper.ms} and then prints
1442 it to the command line after adding the @option{-Tdvi} option. For
1443 direct execution, enclose the call to @code{grog} in backquotes at the
1444 @acronym{UNIX} shell prompt:
1447 `grog -Tdvi paper.ms` > paper.dvi
1451 As seen in the example, it is still necessary to redirect the output to
1452 something meaningful (i.e.@: either a file or a pager program like
1457 @c =====================================================================
1458 @c =====================================================================
1460 @node Tutorial for Macro Users, Macro Packages, Invoking groff, Top
1461 @chapter Tutorial for Macro Users
1462 @cindex tutorial for macro users
1463 @cindex macros, tutorial for users
1464 @cindex user's tutorial for macros
1465 @cindex user's macro tutorial
1467 Most users tend to use a macro package to format their papers. This
1468 means that the whole breadth of @code{groff} is not necessary for most
1469 people. This chapter covers the material needed to efficiently use a
1478 @c =====================================================================
1480 @node Basics, Common Features, Tutorial for Macro Users, Tutorial for Macro Users
1482 @cindex basics of macros
1483 @cindex macro basics
1485 This section covers some of the basic concepts necessary to understand
1486 how to use a macro package.@footnote{This section is derived from
1487 @cite{Writing Papers with nroff using -me} by Eric P.@w{ }Allman.}
1488 References are made throughout to more detailed information, if desired.
1490 @code{gtroff} reads an input file prepared by the user and outputs a
1491 formatted document suitable for publication or framing. The input
1492 consists of text, or words to be printed, and embedded commands
1493 (@dfn{requests} and @dfn{escapes}), which tell @code{gtroff} how to
1494 format the output. For more detail on this, see @ref{Embedded
1497 The word @dfn{argument} is used in this chapter to mean a word or number
1498 which appears on the same line as a request, and which modifies the
1499 meaning of that request. For example, the request
1506 spaces one line, but
1513 spaces four lines. The number@w{ }4 is an argument to the @code{sp}
1514 request which says to space four lines instead of one. Arguments are
1515 separated from the request and from each other by spaces (@emph{no}
1516 tabs). More details on this can be found in @ref{Request Arguments}.
1518 The primary function of @code{gtroff} is to collect words from input
1519 lines, fill output lines with those words, justify the right-hand margin
1520 by inserting extra spaces in the line, and output the result. For
1528 Four score and seven
1533 is read, packed onto output lines, and justified to produce:
1536 Now is the time for all good men to come to the aid of their party.
1537 Four score and seven years ago, etc.
1542 Sometimes a new output line should be started even though the current
1543 line is not yet full; for example, at the end of a paragraph. To do
1544 this it is possible to cause a @dfn{break}, which starts a new output
1545 line. Some requests cause a break automatically, as normally do blank
1546 input lines and input lines beginning with a space.
1548 Not all input lines are text to be formatted. Some input lines are
1549 requests which describe how to format the text. Requests always have a
1550 period (@samp{.}) or an apostrophe (@samp{'}) as the first character of
1553 The text formatter also does more complex things, such as automatically
1554 numbering pages, skipping over page boundaries, putting footnotes in the
1555 correct place, and so forth.
1557 Here are a few hints for preparing text for input to @code{gtroff}.
1561 First, keep the input lines short. Short input lines are easier to
1562 edit, and @code{gtroff} packs words onto longer lines anyhow.
1565 In keeping with this, it is helpful to begin a new line after every
1566 comma or phrase, since common corrections are to add or delete sentences
1570 End each sentence with two spaces -- or better, start each sentence on a
1571 new line. @code{gtroff} recognizes characters that usually end a
1572 sentence, and inserts sentence space accordingly.
1575 Do not hyphenate words at the end of lines -- @code{gtroff} is smart
1576 enough to hyphenate words as needed, but is not smart enough to take
1577 hyphens out and join a word back together. Also, words such as
1578 ``mother-in-law'' should not be broken over a line, since then a space
1579 can occur where not wanted, such as ``@w{mother- in}-law''.
1582 @cindex double-spacing (@code{ls})
1584 @code{gtroff} double-spaces output text automatically if you use the
1585 request @w{@samp{.ls 2}}. Reactivate single-spaced mode by typing
1586 @w{@samp{.ls 1}}.@footnote{If you need finer granularity of the
1587 vertical space, use the @code{pvs} request (@pxref{Changing Type
1590 A number of requests allow to change the way the output looks,
1591 sometimes called the @dfn{layout} of the output page. Most of these
1592 requests adjust the placing of @dfn{whitespace} (blank lines or
1595 @cindex new page (@code{bp})
1596 The @code{bp} request starts a new page, causing a line break.
1598 @cindex blank line (@code{sp})
1599 @cindex empty line (@code{sp})
1600 @cindex line, empty (@code{sp})
1601 The request @w{@samp{.sp @var{N}}} leaves @var{N}@w{ }lines of blank
1602 space. @var{N}@w{ }can be omitted (meaning skip a single line) or can
1603 be of the form @var{N}i (for @var{N}@w{ }inches) or @var{N}c (for
1604 @var{N}@w{ }centimeters). For example, the input:
1608 My thoughts on the subject
1613 leaves one and a half inches of space, followed by the line ``My
1614 thoughts on the subject'', followed by a single blank line (more
1615 measurement units are available, see @ref{Measurements}).
1617 @cindex centering lines (@code{ce})
1618 @cindex lines, centering (@code{ce})
1619 Text lines can be centered by using the @code{ce} request. The line
1620 after @code{ce} is centered (horizontally) on the page. To center more
1621 than one line, use @w{@samp{.ce @var{N}}} (where @var{N} is the number
1622 of lines to center), followed by the @var{N}@w{ }lines. To center many
1623 lines without counting them, type:
1632 The @w{@samp{.ce 0}} request tells @code{groff} to center zero more
1633 lines, in other words, stop centering.
1635 @cindex line break (@code{br})
1636 @cindex break (@code{br})
1637 All of these requests cause a break; that is, they always start a new
1638 line. To start a new line without performing any other action, use
1642 @c =====================================================================
1644 @node Common Features, , Basics, Tutorial for Macro Users
1645 @section Common Features
1646 @cindex common features
1647 @cindex features, common
1649 @code{gtroff} provides very low-level operations for formatting a
1650 document. There are many common routine operations which are done in
1651 all documents. These common operations are written into @dfn{macros}
1652 and collected into a @dfn{macro package}.
1654 All macro packages provide certain common capabilities which fall into
1655 the following categories.
1659 * Sections and Chapters::
1660 * Headers and Footers::
1661 * Page Layout Adjustment::
1663 * Footnotes and Annotations::
1664 * Table of Contents::
1667 * Multiple Columns::
1668 * Font and Size Changes::
1669 * Predefined Strings::
1670 * Preprocessor Support::
1671 * Configuration and Customization::
1674 @c ---------------------------------------------------------------------
1676 @node Paragraphs, Sections and Chapters, Common Features, Common Features
1677 @subsection Paragraphs
1680 One of the most common and most used capability is starting a
1681 paragraph. There are a number of different types of paragraphs, any
1682 of which can be initiated with macros supplied by the macro package.
1683 Normally, paragraphs start with a blank line and the first line
1684 indented, like the text in this manual. There are also block style
1685 paragraphs, which omit the indentation:
1688 Some men look at constitutions with sanctimonious
1689 reverence, and deem them like the ark of the covenant, too
1690 sacred to be touched.
1694 And there are also indented paragraphs which begin with a tag or label
1695 at the margin and the remaining text indented.
1698 one This is the first paragraph. Notice how the first
1699 line of the resulting paragraph lines up with the
1700 other lines in the paragraph.
1704 This paragraph had a long label. The first
1705 character of text on the first line does not line up
1706 with the text on second and subsequent lines,
1707 although they line up with each other.
1710 A variation of this is a bulleted list.
1713 . Bulleted lists start with a bullet. It is possible
1714 to use other glyphs instead of the bullet. In nroff
1715 mode using the ASCII character set for output, a dot
1716 is used instead of a real bullet.
1720 @c ---------------------------------------------------------------------
1722 @node Sections and Chapters, Headers and Footers, Paragraphs, Common Features
1723 @subsection Sections and Chapters
1725 Most macro packages supply some form of section headers. The simplest
1726 kind is simply the heading on a line by itself in bold type. Others
1727 supply automatically numbered section heading or different heading
1728 styles at different levels. Some, more sophisticated, macro packages
1729 supply macros for starting chapters and appendices.
1731 @c ---------------------------------------------------------------------
1733 @node Headers and Footers, Page Layout Adjustment, Sections and Chapters, Common Features
1734 @subsection Headers and Footers
1736 Every macro package gives some way to manipulate the @dfn{headers} and
1737 @dfn{footers} (also called @dfn{titles}) on each page. This is text
1738 put at the top and bottom of each page, respectively, which contain
1739 data like the current page number, the current chapter title, and so
1740 on. Its appearance is not affected by the running text. Some packages
1741 allow for different ones on the even and odd pages (for material printed
1744 The titles are called @dfn{three-part titles}, that is, there is a
1745 left-justified part, a centered part, and a right-justified part. An
1746 automatically generated page number may be put in any of these fields
1747 with the @samp{%} character (see @ref{Page Layout}, for more details).
1749 @c ---------------------------------------------------------------------
1751 @node Page Layout Adjustment, Displays, Headers and Footers, Common Features
1752 @subsection Page Layout
1754 Most macro packages let the user specify top and bottom margins and
1755 other details about the appearance of the printed pages.
1757 @c ---------------------------------------------------------------------
1759 @node Displays, Footnotes and Annotations, Page Layout Adjustment, Common Features
1760 @subsection Displays
1763 @dfn{Displays} are sections of text to be set off from the body of
1764 the paper. Major quotes, tables, and figures are types of displays, as
1765 are all the examples used in this document.
1767 @cindex quotes, major
1768 @cindex major quotes
1769 @dfn{Major quotes} are quotes which are several lines long, and hence
1770 are set in from the rest of the text without quote marks around them.
1773 A @dfn{list} is an indented, single-spaced, unfilled display. Lists
1774 should be used when the material to be printed should not be filled and
1775 justified like normal text, such as columns of figures or the examples
1779 A @dfn{keep} is a display of lines which are kept on a single page if
1780 possible. An example for a keep might be a diagram. Keeps differ from
1781 lists in that lists may be broken over a page boundary whereas keeps are
1784 @cindex keep, floating
1785 @cindex floating keep
1786 @dfn{Floating keeps} move relative to the text. Hence, they are good for
1787 things which are referred to by name, such as ``See figure@w{ }3''. A
1788 floating keep appears at the bottom of the current page if it fits;
1789 otherwise, it appears at the top of the next page. Meanwhile, the
1790 surrounding text `flows' around the keep, thus leaving no blank areas.
1792 @c ---------------------------------------------------------------------
1794 @node Footnotes and Annotations, Table of Contents, Displays, Common Features
1795 @subsection Footnotes and Annotations
1799 There are a number of requests to save text for later printing.
1801 @dfn{Footnotes} are printed at the bottom of the current page.
1803 @cindex delayed text
1804 @dfn{Delayed text} is very similar to a footnote except that it is
1805 printed when called for explicitly. This allows a list of references to
1806 appear (for example) at the end of each chapter, as is the convention in
1809 Most macro packages which supply this functionality also supply a means
1810 of automatically numbering either type of annotation.
1812 @c ---------------------------------------------------------------------
1814 @node Table of Contents, Indices, Footnotes and Annotations, Common Features
1815 @subsection Table of Contents
1816 @cindex table of contents
1817 @cindex contents, table of
1819 @dfn{Tables of contents} are a type of delayed text having a tag
1820 (usually the page number) attached to each entry after a row of dots.
1821 The table accumulates throughout the paper until printed, usually after
1822 the paper has ended. Many macro packages provide the ability to have
1823 several tables of contents (e.g.@: a standard table of contents, a list
1826 @c ---------------------------------------------------------------------
1828 @node Indices, Paper Formats, Table of Contents, Common Features
1830 @cindex index, in macro package
1832 While some macro packages use the term @dfn{index}, none actually
1833 provide that functionality. The facilities they call indices are
1834 actually more appropriate for tables of contents.
1837 To produce a real index in a document, external tools like the
1838 @code{makeindex} program are necessary.
1840 @c ---------------------------------------------------------------------
1842 @node Paper Formats, Multiple Columns, Indices, Common Features
1843 @subsection Paper Formats
1844 @cindex paper formats
1846 Some macro packages provide stock formats for various kinds of
1847 documents. Many of them provide a common format for the title and
1848 opening pages of a technical paper. The @file{mm} macros in particular
1849 provide formats for letters and memoranda.
1851 @c ---------------------------------------------------------------------
1853 @node Multiple Columns, Font and Size Changes, Paper Formats, Common Features
1854 @subsection Multiple Columns
1856 Some macro packages (but not @file{man}) provide the ability to have two
1857 or more columns on a page.
1859 @c ---------------------------------------------------------------------
1861 @node Font and Size Changes, Predefined Strings, Multiple Columns, Common Features
1862 @subsection Font and Size Changes
1864 The built-in font and size functions are not always intuitive, so all
1865 macro packages provide macros to make these operations simpler.
1867 @c ---------------------------------------------------------------------
1869 @node Predefined Strings, Preprocessor Support, Font and Size Changes, Common Features
1870 @subsection Predefined Strings
1872 Most macro packages provide various predefined strings for a variety of
1873 uses; examples are sub- and superscripts, printable dates, quotes and
1874 various special characters.
1876 @c ---------------------------------------------------------------------
1878 @node Preprocessor Support, Configuration and Customization, Predefined Strings, Common Features
1879 @subsection Preprocessor Support
1881 All macro packages provide support for various preprocessors and may
1882 extend their functionality.
1884 For example, all macro packages mark tables (which are processed with
1885 @code{gtbl}) by placing them between @code{TS} and @code{TE} macros.
1886 The @file{ms} macro package has an option, @samp{.TS@w{ }H}, that prints
1887 a caption at the top of a new page (when the table is too long to fit on
1890 @c ---------------------------------------------------------------------
1892 @node Configuration and Customization, , Preprocessor Support, Common Features
1893 @subsection Configuration and Customization
1895 Some macro packages provide means of customizing many of the details of
1896 how the package behaves. This ranges from setting the default type size
1897 to changing the appearance of section headers.
1901 @c =====================================================================
1902 @c =====================================================================
1904 @node Macro Packages, gtroff Reference, Tutorial for Macro Users, Top
1905 @chapter Macro Packages
1906 @cindex macro packages
1907 @cindex packages, macros
1909 This chapter documents the main macro packages that come with
1921 @c =====================================================================
1923 @node man, mdoc, Macro Packages, Macro Packages
1925 @cindex manual pages
1929 @pindex man-old.tmac
1931 This is the most popular and probably the most important macro package
1932 of @code{groff}. It is easy to use, and a vast majority of manual pages
1939 * Miscellaneous man macros::
1940 * Predefined man strings::
1941 * Preprocessors in man pages::
1944 @c ---------------------------------------------------------------------
1946 @node Man options, Man usage, man, man
1949 The command line format for using the @file{man} macros with
1953 groff -m man [ -rLL=@var{length} ] [ -rLT=@var{length} ]
1954 [ -rcR=1 ] [ -rC1 ] [ -rD1 ] [ -rP@var{nnn} ]
1955 [ -rS@var{xx} ] [ -rX@var{nnn} ] [ @var{files}@dots{} ]
1959 It is possible to use @samp{-man} instead of @w{@samp{-m man}}.
1962 @item -rLL=@var{length}
1963 Set line length to @var{length}. If not specified, the line length
1964 defaults to 78@w{ }en in nroff mode (this is 78@w{ }characters per
1965 line) and 6.5@w{ }inch otherwise.
1967 @item -rLT=@var{length}
1968 Set title length to @var{length}. If not specified, the title length
1969 defaults to 78@w{ }en in nroff mode (this is 78@w{ }characters per
1970 line) and 6.5@w{ }inch otherwise.
1973 This option (the default if a TTY output device is used) creates a
1974 single, very long page instead of multiple pages. Use @code{-rcR=0}
1978 If more than one manual page is given on the command line, number the
1979 pages continuously, rather than starting each at@w{ }1.
1982 Double-sided printing. Footers for even and odd pages are formatted
1986 Page numbering starts with @var{nnn} rather than with@w{ }1.
1989 Use @var{xx} (which can be 10, 11, or@w{ }12@dmn{pt}) as the base
1990 document font size instead of the default value of@w{ }10@dmn{pt}.
1993 After page @var{nnn}, number pages as @var{nnn}a, @var{nnn}b,
1994 @var{nnn}c, etc. For example, the option @option{-rX2} produces the
1995 following page numbers: 1, 2, 2a, 2b, 2c, etc.
1998 @c ---------------------------------------------------------------------
2000 @node Man usage, Man font macros, Man options, man
2002 @cindex @code{man} macros
2003 @cindex macros for manual pages [@code{man}]
2006 This section describes the available macros for manual pages. For
2007 further customization, put additional macros and requests into the file
2008 @file{man.local} which is loaded immediately after the @file{man}
2011 @Defmac {TH, title section [@Var{extra1} [@Var{extra2} [@Var{extra3}]]], man}
2012 Set the title of the man page to @var{title} and the section to
2013 @var{section}, which must have a value between 1 and@w{ }8. The value
2014 of @var{section} may also have a string appended, e.g.@: @samp{.pm},
2015 to indicate a specific subsection of the man pages.
2017 Both @var{title} and @var{section} are positioned at the left and right
2018 in the header line (with @var{section} in parentheses immediately
2019 appended to @var{title}. @var{extra1} is positioned in the middle of
2020 the footer line. @var{extra2} is positioned at the left in the footer
2021 line (or at the left on even pages and at the right on odd pages if
2022 double-sided printing is active). @var{extra3} is centered in the
2025 For @acronym{HTML} output, headers and footers are completely suppressed.
2027 Additionally, this macro starts a new page; the new line number is@w{ }1
2028 again (except if the @option{-rC1} option is given on the command line)
2029 -- this feature is intended only for formatting multiple man pages; a
2030 single man page should contain exactly one @code{TH} macro at the
2031 beginning of the file.
2034 @Defmac {SH, [@Var{heading}], man}
2035 Set up an unnumbered section heading sticking out to the left. Prints
2036 out all the text following @code{SH} up to the end of the line (or the
2037 text in the next line if there is no argument to @code{SH}) in bold
2038 face, one size larger than the base document size. Additionally, the
2039 left margin for the following text is reset to its default value.
2042 @Defmac {SS, [@Var{heading}], man}
2043 Set up an unnumbered (sub)section heading. Prints out all the text
2044 following @code{SS} up to the end of the line (or the text in the next
2045 line if there is no argument to @code{SS}) in bold face, at the same
2046 size as the base document size. Additionally, the left margin for the
2047 following text is reset to its default value.
2050 @Defmac {TP, [@Var{nnn}], man}
2051 Set up an indented paragraph with label. The indentation is set to
2052 @var{nnn} if that argument is supplied (the default unit is @samp{n}
2053 if omitted), otherwise it is set to the default indentation value.
2055 The first line of text following this macro is interpreted as a string
2056 to be printed flush-left, as it is appropriate for a label. It is not
2057 interpreted as part of a paragraph, so there is no attempt to fill the
2058 first line with text from the following input lines. Nevertheless, if
2059 the label is not as wide as the indentation, then the paragraph starts
2060 at the same line (but indented), continuing on the following lines.
2061 If the label is wider than the indentation, then the descriptive part
2062 of the paragraph begins on the line following the label, entirely
2063 indented. Note that neither font shape nor font size of the label is
2064 set to a default value; on the other hand, the rest of the text has
2065 default font settings.
2068 @DefmacList {LP, , man}
2069 @DefmacItem {PP, , man}
2070 @DefmacListEnd {P, , man}
2071 These macros are mutual aliases. Any of them causes a line break at
2072 the current position, followed by a vertical space downwards by the
2073 amount specified by the @code{PD} macro. The font size and shape are
2074 reset to the default value (10@dmn{pt} roman if no @option{-rS} option
2075 is given on the command line). Finally, the current left margin is
2079 @Defmac {IP, [@Var{designator} [@Var{nnn}]], man}
2080 Set up an indented paragraph, using @var{designator} as a tag to mark
2081 its beginning. The indentation is set to @var{nnn} if that argument
2082 is supplied (default unit is @samp{n}), otherwise the default
2083 indentation value is used. Font size and face of the paragraph (but
2084 not the designator) are reset to their default values. To start an
2085 indented paragraph with a particular indentation but without a
2086 designator, use @samp{""} (two double quotes) as the first argument of
2089 For example, to start a paragraph with bullets as the designator and
2090 4@w{ }en indentation, write
2097 @Defmac {HP, [@Var{nnn}], man}
2098 @cindex hanging indentation [@code{man}]
2099 @cindex @code{man} macros, hanging indentation
2100 Set up a paragraph with hanging left indentation. The indentation is
2101 set to @var{nnn} if that argument is supplied (default unit is
2102 @samp{n}), otherwise the default indentation value is used. Font size
2103 and face are reset to their default values.
2106 @Defmac {RS, [@Var{nnn}], man}
2107 @cindex left margin, how to move [@code{man}]
2108 @cindex @code{man} macros, moving left margin
2109 Move the left margin to the right by the value @var{nnn} if specified
2110 (default unit is @samp{n}); otherwise the default indentation value
2111 is used. Calls to the @code{RS} macro can be nested.
2114 @Defmac {RE, [@Var{nnn}], man}
2115 Move the left margin back to level @var{nnn}; if no argument is given,
2116 it moves one level back. The first level (i.e., no call to @code{RS}
2117 yet) has number@w{ }1, and each call to @code{RS} increases the level
2121 @cindex line breaks, with vertical space [@code{man}]
2122 @cindex @code{man} macros, line breaks with vertical space
2123 To summarize, the following macros cause a line break with the insertion
2124 of vertical space (which amount can be changed with the @code{PD}
2125 macro): @code{SH}, @code{SS}, @code{TP}, @code{LP} (@code{PP},
2126 @code{P}), @code{IP}, and @code{HP}.
2128 @cindex line breaks, without vertical space [@code{man}]
2129 @cindex @code{man} macros, line breaks without vertical space
2130 The macros @code{RS} and @code{RE} also cause a break but do not insert
2133 @cindex default indentation, resetting [@code{man}]
2134 @cindex indentaion, resetting to default [@code{man}]
2135 @cindex @code{man} macros, resetting default indentation
2136 Finally, the macros @code{SH}, @code{SS}, @code{LP} (@code{PP}, @code{P}),
2137 and @code{RS} reset the indentation to its default value.
2139 @c ---------------------------------------------------------------------
2141 @node Man font macros, Miscellaneous man macros, Man usage, man
2142 @subsection Macros to set fonts
2143 @cindex font selection [@code{man}]
2144 @cindex @code{man} macros, how to set fonts
2146 The standard font is roman; the default text size is 10@w{ }point.
2147 If command line option @option{-rS=@var{n}} is given, use
2148 @var{n}@dmn{pt} as the default text size.
2150 @Defmac {SM, [@Var{text}], man}
2151 Set the text on the same line or the text on the next line in a font
2152 that is one point size smaller than the default font.
2155 @Defmac {SB, [@Var{text}], man}
2156 @cindex bold face [@code{man}]
2157 @cindex @code{man} macros, bold face
2158 Set the text on the same line or the text on the next line in bold face
2159 font, one point size smaller than the default font.
2162 @Defmac {BI, text, man}
2163 Set its arguments alternately in bold face and italic. Thus,
2166 .BI this "word and" that
2170 would set ``this'' and ``that'' in bold face, and ``word and'' in
2174 @Defmac {IB, text, man}
2175 Set its arguments alternately in italic and bold face.
2178 @Defmac {RI, text, man}
2179 Set its arguments alternately in roman and italic.
2182 @Defmac {IR, text, man}
2183 Set its arguments alternately in italic and roman.
2186 @Defmac {BR, text, man}
2187 Set its arguments alternately in bold face and roman.
2190 @Defmac {RB, text, man}
2191 Set its arguments alternately in roman and bold face.
2194 @Defmac {B, [@Var{text}], man}
2195 Set @var{text} in bold face. If no text is present on the line where
2196 the macro is called, then the text of the next line appears in bold
2200 @Defmac {I, [@Var{text}], man}
2201 @cindex italic fonts [@code{man}]
2202 @cindex @code{man} macros, italic fonts
2203 Set @var{text} in italic. If no text is present on the line where the
2204 macro is called, then the text of the next line appears in italic.
2207 @c ---------------------------------------------------------------------
2209 @node Miscellaneous man macros, Predefined man strings, Man font macros, man
2210 @subsection Miscellaneous macros
2213 @cindex @code{man} macros, default indentation
2214 @cindex default indentation [@code{man}]
2215 The default indentation is 7.2@w{ }en for all output devices except for
2216 @code{grohtml} which ignores indentation.
2219 @cindex tab stops [@code{man}]
2220 @cindex @code{man} macros, tab stops
2221 Set tabs every 0.5@w{ }inches. Since this macro is always executed
2222 during a call to the @code{TH} macro, it makes sense to call it only if
2223 the tab positions have been changed.
2226 @Defmac {PD, [@Var{nnn}], man}
2227 @cindex empty space before a paragraph [@code{man}]
2228 @cindex @code{man} macros, empty space before a paragraph
2229 Adjust the empty space before a new paragraph (or section). The
2230 optional argument gives the amount of space (default unit is
2231 @samp{v}); without parameter, the value is reset to its default value
2232 (1@w{ }line for TTY devices, 0.4@dmn{v}@w{ }otherwise).
2235 This affects the macros @code{SH}, @code{SS}, @code{TP}, @code{LP} (as
2236 well as @code{PP} and @code{P}), @code{IP}, and @code{HP}.
2238 @c ---------------------------------------------------------------------
2240 @node Predefined man strings, Preprocessors in man pages, Miscellaneous man macros, man
2241 @subsection Predefined strings
2243 The following strings are defined:
2246 Switch back to the default font size.
2250 The `registered' sign.
2254 The `trademark' sign.
2257 @DefstrList {lq, man}
2258 @DefstrListEnd {rq, man}
2259 @cindex @code{lq} glyph, and @code{lq} string [@code{man}]
2260 @cindex @code{rq} glyph, and @code{rq} string [@code{man}]
2261 Left and right quote. This is equal to @code{\(lq} and @code{\(rq},
2265 @c ---------------------------------------------------------------------
2267 @node Preprocessors in man pages, , Predefined man strings, man
2268 @subsection Preprocessors in @file{man} pages
2270 @cindex preprocessor, calling convention
2271 @cindex calling convention of preprocessors
2272 If a preprocessor like @code{gtbl} or @code{geqn} is needed, it has
2273 become common usage to make the first line of the man page look like
2280 @pindex geqn@r{, invocation in manual pages}
2281 @pindex grefer@r{, invocation in manual pages}
2282 @pindex gtbl@r{, invocation in manual pages}
2283 @pindex man@r{, invocation of preprocessors}
2285 Note the single space character after the double quote. @var{word}
2286 consists of letters for the needed preprocessors: @samp{e} for
2287 @code{geqn}, @samp{r} for @code{grefer}, @samp{t} for @code{gtbl}.
2288 Modern implementations of the @code{man} program read this first line
2289 and automatically call the right preprocessor(s).
2292 @c =====================================================================
2294 @node mdoc, ms, man, Macro Packages
2295 @section @file{mdoc}
2296 @cindex @code{mdoc} macros
2298 @c XXX documentation
2299 @c XXX this is a placeholder until we get stuff knocked into shape
2300 See the @cite{groff_mdoc(7)} man page (type @command{man groff_mdoc}
2301 at the command line).
2304 @c =====================================================================
2306 @node ms, me, mdoc, Macro Packages
2308 @cindex @code{ms} macros
2311 macros are suitable for reports, letters, books,
2312 user manuals, and so forth.
2313 The package provides macros for cover pages, section headings,
2314 paragraphs, lists, footnotes, pagination,
2315 and a table of contents.
2319 * General ms Structure::
2320 * ms Document Control Registers::
2321 * ms Cover Page Macros::
2324 * Differences from AT&T ms::
2327 @c ---------------------------------------------------------------------
2329 @node ms Intro, General ms Structure, ms, ms
2330 @subsection Introduction to @file{ms}
2332 The original @file{-ms} macros were included with
2333 @acronym{AT&T} @code{troff} as well as the
2335 While the @file{man} package is intended for brief documents
2336 that can be read on-line as well as printed, the @file{ms}
2337 macros are suitable for longer documents that are meant to be
2338 printed rather than read on-line.
2340 The @file{ms} macro package included with @code{groff}
2341 is a complete, bottom-up re-implementation.
2342 Several macros (specific to @acronym{AT&T}
2343 or Berkeley) are not included, while several new commands are.
2344 @xref{Differences from AT&T ms}, for more information.
2346 @c ---------------------------------------------------------------------
2348 @node General ms Structure, ms Document Control Registers, ms Intro, ms
2349 @subsection General structure of an @file{ms} document
2350 @cindex @code{ms} macros, general structure
2352 The @file{ms} macro package expects a certain amount of structure,
2353 but not as much as packages such as @file{man} or @file{mdoc}.
2355 The simplest documents can begin with a paragraph macro
2356 (such as @code{LP} or @code{PP}),
2357 and consist of text separated by paragraph macros
2358 or even blank lines.
2359 Longer documents have a structure as follows:
2363 If you invoke the @code{RP}
2364 (report) macro on the first line of the document,
2365 @code{groff} prints the cover page information on its own page;
2366 otherwise it prints the information on the
2367 first page with your document text immediately following.
2368 Other document formats found in @acronym{AT&T} @code{troff}
2369 are specific to @acronym{AT&T} or Berkeley, and are not supported in
2372 @item Format and layout
2373 By setting number registers,
2374 you can change your document's type (font and size),
2375 margins, spacing, headers and footers, and footnotes.
2376 @xref{ms Document Control Registers}, for more details.
2379 A cover page consists of a title, the author's name and institution,
2380 an abstract, and the date.
2381 @footnote{Actually, only the title is required.}
2382 @xref{ms Cover Page Macros}, for more details.
2385 Following the cover page is your document.
2386 You can use the @file{ms}
2387 macros to write reports, letters, books, and so forth.
2388 The package is designed for structured documents,
2389 consisting of paragraphs interspersed with headings
2390 and augmented by lists, footnotes, tables, and other
2392 @xref{ms Body Text}, for more details.
2394 @item Table of contents
2395 Longer documents usually include a table of contents,
2396 which you can invoke by placing the
2398 macro at the end of your document.
2400 macros have minimal indexing facilities, consisting of the
2401 @code{IX} macro, which prints an entry on standard error.
2402 Printing the table of contents at the end is necessary since
2403 @code{groff} is a single-pass text formatter,
2404 thus it cannot determine the page number of each section
2405 until that section has actually been set and printed.
2406 Since @file{ms} output is intended for hardcopy,
2407 you can manually relocate the pages containing
2408 the table of contents between the cover page and the
2409 body text after printing.
2412 @c ---------------------------------------------------------------------
2414 @node ms Document Control Registers, ms Cover Page Macros, General ms Structure, ms
2415 @subsection Document control registers
2416 @cindex @code{ms} macros, document control registers
2418 The following is a list of document control number registers.
2419 For the sake of consistency,
2420 set registers related to margins at the beginning of your document,
2421 or just after the @code{RP} macro.
2422 You can set other registers later in your document,
2423 but you should keep them together at the beginning
2424 to make them easy to find and edit as necessary.
2426 @unnumberedsubsubsec Margin Settings
2429 Defines the page offset (i.e.@: the left margin).
2430 There is no explicit right margin setting; the combination of
2431 the @code{PO} and @code{LL} registers implicitly define the
2434 Effective: next page.
2436 Default value: 1@dmn{i}.
2440 Defines the line length (i.e.@: the width of the body text).
2442 Effective: next paragraph.
2448 Defines the title length (i.e.@: the header and footer width).
2449 This is usually the same as @code{LL}, but not necessarily.
2451 Effective: next paragraph.
2457 Defines the header margin height at the top of the page.
2459 Effective: next page.
2465 Defines the footer margin height at the bottom of the page.
2467 Effective: next page.
2472 @unnumberedsubsubsec Text Settings
2475 Defines the point size of the body text.
2477 Effective: next paragraph.
2483 Defines the space between lines (line height plus leading).
2485 Effective: next paragraph.
2490 @unnumberedsubsubsec Paragraph Settings
2493 Defines the initial indent of a @code{.PP} paragraph.
2495 Effective: next paragraph.
2501 Defines the space between paragraphs.
2503 Effective: next paragraph.
2505 Default: 0.3@dmn{v}.
2509 Defines the indent on both sides of a quoted (@code{.QP}) paragraph.
2511 Effective: next paragraph.
2516 @unnumberedsubsubsec Footnote Settings
2519 Defines the length of a footnote.
2521 Effective: next footnote.
2523 Default: @math{@code{@\n[LL]} * 5 / 6}.
2527 Defines the footnote indent.
2529 Effective: next footnote.
2535 The footnote format:
2538 Prints the footnote number as a superscript; indents the footnote (default).
2541 Prints the number followed by a period (like 1.)
2542 and indents the footnote.
2545 Like 1, without an indent.
2548 Like 1, but prints the footnote number as a hanging paragraph.
2551 Effective: next footnote.
2556 @unnumberedsubsubsec Miscellaneous Number Registers
2558 @Defmpreg {MINGW, ms}
2559 Defines the minimum width between columns in a multi-column document.
2561 Effective: next page.
2566 @c ---------------------------------------------------------------------
2568 @node ms Cover Page Macros, ms Body Text, ms Document Control Registers, ms
2569 @subsection Cover page macros
2570 @cindex @code{ms} macros, cover page
2571 @cindex cover page macros, [@code{ms}]
2573 Use the following macros to create a cover page for your document
2576 @Defmac {RP, [@code{no}], ms}
2577 Specifies the report format for your document.
2578 The report format creates a separate cover page.
2579 The default action (no @code{.RP}
2580 macro) is to print a subset of the
2581 cover page on page 1 of your document.
2583 If you use the word @code{no} as an optional argument,
2584 @code{groff} prints a title page but
2585 does not repeat any of the title page information
2586 (title, author, abstract, etc.)
2587 on page 1 of the document.
2590 @Defmac {DA, [@dots{}], ms}
2591 (optional) Print the current date, or the arguments to the macro if any,
2592 on the title page (if specified) and in the footers.
2593 This is the default for @code{nroff}.
2596 @Defmac {ND, [@dots{}], ms}
2597 (optional) Print the current date, or the arguments to the macro if any,
2598 on the title page (if specified) but not in the footers.
2599 This is the default for @code{troff}.
2603 Specifies the document title.
2604 @code{groff} collects text following the @code{.TL}
2605 macro into the title, until reaching the author name or abstract.
2609 Specifies the author's name, which appears on the
2610 line (or lines) immediately following.
2611 You can specify multiple authors as follows:
2617 University of West Bumblefuzz
2621 Monolithic Corporation
2628 Specifies the author's institution.
2629 You can specify multiple institutions in the same way
2630 that you specify multiple authors.
2633 @Defmac {AB, [@code{no}], ms}
2634 Begins the abstract.
2635 The default is to print the word @acronym{ABSTRACT},
2636 centered and in italics, above the text of the abstract.
2637 The word @code{no} as an optional argument suppresses this heading.
2644 The following is example mark-up for a title page.
2645 @cindex title page, example markup
2646 @cindex example markup, title page
2652 The Inevitability of Code Bloat
2653 in Commercial and Free Software
2657 University of West Bumblefuzz
2659 This report examines the long-term growth
2660 of the code bases in two large, popular software
2661 packages; the free Emacs and the commercial
2663 While differences appear in the type or order
2664 of features added, due to the different
2665 methodologies used, the results are the same
2668 The free software approach is shown to be
2669 superior in that while free software can
2670 become as bloated as commercial offerings,
2671 free software tends to have fewer serious
2672 bugs and the added features are in line with
2676 ... the rest of the paper follows ...
2680 @c ---------------------------------------------------------------------
2682 @node ms Body Text, ms Page Layout, ms Cover Page Macros, ms
2683 @subsection Body text
2684 @cindex @code{ms} macros, body text
2686 This section describes macros used to mark up the body of your document.
2687 Examples include paragraphs, sections, and other groups.
2690 * Paragraphs in ms::
2692 * Highlighting in ms::
2696 * ms Displays and Keeps::
2698 * Example multi-page table::
2702 @c ---------------------------------------------------------------------
2704 @node Paragraphs in ms, Headings in ms, ms Body Text, ms Body Text
2705 @subsubsection Paragraphs
2706 @cindex @code{ms} macros, paragraph handling
2708 The following paragraph types are available.
2711 Sets a paragraph with an initial indent.
2715 Sets a paragraph with no initial indent.
2719 Sets a paragraph that is indented at both left and right margins.
2720 The effect is identical to the @acronym{HTML} @code{<BLOCKQUOTE>} element.
2721 The next paragraph or heading returns margins to normal.
2725 Sets a paragraph whose lines are indented,
2726 except for the first line.
2727 This is a Berkeley extension.
2730 The following markup uses all four paragraph macros.
2735 Cases used in the study
2737 The following software and versions were
2738 considered for this report.
2740 For commercial software, we chose
2741 .B "Microsoft Word for Windows" ,
2742 starting with version 1.0 through the
2743 current version (Word 2000).
2745 For free software, we chose
2747 from its first appearance as a standalone
2748 editor through the current version (v20).
2749 See [Bloggs 2002] for details.
2751 Franklin's Law applied to software:
2752 software expands to outgrow both
2753 RAM and disk space over time.
2758 .I "Everyone's a Critic" ,
2759 Underground Press, March 2002.
2760 A definitive work that answers all questions
2761 and criticisms about the quality and usability of
2767 @c ---------------------------------------------------------------------
2769 @node Headings in ms, Highlighting in ms, Paragraphs in ms, ms Body Text
2770 @subsubsection Headings
2771 @cindex @code{ms} macros, headings
2773 Use headings to create a hierarchical structure for your document.
2774 The @file{ms} macros print headings in @strong{bold},
2775 using the same font family and point size as the body text.
2777 The following describes the heading macros:
2779 @DefmacList {NH, @Var{curr-level}, ms}
2780 @DefmacListEnd {NH, @t{S} @Var{level0} @dots{}, ms}
2782 The argument is either a numeric argument to indicate the
2783 level of the heading, or the letter@w{ }@code{S} followed by numeric
2784 arguments to set the heading level explicitly.
2786 If you specify heading levels out of sequence, such as invoking
2787 @samp{.NH 3} after @samp{.NH 1}, @code{groff}
2788 prints a warning on standard error.
2792 Unnumbered subheading.
2795 @c ---------------------------------------------------------------------
2797 @node Highlighting in ms, Lists in ms, Headings in ms, ms Body Text
2798 @subsubsection Highlighting
2799 @cindex @code{ms} macros, highlighting
2801 The @file{ms} macros provide a variety of methods to highlight
2804 @Defmac {B, [@Var{txt} [@Var{post} [@Var{pre}]]], ms}
2805 Sets its first argument in @strong{bold type}.
2806 If you specify a second argument, @code{groff} prints it in the
2807 previous font after the bold text, with no intervening space
2808 (this allows you to set punctuation after the highlighted text
2809 without highlighting the punctuation).
2810 Similarly, it prints the third argument (if any) in the previous
2811 font @strong{before} the first argument.
2818 prints (@strong{foo}).
2820 If you give this macro no arguments, @code{groff}
2821 prints all text following in bold until
2822 the next highlighting, paragraph, or heading macro.
2825 @Defmac {R, [@Var{txt} [@Var{post} [@Var{pre}]]], ms}
2826 Sets its first argument in roman (or regular) type.
2827 It operates similarly to the @code{B}@w{ }macro otherwise.
2830 @Defmac {I, [@Var{txt} [@Var{post} [@Var{pre}]]], ms}
2831 Sets its first argument in @emph{italic type}.
2832 It operates similarly to the @code{B}@w{ }macro otherwise.
2835 @Defmac {CW, [@Var{txt} [@Var{post} [@Var{pre}]]], ms}
2836 Sets its first argument in a @code{constant width face}.
2837 It operates similarly to the @code{B}@w{ }macro otherwise.
2840 @Defmac {BI, [@Var{txt} [@Var{post} [@Var{pre}]]], ms}
2841 Sets its first argument in bold italic type.
2842 It operates similarly to the @code{B}@w{ }macro otherwise.
2845 @Defmac {BX, [@Var{txt}], ms}
2846 Prints its argument and draws a box around it.
2847 If you want to box a string that contains spaces,
2848 use a digit-width space (@code{\0}).
2851 @Defmac {UL, [@Var{txt} [@Var{post}]], ms}
2852 Prints its first argument with an underline.
2853 If you specify a second argument, @code{groff}
2854 prints it in the previous font after
2855 the underlined text, with no intervening space.
2859 Prints all text following in larger type
2860 (two points larger than the current point size) until
2861 the next font size, highlighting, paragraph, or heading macro.
2862 You can specify this macro multiple times
2863 to enlarge the point size as needed.
2867 Prints all text following in smaller type
2868 (two points smaller than the current point size) until
2869 the next type size, highlighting, paragraph, or heading macro.
2870 You can specify this macro multiple times
2871 to reduce the point size as needed.
2875 Prints all text following in the normal point size
2876 (that is, the value of the @code{PS} register).
2879 @c ---------------------------------------------------------------------
2881 @node Lists in ms, Indents in ms, Highlighting in ms, ms Body Text
2882 @subsubsection Lists
2883 @cindex @code{ms} macros, lists
2885 The @code{.IP} macro handles duties for all lists.
2887 @Defmac {IP, [@Var{marker} [@Var{width}]], ms}
2888 The @var{marker} is usually a bullet glyph (@code{\[bu]})
2889 for unordered lists, a number (or auto-incrementing number
2890 register) for numbered lists, or a word or phrase for indented
2891 (glossary-style) lists.
2893 The @var{width} specifies the indent for the body of each list item;
2894 its default unit is @samp{n}.
2895 Once specified, the indent remains the same for all
2896 list items in the document until specified again.
2899 The following is an example of a bulleted list.
2900 @cindex example markup, bulleted list [@code{ms}]
2901 @cindex bulleted list, example markup [@code{ms}]
2927 The following is an example of a numbered list.
2928 @cindex example markup, numbered list [@code{ms}]
2929 @cindex numbered list, example markup [@code{ms}]
2954 Note the use of the auto-incrementing number
2955 register in this example.
2958 The following is an example of a glossary-style list.
2959 @cindex example markup, glossary-style list [@code{ms}]
2960 @cindex glossary-style list, example markup [@code{ms}]
2963 A glossary-style list:
2965 Two or more attorneys.
2967 Firearms, preferably
2977 A glossary-style list:
2980 Two or more attorneys.
2982 guns Firearms, preferably large-caliber.
2985 Gotta pay for those lawyers and guns!
2988 In the last example, the @code{IP} macro places the definition
2989 on the same line as the term if it has enough space; otherwise,
2990 it breaks to the next line and starts the definition below the
2992 This may or may not be the effect you want, especially if some
2993 of the definitions break and some do not.
2994 The following examples show two possible ways to force a break.
2996 The first workaround uses the @code{br}
2997 request to force a break after printing the term or label.
3001 A glossary-style list:
3003 Two or more attorneys.
3006 Firearms, preferably large-caliber.
3008 Gotta pay for those lawyers and guns!
3013 The second workaround uses the @code{\p} escape to force the break.
3014 Note the space following the escape; this is important.
3015 If you omit the space, @code{groff} prints the first word on
3016 the same line as the term or label (if it fits) @strong{then}
3021 A glossary-style list:
3023 Two or more attorneys.
3025 \p Firearms, preferably large-caliber.
3027 Gotta pay for those lawyers and guns!
3032 To set nested lists, use the @code{RS} and @code{RE} macros.
3033 @xref{Indents in ms}, for more information.
3034 @cindex @code{ms} macros, nested lists
3035 @cindex nested lists [@code{ms}]
3070 @c ---------------------------------------------------------------------
3072 @node Indents in ms, Tabstops in ms, Lists in ms, ms Body Text
3073 @subsubsection Indents
3076 you may need to indent a section of text
3077 while still wrapping and filling.
3079 for an example of nested lists.
3081 @DefmacList {RS, , ms}
3082 @DefmacListEnd {RE, , ms}
3083 These macros begin and end an indented section.
3084 The @code{PI} register controls the amount of indent,
3085 allowing the indented text to line up under hanging
3086 and indented paragraphs.
3089 @xref{ms Displays and Keeps},
3090 for macros to indent and turn off filling.
3092 @c ---------------------------------------------------------------------
3094 @node Tabstops in ms, ms Displays and Keeps, Indents in ms, ms Body Text
3095 @subsubsection Tab Stops
3097 Use the @code{ta} request to define tab stops as needed.
3098 @xref{Tabs and Fields}.
3101 Use this macro to reset the tab stops to the default for @file{ms}
3103 You can redefine the @code{TA} macro to create a different set
3104 of default tab stops.
3107 @c ---------------------------------------------------------------------
3109 @node ms Displays and Keeps, ms Insertions, Tabstops in ms, ms Body Text
3110 @subsubsection Displays and keeps
3111 @cindex @code{ms} macros, displays
3112 @cindex @code{ms} macros, keeps
3113 @cindex keeps [@code{ms}]
3114 @cindex displays [@code{ms}]
3116 Use displays to show text-based examples or figures
3117 (such as code listings).
3119 Displays turn off filling, so lines of code are displayed
3120 as-is without inserting @code{br} requests in between each line.
3121 Displays can be @dfn{kept} on a single page, or allowed
3122 to break across pages.
3124 @DefmacList {DS, @t{L}, ms}
3125 @DefmacItem {LD, , ms}
3126 @DefmacListEnd {DE, , ms}
3127 Left-justified display.
3128 The @samp{.DS L} call generates a page break, if necessary,
3129 to keep the entire display on one page.
3130 The @code{LD} macro allows the display to break across pages.
3131 The @code{DE} macro ends the display.
3134 @DefmacList {DS, @t{I}, ms}
3135 @DefmacItem {ID, , ms}
3136 @DefmacListEnd {DE, , ms}
3137 Indents the display as defined by the @code{DI} register.
3138 The @samp{.DS I} call generates a page break, if necessary,
3139 to keep the entire display on one page.
3140 The @code{ID} macro allows the display to break across pages.
3141 The @code{DE} macro ends the display.
3144 @DefmacList {DS, @t{B}, ms}
3145 @DefmacItem {BD, , ms}
3146 @DefmacListEnd {DE, , ms}
3147 Sets a block-centered display: the entire display is left-justified,
3148 but indented so that the longest line in the display is centered
3150 The @samp{.DS B} call generates a page break, if necessary,
3151 to keep the entire display on one page.
3152 The @code{BD} macro allows the display to break across pages.
3153 The @code{DE} macro ends the display.
3156 @DefmacList {DS, @t{C}, ms}
3157 @DefmacItem {CD, , ms}
3158 @DefmacListEnd {DE, , ms}
3159 Sets a centered display: each line in the display is centered.
3160 The @samp{.DS C} call generates a page break, if necessary,
3161 to keep the entire display on one page.
3162 The @code{CD} macro allows the display to break across pages.
3163 The @code{DE} macro ends the display.
3166 @DefmacList {DS, @t{R}, ms}
3167 @DefmacItem {RD, , ms}
3168 @DefmacListEnd {DE, , ms}
3169 Right-justifies each line in the display.
3170 The @samp{.DS R} call generates a page break, if necessary,
3171 to keep the entire display on one page.
3172 The @code{RD} macro allows the display to break across pages.
3173 The @code{DE} macro ends the display.
3177 On occasion, you may want to @dfn{keep} other text together on a page.
3178 For example, you may want to keep two paragraphs together, or
3179 a paragraph that refers to a table (or list, or other item)
3180 immediately following.
3181 The @file{ms} macros provide the @code{KS} and @code{KE}
3182 macros for this purpose.
3184 @DefmacList {KS, , ms}
3185 @DefmacListEnd {KE, , ms}
3186 The @code{KS} macro begins a block of text to be kept on a
3187 single page, and the @code{KE} macro ends the block.
3190 @DefmacList {KF, , ms}
3191 @DefmacListEnd {KE, , ms}
3192 Specifies a @dfn{floating keep};
3193 if the keep cannot fit on the current page, @code{groff}
3194 holds the contents of the keep and allows text following
3195 the keep (in the source file) to fill in the remainder of
3197 When the page breaks, whether by an explicit @code{bp}
3198 request or by reaching the end of the page, @code{groff}
3199 prints the floating keep at the top of the new page.
3200 This is useful for printing large graphics or tables
3201 that do not need to appear exactly where specified.
3204 You can also use the @code{ne} request to force a page break if
3205 there is not enough vertical space remaining on the page.
3208 Use the following macros to draw a box around a section of
3209 text (such as a display).
3211 @DefmacList {B1, , ms}
3212 @DefmacListEnd {B2, , ms}
3213 Marks the beginning and ending of text that is to have a
3214 box drawn around it.
3215 The @code{B1} macro begins the box; the @code{B2} macro ends it.
3216 Text in the box is automatically placed in a diversion (keep).
3219 @c ---------------------------------------------------------------------
3221 @node ms Insertions, Example multi-page table, ms Displays and Keeps, ms Body Text
3222 @subsubsection Tables, figures, equations, and references
3223 @cindex @code{ms} macros, tables
3224 @cindex @code{ms} macros, figures
3225 @cindex @code{ms} macros, equations
3226 @cindex @code{ms} macros, references
3227 @cindex tables [@code{ms}]
3228 @cindex figures [@code{ms}]
3229 @cindex equations [@code{ms}]
3230 @cindex references [@code{ms}]
3232 The @file{ms} macros support the standard
3233 @code{groff} preprocessors:
3234 @code{tbl}, @code{pic}, @code{eqn}, and @code{refer}.
3239 You mark text meant for preprocessors by enclosing it
3240 in pairs of tags as follows.
3242 @DefmacList {TS, [@code{H}], ms}
3243 @DefmacListEnd {TE, , ms}
3244 Denotes a table, to be processed by the @code{tbl} preprocessor.
3245 The optional argument@w{ }@code{H} to @code{TS} instructs @code{groff}
3246 to create a running header with the information
3247 up to the @code{TH} macro.
3248 @code{groff} prints the header at the beginning of the
3249 table; if the table runs onto another page, @code{groff}
3250 prints the header on the next page as well.
3253 @DefmacList {PS, , ms}
3254 @DefmacListEnd {PE, , ms}
3255 Denotes a graphic, to be processed by the @code{pic} preprocessor.
3256 You can create a @code{pic} file by hand, using the @acronym{AT&T}
3257 @code{pic} manual available on the Web as a reference, or by using
3258 a graphics program such as @code{xfig}.
3261 @DefmacList {EQ, [@Var{align}], ms}
3262 @DefmacListEnd {EN, , ms}
3263 Denotes an equation, to be processed by the @code{eqn} preprocessor.
3264 The optional @var{align} argument can be @code{C}, @code{L}, or@w{
3265 }@code{I} to center (the default), left-justify, or indent the equation.
3268 @DefmacList {[, , ms}
3269 @DefmacListEnd {], , ms}
3270 Denotes a reference, to be processed by the @code{refer} preprocessor.
3271 The @acronym{GNU} @cite{refer(1)} man page provides a comprehensive
3272 reference to the preprocessor and the format of the bibliographic
3277 * Example multi-page table::
3280 @c ---------------------------------------------------------------------
3282 @node Example multi-page table, ms Footnotes, ms Insertions, ms Body Text
3283 @subsubsection An example multi-page table
3284 @cindex example markup, multi-page table [@code{ms}]
3285 @cindex multi-page table, example markup [@code{ms}]
3287 The following is an example of how to set up a
3288 table that may print across two or more pages.
3295 Text ...of heading...
3300 ... the rest of the table follows...
3306 @c ---------------------------------------------------------------------
3308 @node ms Footnotes, , Example multi-page table, ms Body Text
3309 @subsubsection Footnotes
3310 @cindex @code{ms} macros, footnotes
3311 @cindex footnotes [@code{ms}]
3313 The @file{ms} macro package has a flexible footnote system.
3314 You can specify either numbered footnotes or symbolic footnotes
3315 (that is, using a marker such as a dagger symbol).
3318 Specifies the location of a numbered footnote marker in the text.
3321 @DefmacList {FS, , ms}
3322 @DefmacListEnd {FE, , ms}
3323 Specifies the text of the footnote.
3324 The default action is to create a numbered footnote;
3325 you can create a symbolic footnote by specifying
3327 (such as @code{\[dg]} for the dagger glyph)
3328 in the body text and as an argument to the @code{FS} macro,
3329 followed by the text of the footnote
3330 and the @code{FE} macro.
3333 You can control how @code{groff}
3334 prints footnote numbers by changing the value of the
3335 @code{FF} register. @xref{ms Document Control Registers}.
3337 @c ---------------------------------------------------------------------
3339 @node ms Page Layout, Differences from AT&T ms, ms Body Text, ms
3340 @subsection Page layout
3341 @cindex @code{ms} macros, page layout
3342 @cindex page layout [@code{ms}]
3344 The default output from the @file{ms}
3345 macros provides a minimalist page layout:
3346 it prints a single column, with the page number centered at the top
3348 It prints no footers.
3350 You can change the layout by setting
3351 the proper number registers and strings.
3354 * ms Headers and Footers::
3356 * ms Multiple Columns::
3358 * ms Strings and Special Characters::
3361 @c ---------------------------------------------------------------------
3363 @node ms Headers and Footers, ms Margins, ms Page Layout, ms Page Layout
3364 @subsubsection Headers and footers
3365 @cindex @code{ms} macros, headers
3366 @cindex @code{ms} macros, footers
3367 @cindex headers [@code{ms}]
3368 @cindex footers [@code{ms}]
3370 For documents that do not distinguish between odd and even pages,
3371 set the following strings:
3373 @DefstrList {LH, ms}
3374 @DefstrItem {CH, ms}
3375 @DefstrListEnd {RH, ms}
3376 Sets the left, center, and right headers.
3379 @DefstrList {LF, ms}
3380 @DefstrItem {CF, ms}
3381 @DefstrListEnd {RF, ms}
3382 Sets the left, center, and right footers.
3386 For documents that need different information printed in the
3387 even and odd pages, use the following macros:
3389 @DefmacList {OH, @t{'}@Var{left}@t{'}@Var{center}@t{'}@Var{right}@t{'}, ms}
3390 @DefmacItem {EH, @t{'}@Var{left}@t{'}@Var{center}@t{'}@Var{right}@t{'}, ms}
3391 @DefmacItem {OF, @t{'}@Var{left}@t{'}@Var{center}@t{'}@Var{right}@t{'}, ms}
3392 @DefmacListEnd {EF, @t{'}@Var{left}@t{'}@Var{center}@t{'}@Var{right}@t{'}, ms}
3393 The @code{OH} and @code{EH} macros define headers for the odd and even pages;
3394 the @code{OF} and @code{EF} macros define footers for the odd and even pages.
3395 This is more flexible than defining the individual strings.
3397 You can replace the quote (@code{'}) marks with any character not
3398 appearing in the header or footer text.
3401 @c ---------------------------------------------------------------------
3403 @node ms Margins, ms Multiple Columns, ms Headers and Footers, ms Page Layout
3404 @subsubsection Margins
3405 @cindex @code{ms} macros, margins
3407 You control margins using a set of number registers.
3408 @xref{ms Document Control Registers}, for details.
3410 @c ---------------------------------------------------------------------
3412 @node ms Multiple Columns, ms TOC, ms Margins, ms Page Layout
3413 @subsubsection Multiple columns
3414 @cindex @code{ms} macros, multiple columns
3415 @cindex multiple columns [@code{ms}]
3417 The @file{ms} macros can set text in as many columns as will
3418 reasonably fit on the page.
3419 The following macros are available;
3420 all of them force a page break if a multi-column mode is already set.
3421 However, if the current mode is single-column, starting a multi-column
3422 mode does @strong{not} force a page break.
3432 @Defmac {MC, [@Var{width} [@Var{gutter}]], ms}
3434 If you specify no arguments, it is equivalent to the
3436 Otherwise, @var{width} is the width of each column and
3437 @var{gutter} is the space between columns.
3438 The @code{MINGW} number register controls the default gutter width.
3441 @c ---------------------------------------------------------------------
3443 @node ms TOC, ms Strings and Special Characters, ms Multiple Columns, ms Page Layout
3444 @subsubsection Creating a table of contents
3445 @cindex @code{ms} macros, creating table of contents
3446 @cindex table of contents, creating [@code{ms}]
3448 The facilities in the @file{ms} macro package for creating
3449 a table of contents are semi-automated at best.
3450 Assuming that you want the table of contents to consist of
3451 the document's headings, you need to repeat those headings
3452 wrapped in @code{XS} and @code{XE} macros.
3454 @DefmacList {XS, [@Var{page}], ms}
3455 @DefmacItem {XA, [@Var{page}], ms}
3456 @DefmacListEnd {XE, , ms}
3457 These macros define a table of contents
3458 or an individual entry in the table of contents,
3459 depending on their use.
3460 The macros are very simple; they cannot indent a heading based on its level.
3461 The easiest way to work around this is to add tabs
3462 to the table of contents string.
3463 The following is an example:
3485 You can manually create a table of contents
3486 by beginning with the @code{XS} macro for the first entry,
3487 specifying the page number for that entry as the argument to @code{XS}.
3488 Add subsequent entries using the @code{XA} macro,
3489 specifying the page number for that entry as the argument to @code{XA}.
3490 The following is an example:
3497 A Brief History of the Universe
3499 Details of Galactic Formation
3506 @Defmac {TC, [@code{no}], ms}
3507 Prints the table of contents on a new page,
3508 setting the page number to@w{ }@strong{i} (Roman numeral one).
3509 You should usually place this macro at the end of the
3510 file, since @code{groff} is a single-pass formatter and
3511 can only print what has been collected up to the point
3512 that the @code{TC} macro appears.
3514 The optional argument @code{no} suppresses printing
3515 the title specified by the string register @code{TOC}.
3518 @Defmac{PX, [@code{no}], ms}
3519 Prints the table of contents on a new page,
3520 using the current page numbering sequence.
3521 Use this macro to print a manually-generated table of contents
3522 at the beginning of your document.
3524 The optional argument @code{no} suppresses printing
3525 the title specified by the string register @code{TOC}.
3528 The @cite{Groff and Friends HOWTO}
3529 includes a @code{sed} script that automatically inserts
3530 @code{XS} and @code{XE} macro entries after each heading in a document.
3532 Altering the @code{NH} macro to automatically build the table
3533 of contents is perhaps initially more difficult, but would save
3534 a great deal of time in the long run if you use @file{ms} regularly.
3536 @c ---------------------------------------------------------------------
3538 @node ms Strings and Special Characters, , ms TOC, ms Page Layout
3539 @subsubsection Strings and Special Characters
3540 @cindex @code{ms} macros, strings
3541 @cindex @code{ms} macros, special characters
3542 @cindex @code{ms} macros, accent marks
3543 @cindex accent marks [@code{ms}]
3544 @cindex special characters [@code{ms}]
3545 @cindex strings [@code{ms}]
3547 The @file{ms} macros provide the following predefined strings.
3548 You can change the string definitions to help in creating
3549 documents in languages other than English.
3551 @Defstr {REFERENCES, ms}
3552 Contains the string printed at the beginning of the
3553 references (bibliography) page.
3554 The default is @samp{References}.
3557 @Defstr {ABSTRACT, ms}
3558 Contains the string printed at the beginning of the abstract.
3559 The default is @samp{ABSTRACT}.
3563 Contains the string printed at the beginning of the table of contents.
3566 @DefstrList {MONTH1, ms}
3567 @DefstrItem {MONTH2, ms}
3568 @DefstrItem {MONTH3, ms}
3569 @DefstrItem {MONTH4, ms}
3570 @DefstrItem {MONTH5, ms}
3571 @DefstrItem {MONTH6, ms}
3572 @DefstrItem {MONTH7, ms}
3573 @DefstrItem {MONTH8, ms}
3574 @DefstrItem {MONTH9, ms}
3575 @DefstrItem {MONTH10, ms}
3576 @DefstrItem {MONTH11, ms}
3577 @DefstrListEnd {MONTH12, ms}
3578 Prints the full name of the month in dates.
3579 The default is @samp{January}, @samp{February}, etc.
3582 The following special characters are available@footnote{For an
3583 explanation what special characters are see @ref{Special Characters}.}:
3589 @DefstrList {*Q, ms}
3590 @DefstrListEnd {*U, ms}
3591 Prints typographer's quotes in troff,
3592 plain quotes in nroff.
3593 @code{*Q} is the left quote and @code{*U} is the right quote.
3596 Improved accent marks are available in the @file{ms} macros.
3599 Specify this macro at the beginning of your document
3600 to enable extended accent marks and special characters.
3601 This is a Berkeley extension.
3603 To use the accent marks, place them @strong{after}
3604 the character being accented.
3607 The following accent marks are available
3608 after invoking the @code{AM} macro:
3630 @deffn String @t{\*[:]}
3632 @stindex : @r{[}ms@r{]}
3635 @stindex @r{<colon>} @r{[}ms@r{]}
3656 The following are standalone characters
3657 available after invoking the @code{AM} macro:
3660 Upside-down question mark.
3664 Upside-down exclamation point.
3668 German @ss{} ligature.
3696 Lowercase @ae{} ligature.
3700 Uppercase @AE{} ligature.
3703 @c ---------------------------------------------------------------------
3705 @node Differences from AT&T ms, , ms Page Layout, ms
3706 @subsection Differences from @acronym{AT&T} @file{ms}
3707 @cindex @code{ms} macros, differences from @acronym{AT&T}
3708 @cindex @acronym{AT&T} @code{troff}, @code{ms} macro package differences
3710 This section lists the (minor) differences between the
3711 @code{groff -ms} macros and @acronym{AT&T}
3712 @code{troff -ms} macros.
3715 * Missing ms Macros::
3716 * Additional ms Macros::
3719 @c ---------------------------------------------------------------------
3721 @node Missing ms Macros, Additional ms Macros, Differences from AT&T ms, Differences from AT&T ms
3722 @subsubsection @code{troff} macros not appearing in @code{groff}
3724 Macros missing from @code{groff -ms}
3725 are cover page macros specific to Bell Labs.
3726 The macros known to be missing are:
3730 Technical memorandum; a cover sheet style
3733 Internal memorandum; a cover sheet style
3736 Memo for record; a cover sheet style
3739 Memo for file; a cover sheet style
3742 Engineer's notes; a cover sheet style
3745 Computing Science Tech Report; a cover sheet style
3751 Cover sheet information
3757 @c ---------------------------------------------------------------------
3759 @node Additional ms Macros, , Missing ms Macros, Differences from AT&T ms
3760 @subsubsection @code{groff} macros not appearing in @acronym{AT&T} @code{troff}
3762 The @code{groff -ms} macros have a few minor extensions
3763 compared to the @acronym{AT&T} @code{troff -ms} macros.
3766 Improved accent marks.
3767 @xref{ms Strings and Special Characters}, for details.
3770 @Defmac {DS, @t{I}, ms}
3772 The default behavior of @acronym{AT&T} @code{troff -ms}
3773 was to indent; the @code{groff} default prints displays
3774 flush left with the body text.
3778 Print text in @code{constant width} (Courier) font.
3782 Indexing term (printed on standard error).
3783 You can write a script to capture and process an index
3784 generated in this manner.
3788 The following additional number registers
3789 appear in @code{groff -ms}:
3791 @Defmpreg {MINGW, ms}
3792 Specifies a minimum space
3793 between columns (for multi-column output); this takes the
3794 place of the @code{GW} register that was documented but apparently
3795 not implemented in @acronym{AT&T} @code{troff}.
3799 Several new string registers are available as well.
3800 You can change these to handle (for example) the local language.
3801 @xref{ms Strings and Special Characters}, for details.
3804 @c =====================================================================
3806 @node me, mm, ms, Macro Packages
3808 @cindex @code{me} macro package
3810 @c XXX documentation
3811 @c XXX this is a placeholder until we get stuff knocked into shape
3812 See the @file{meintro.me} and @file{meref.me} documents in
3813 groff's @file{doc} directory.
3816 @c =====================================================================
3818 @node mm, , me, Macro Packages
3820 @cindex @code{mm} macro package
3822 @c XXX documentation
3823 @c XXX this is a placeholder until we get stuff knocked into shape
3824 See the @cite{groff_mm(7)} man page (type @command{man groff_mm} at
3828 @c =====================================================================
3829 @c =====================================================================
3831 @node gtroff Reference, Preprocessors, Macro Packages, Top
3832 @chapter @code{gtroff} Reference
3833 @cindex reference, @code{gtroff}
3834 @cindex @code{gtroff}, reference
3836 This chapter covers @strong{all} of the facilities of @code{gtroff}.
3837 Users of macro packages may skip it if not interested in details.
3842 * Input Conventions::
3846 * Embedded Commands::
3848 * Manipulating Filling and Adjusting::
3849 * Manipulating Hyphenation::
3850 * Manipulating Spacing::
3852 * Character Translations::
3853 * Troff and Nroff Mode::
3861 * Conditionals and Loops::
3864 * Drawing Requests::
3868 * Suppressing output::
3871 * Postprocessor Access::
3873 * Gtroff Internals::
3875 * Implementation Differences::
3879 @c =====================================================================
3881 @node Text, Input Conventions, gtroff Reference, gtroff Reference
3883 @cindex text, @code{gtroff} processing
3885 @code{gtroff} input files contain text with control commands
3886 interspersed throughout. But, even without control codes, @code{gtroff}
3887 still does several things with the input text:
3891 filling and adjusting
3894 adding additional space after sentences
3900 inserting implicit line breaks
3904 * Filling and Adjusting::
3908 * Implicit Line Breaks::
3911 @c ---------------------------------------------------------------------
3913 @node Filling and Adjusting, Hyphenation, Text, Text
3914 @subsection Filling and Adjusting
3918 When @code{gtroff} reads text, it collects words from the input and fits
3919 as many of them together on one output line as it can. This is known as
3922 @cindex leading spaces
3923 @cindex spaces, leading and trailing
3924 @cindex extra spaces
3925 @cindex trailing spaces
3926 Once @code{gtroff} has a @dfn{filled} line, it tries to @dfn{adjust}
3927 it. This means it widens the spacing between words until the text
3928 reaches the right margin (in the default adjustment mode). Extra spaces
3929 between words are preserved, but spaces at the end of lines are ignored.
3930 Spaces at the front of a line cause a @dfn{break} (breaks are
3931 explained in @ref{Implicit Line Breaks}).
3933 @xref{Manipulating Filling and Adjusting}.
3935 @c ---------------------------------------------------------------------
3937 @node Hyphenation, Sentences, Filling and Adjusting, Text
3938 @subsection Hyphenation
3941 Since the odds are not great for finding a set of words, for every
3942 output line, which fit nicely on a line without inserting excessive
3943 amounts of space between words, @code{gtroff} hyphenates words so
3944 that it can justify lines without inserting too much space between
3945 words. It uses an internal hyphenation algorithm (a simplified version
3946 of the algorithm used within @TeX{}) to indicate which words can be
3947 hyphenated and how to do so. When a word is hyphenated, the first part
3948 of the word is added to the current filled line being output (with
3949 an attached hyphen), and the other portion is added to the next
3952 @xref{Manipulating Hyphenation}.
3954 @c ---------------------------------------------------------------------
3956 @node Sentences, Tab Stops, Hyphenation, Text
3957 @subsection Sentences
3960 Although it is often debated, some typesetting rules say there should be
3961 different amounts of space after various punctuation marks. For
3962 example, the @cite{Chicago typsetting manual} says that a period at the
3963 end of a sentence should have twice as much space following it as would
3964 a comma or a period as part of an abbreviation.
3966 @c XXX exact citation of Chicago manual
3968 @cindex sentence space
3969 @cindex space between sentences
3970 @cindex french-spacing
3971 @code{gtroff} does this by flagging certain characters (normally
3972 @samp{!}, @samp{?}, and @samp{.}) as @dfn{end-of-sentence} characters.
3973 When @code{gtroff} encounters one of these characters at the end of a
3974 line, it appends a normal space followed by a @dfn{sentence space} in
3975 the formatted output. (This justifies one of the conventions mentioned
3976 in @ref{Input Conventions}.)
3978 @cindex transparent characters
3979 @cindex character, transparent
3980 @cindex @code{dg} glyph, at end of sentence
3981 @cindex @code{rq} glyph, at end of sentence
3982 @cindex @code{"}, at end of sentence
3983 @cindex @code{'}, at end of sentence
3984 @cindex @code{)}, at end of sentence
3985 @cindex @code{]}, at end of sentence
3986 @cindex @code{*}, at end of sentence
3987 In addition, the following characters and symbols are treated
3988 transparently while handling end-of-sentence characters: @samp{"},
3989 @samp{'}, @samp{)}, @samp{]}, @samp{*}, @code{\[dg]}, and @code{\[rq]}.
3991 See the @code{cflags} request in @ref{Using Symbols}, for more details.
3993 @cindex @code{\&}, at end of sentence
3994 To prevent the insertion of extra space after an end-of-sentence
3995 character (at the end of a line), append @code{\&}.
3997 @c ---------------------------------------------------------------------
3999 @node Tab Stops, Implicit Line Breaks, Sentences, Text
4000 @subsection Tab Stops
4002 @cindex stops, tabulator
4003 @cindex tab character
4004 @cindex character, tabulator
4006 @cindex @acronym{EBCDIC} encoding
4007 @cindex encoding, @acronym{EBCDIC}
4008 @code{gtroff} translates @dfn{tabulator characters}, also called
4009 @dfn{tabs} (normally code point @acronym{ASCII} @code{0x09} or
4010 @acronym{EBCDIC} @code{0x05}), in the input into movements to the next
4011 tabulator stop. These tab stops are initially located every half inch
4012 across the page. Using this, simple tables can be made easily.
4013 However, it can often be deceptive as the appearance (and width) of the
4014 text on a terminal and the results from @code{gtroff} can vary greatly.
4016 Also, a possible sticking point is that lines beginning with tab
4017 characters are still filled, again producing unexpected results.
4018 For example, the following input
4020 @multitable {12345678} {12345678} {12345678} {12345678}
4022 @tab 1 @tab 2 @tab 3
4030 @multitable {12345678} {12345678} {12345678} {12345678} {12345678} {12345678} {12345678}
4032 @tab 1 @tab 2 @tab 3 @tab @tab 4 @tab 5
4035 @xref{Tabs and Fields}.
4037 @c ---------------------------------------------------------------------
4039 @node Implicit Line Breaks, , Tab Stops, Text
4040 @subsection Implicit Line Breaks
4041 @cindex implicit line breaks
4042 @cindex implicit breaks of lines
4043 @cindex line, implicit breaks
4044 @cindex break, implicit
4047 An important concept in @code{gtroff} is the @dfn{break}. When a break
4048 occurs, @code{gtroff} outputs the partially filled line
4049 (unjustified), and resumes collecting and filling text on the next output
4055 @cindex blank line macro (@code{blm})
4056 There are several ways to cause a break in @code{gtroff}. A blank
4057 line not only causes a break, but it also outputs a one-line vertical
4058 space (effectively a blank line). Note that this behaviour can be
4059 modified with the blank line macro request @code{blm}.
4060 @xref{Blank Line Traps}.
4064 A line that begins with a space causes a break and the space is
4065 output at the beginning of the next line. Note that this space isn't
4066 adjusted, even in fill mode.
4068 The end of file also causes a break -- otherwise the last line of
4069 the document may vanish!
4071 Certain requests also cause breaks, implicitly or explicitly. This is
4072 discussed in @ref{Manipulating Filling and Adjusting}.
4075 @c =====================================================================
4077 @node Input Conventions, Measurements, Text, gtroff Reference
4078 @section Input Conventions
4079 @cindex input conventions
4080 @cindex conventions for input
4082 Since @code{gtroff} does filling automatically, it is traditional in
4083 @code{groff} not to try and type things in as nicely formatted
4084 paragraphs. These are some conventions commonly used when typing
4089 Break lines after punctuation, particularly at the end of a sentence
4090 and in other logical places. Keep separate phrases on lines by
4091 themselves, as entire phrases are often added or deleted when editing.
4094 Try to keep lines less than 40-60@w{ }characters, to allow space for
4095 inserting more text.
4098 Do not try to do any formatting in a @acronym{WYSIWYG} manner (i.e.,
4099 don't try using spaces to get proper indentation).
4103 @c =====================================================================
4105 @node Measurements, Expressions, Input Conventions, gtroff Reference
4106 @section Measurements
4107 @cindex measurements
4109 @cindex units of measurement
4110 @cindex basic unit (@code{u})
4111 @cindex machine unit (@code{u})
4112 @cindex measurement unit
4113 @cindex @code{u} unit
4114 @cindex unit, @code{u}
4115 @code{gtroff} (like many other programs) requires numeric parameters to
4116 specify various measurements. Most numeric parameters@footnote{those
4117 that specify vertical or horizontal motion or a type size} may have a
4118 @dfn{measurement unit} attached. These units are specified as a single
4119 character which immediately follows the number or expression. Each of
4120 these units are understood, by @code{gtroff}, to be a multiple of its
4121 @dfn{basic unit}. So, whenever a different measurement unit is
4122 specified @code{gtroff} converts this into its @dfn{basic units}. This
4123 basic unit, represented by a @samp{u}, is a device dependent measurement
4124 which is quite small, ranging from 1/75@dmn{th} to 1/72000@dmn{th} of an
4125 inch. The values may be given as fractional numbers; however,
4126 fractional basic units are always rounded to integers.
4128 Some of the measurement units are completely independent of any of the
4129 current settings (e.g.@: type size) of @code{gtroff}.
4133 @cindex inch unit (@code{i})
4134 @cindex @code{i} unit
4135 @cindex unit, @code{i}
4136 Inches. An antiquated measurement unit still in use in certain
4137 backwards countries with incredibly low-cost computer equipment. One
4138 inch is equal to@w{ }2.54@dmn{cm}.
4141 @cindex centimeter unit (@code{c})
4142 @cindex @code{c} unit
4143 @cindex unit, @code{c}
4144 Centimeters. One centimeter is equal to@w{ }0.3937@dmn{in}.
4147 @cindex point unit (@code{p})
4148 @cindex @code{p} unit
4149 @cindex unit, @code{p}
4150 Points. This is a typesetter's measurement used for measure type size.
4151 It is 72@w{ }points to an inch.
4154 @cindex pica unit (@code{P})
4155 @cindex @code{P} unit
4156 @cindex unit, @code{P}
4157 Pica. Another typesetting measurement. 6@w{ }Picas to an inch (and
4158 12@w{ }points to a pica).
4162 @cindex @code{s} unit
4163 @cindex unit, @code{s}
4164 @cindex @code{z} unit
4165 @cindex unit, @code{z}
4166 @xref{Fractional Type Sizes}, for a discussion of these units.
4169 @cindex @code{f} unit
4170 @cindex unit, @code{f}
4171 Fractions. Value is 65536.
4172 @xref{Colors}, for usage.
4175 The other measurements understood by @code{gtroff} depend on
4176 settings currently in effect in @code{gtroff}. These are very useful
4177 for specifying measurements which should look proper with any size of
4182 @cindex em unit (@code{m})
4183 @cindex @code{m} unit
4184 @cindex unit, @code{m}
4185 Ems. This unit is equal to the current font size in points. So called
4186 because it is @emph{approximately} the width of the letter@w{ }@samp{m}
4187 in the current font.
4190 @cindex en unit (@code{n})
4191 @cindex @code{n} unit
4192 @cindex unit, @code{n}
4193 Ens. In @code{groff}, this is half of an em.
4196 @cindex vertical space unit (@code{v})
4197 @cindex space, vertical, unit (@code{v})
4198 @cindex @code{v} unit
4199 @cindex unit, @code{v}
4200 Vertical space. This is equivalent to the current line spacing.
4201 @xref{Sizes}, for more information about this.
4204 @cindex @code{M} unit
4205 @cindex unit, @code{M}
4213 @c ---------------------------------------------------------------------
4215 @node Default Units, , Measurements, Measurements
4216 @subsection Default Units
4217 @cindex default units
4218 @cindex units, default
4220 Many requests take a default unit. While this can be helpful at times,
4221 it can cause strange errors in some expressions. For example, the line
4222 length request expects em units. Here are several attempts to get a
4223 line length of 3.5@w{ }inches and their results:
4229 (7 / 2)u @result{} 0i
4231 7i/2u @result{} 3.5i
4235 Everything is converted to basic units first. In the above example it
4236 is assumed that 1@dmn{i} equals@w{ }240@dmn{u}, and 1@dmn{m} equals@w{
4237 }10@dmn{p} (thus 1@dmn{m} equals@w{ }33@dmn{u}). The value 7@dmn{i}/2
4238 is first handled as 7@dmn{i}/2@dmn{m}, then converted to
4239 1680@dmn{u}/66@dmn{u} which is 25@dmn{u}, and this is approximately
4240 0.1@dmn{i}. As can be seen, a scaling indicator after a closing
4241 parenthesis is simply ignored.
4243 @cindex measurements, specifying safely
4244 Thus, the safest way to specify measurements is to always
4245 attach a scaling indicator. If you want to multiply or divide by a
4246 certain scalar value, use @samp{u} as the unit for that value.
4249 @c =====================================================================
4251 @node Expressions, Identifiers, Measurements, gtroff Reference
4252 @section Expressions
4255 @code{gtroff} has most arithmetic operators common to other languages:
4259 @cindex arithmetic operators
4260 @cindex operators, arithmetic
4266 Arithmetic: @samp{+} (addition), @samp{-} (subtraction), @samp{/}
4267 (division), @samp{*} (multiplication), @samp{%} (modulo).
4269 @code{gtroff} only provides integer arithmetic. The internal type used
4270 for computing results is @samp{int}, which is usually a 32@dmn{bit}
4274 @cindex comparison operators
4275 @cindex operators, comparison
4282 Comparison: @samp{<} (less than), @samp{>} (greater than), @samp{<=}
4283 (less than or equal), @samp{>=} (greater than or equal), @samp{=}
4284 (equal), @samp{==} (the same as @samp{=}).
4287 @cindex logical operators
4288 @cindex operators, logical
4294 @opindex @r{<colon>}
4296 Logical: @samp{&} (logical and), @samp{:} (logical or).
4299 @cindex unary operators
4300 @cindex operators, unary
4304 @cindex @code{if} request, and the @samp{!} operator
4305 @cindex @code{while} request, and the @samp{!} operator
4306 Unary operators: @samp{-} (negating, i.e.@: changing the sign), @samp{+}
4307 (just for completeness; does nothing in expressions), @samp{!} (logical
4308 not; this works only within @code{if} and @code{while} requests). See
4309 below for the use of unary operators in motion requests.
4312 @cindex extremum operators (@code{>?}, @code{<?})
4313 @cindex operators, extremum (@code{>?}, @code{<?})
4316 Extrema: @samp{>?} (maximum), @samp{<?} (minimum).
4323 .nr z (\n[x] >? \n[y])
4327 The register@w{ }@code{z} now contains@w{ }5.
4330 @cindex scaling operator
4331 @cindex operator, scaling
4332 Scaling: @code{(@var{c};@var{e})}. Evaluate@w{ }@var{e} using@w{ }@var{c}
4333 as the default scaling indicator. If @var{c} is missing, ignore scaling
4334 indicators in the evaluation of@w{ }@var{e}.
4338 @cindex order of evaluation in expressions
4339 @cindex expression, order of evaluation
4342 Parentheses may be used as in any other language. However, in
4343 @code{gtroff} they are necessary to ensure order of evaluation.
4344 @code{gtroff} has no operator precedence; expressions are evaluated left
4345 to right. This means that @code{gtroff} evaluates @samp{3+5*4} as if it were
4346 parenthesized like @samp{(3+5)*4}, not as @samp{3+(5*4)}, as might be
4349 @cindex @code{+}, and page motion
4350 @cindex @code{-}, and page motion
4351 @cindex motion operators
4352 @cindex operators, motion
4353 For many requests which cause a motion on the page, the unary operators
4354 @samp{+} and @samp{-} work differently if leading an expression. They
4355 then indicate a motion relative to the current position (down or up,
4358 @cindex @code{|}, and page motion
4359 @cindex absolute position operator (@code{|})
4360 @cindex position, absolute, operator (@code{|})
4361 Similarly, a leading @samp{|} operator indicates an absolute position.
4362 For vertical movements, it specifies the distance from the top of the
4363 page; for horizontal movements, it gives the distance from the beginning
4364 of the @emph{input} line.
4366 @cindex @code{bp} request, using @code{+} and@w{ }@code{-}
4367 @cindex @code{in} request, using @code{+} and@w{ }@code{-}
4368 @cindex @code{ll} request, using @code{+} and@w{ }@code{-}
4369 @cindex @code{lt} request, using @code{+} and@w{ }@code{-}
4370 @cindex @code{nm} request, using @code{+} and@w{ }@code{-}
4371 @cindex @code{nr} request, using @code{+} and@w{ }@code{-}
4372 @cindex @code{pl} request, using @code{+} and@w{ }@code{-}
4373 @cindex @code{pn} request, using @code{+} and@w{ }@code{-}
4374 @cindex @code{po} request, using @code{+} and@w{ }@code{-}
4375 @cindex @code{ps} request, using @code{+} and@w{ }@code{-}
4376 @cindex @code{pvs} request, using @code{+} and@w{ }@code{-}
4377 @cindex @code{rt} request, using @code{+} and@w{ }@code{-}
4378 @cindex @code{ti} request, using @code{+} and@w{ }@code{-}
4379 @cindex @code{\H}, using @code{+} and@w{ }@code{-}
4380 @cindex @code{\R}, using @code{+} and@w{ }@code{-}
4381 @cindex @code{\s}, using @code{+} and@w{ }@code{-}
4382 @samp{+} and @samp{-} are also treated differently by the following
4383 requests and escapes: @code{bp}, @code{in}, @code{ll}, @code{lt},
4384 @code{nm}, @code{nr}, @code{pl}, @code{pn}, @code{po}, @code{ps},
4385 @code{pvs}, @code{rt}, @code{ti}, @code{\H}, @code{\R}, and @code{\s}.
4386 Here, leading plus and minus signs indicate increments and decrements.
4388 @xref{Setting Registers}, for some examples.
4390 @Defesc {\\B, ', anything, '}
4391 @cindex numeric expression, valid
4392 @cindex valid numeric expression
4393 Return@w{ }1 if @var{anything} is a valid numeric expression;
4394 or@w{ }0 if @var{anything} is empty or not a valid numeric expression.
4397 @cindex space characters, in expressions
4398 @cindex expressions, and space characters
4399 Due to the way arguments are parsed, spaces are not allowed in
4400 expressions, unless the entire expression is surrounded by parentheses.
4402 @xref{Request Arguments}, and @ref{Conditionals and Loops}.
4405 @c =====================================================================
4407 @node Identifiers, Embedded Commands, Expressions, gtroff Reference
4408 @section Identifiers
4411 Like any other language, @code{gtroff} has rules for properly formed
4412 @dfn{identifiers}. In @code{gtroff}, an identifier can be made up of
4413 almost any printable character, with the exception of the following
4418 @cindex whitespace characters
4419 @cindex newline character
4420 @cindex character, whitespace
4421 Whitespace characters (spaces, tabs, and newlines).
4424 @cindex character, backspace
4425 @cindex backspace character
4426 @cindex @acronym{EBCDIC} encoding of backspace
4427 Backspace (@acronym{ASCII}@w{ }@code{0x08} or @acronym{EBCDIC}@w{
4428 }@code{0x16}) and character code @code{0x01}.
4431 @cindex invalid input characters
4432 @cindex input characters, invalid
4433 @cindex characters, invalid input
4435 The following input characters are invalid and are ignored if
4436 @code{groff} runs on a machine based on @acronym{ASCII}, causing a
4437 warning message of type @samp{input} (see @ref{Debugging}, for more
4438 details): @code{0x00}, @code{0x0B}, @code{0x0D}-@code{0x1F},
4439 @code{0x80}-@code{0x9F}.
4441 And here are the invalid input characters if @code{groff} runs on an
4442 @acronym{EBCDIC} host: @code{0x00}, @code{0x08}, @code{0x09},
4443 @code{0x0B}, @code{0x0D}-@code{0x14}, @code{0x17}-@code{0x1F},
4444 @code{0x30}-@code{0x3F}.
4446 Currently, some of these reserved codepoints are used internally, thus
4447 making it non-trivial to extend @code{gtroff} to cover Unicode or other
4448 character sets and encodings which use characters of these ranges.
4450 Note that invalid characters are removed before parsing; an
4451 identifier @code{foo}, followed by an invalid character, followed by
4452 @code{bar} is treated as @code{foobar}.
4455 For example, any of the following is valid.
4465 @cindex @code{]}, as part of an identifier
4467 Note that identifiers longer than two characters with a closing bracket
4468 (@samp{]}) in its name can't be accessed with escape sequences which
4469 expect an identifier as a parameter. For example, @samp{\[foo]]}
4470 accesses the glyph @samp{foo}, followed by @samp{]}, whereas
4471 @samp{\C'foo]'} really asks for glyph @samp{foo]}.
4473 @cindex @code{refer}, and macro names starting with @code{[} or @code{]}
4474 @cindex @code{[}, macro names starting with, and @code{refer}
4475 @cindex @code{]}, macro names starting with, and @code{refer}
4476 @cindex macro names, starting with @code{[} or @code{]}, and @code{refer}
4477 To avoid problems with the @code{refer} preprocessor, macro names
4478 should not start with @samp{[} or @samp{]}. Due to backwards
4479 compatibility, everything after @samp{.[} and @samp{.]} is handled as
4480 a special argument to @code{refer}. For example, @samp{.[foo} makes
4481 @code{refer} to start a reference, using @samp{foo} as a parameter.
4483 @Defesc {\\A, ', ident, '}
4484 Test whether an identifier @var{ident} is valid in @code{gtroff}. It
4485 expands to the character@w{ }1 or@w{ }0 according to whether its
4486 argument (usually delimited by quotes) is or is not acceptable as the
4487 name of a string, macro, diversion, number register, environment, or
4488 font. It returns@w{ }0 if no argument is given. This is useful for
4489 looking up user input in some sort of associative table.
4497 @xref{Escapes}, for details on parameter delimiting characters.
4499 Identifiers in @code{gtroff} can be any length, but, in some contexts,
4500 @code{gtroff} needs to be told where identifiers end and text begins
4501 (and in different ways depending on their length):
4507 @cindex @code{(}, starting a two-character identifier
4509 Two characters. Must be prefixed with @samp{(} in some situations.
4511 @cindex @code{[}, starting an identifier
4512 @cindex @code{]}, ending an identifier
4514 Arbitrary length (@code{gtroff} only). Must be bracketed with @samp{[}
4515 and@w{ }@samp{]} in some situations. Any length identifier can be put
4519 @cindex undefined identifiers
4520 @cindex identifiers, undefined
4521 Unlike many other programming languages, undefined identifiers are
4522 silently ignored or expanded to nothing.
4523 When @code{gtroff} finds an undefined identifier, it emits a
4524 warning, doing the following:
4528 If the identifier is a string, macro, or diversion,
4529 @code{gtroff} defines it as empty.
4532 If the identifier is a number register, @code{gtroff}
4533 defines it with a value of@w{ }0.
4536 @xref{Warnings}., @ref{Interpolating Registers}, and @ref{Strings}.
4538 Note that macros, strings, and diversions share the same name space.
4555 As can be seen in the previous example, @code{gtroff} reuses the
4556 identifier @samp{xxx}, changing it from a macro to a diversion.
4557 No warning is emitted! The contents of the first macro definition is
4560 @xref{Interpolating Registers}, and @ref{Strings}.
4563 @c =====================================================================
4565 @node Embedded Commands, Registers, Identifiers, gtroff Reference
4566 @section Embedded Commands
4567 @cindex embedded commands
4568 @cindex commands, embedded
4570 Most documents need more functionality beyond filling, adjusting and
4571 implicit line breaking. In order to gain further functionality,
4572 @code{gtroff} allows commands to be embedded into the text, in two ways.
4574 The first is a @dfn{request} which takes up an entire line, and does
4575 some large-scale operation (e.g.@: break lines, start new pages).
4577 The other is an @dfn{escape} which can be usually embedded anywhere
4578 in the text; most requests can accept it even as an argument.
4579 Escapes generally do more minor operations like sub- and superscripts,
4580 print a symbol, etc.
4588 @c ---------------------------------------------------------------------
4590 @node Requests, Macros, Embedded Commands, Embedded Commands
4591 @subsection Requests
4594 @cindex control character (@code{.})
4595 @cindex character, control (@code{.})
4596 @cindex no-break control character (@code{'})
4597 @cindex character, no-break control (@code{'})
4598 @cindex control character, no-break (@code{'})
4599 A request line begins with a control character, which is either a single
4600 quote (@samp{'}, the @dfn{no-break control character}) or a period
4601 (@samp{.}, the normal @dfn{control character}). These can be changed;
4602 see @ref{Character Translations}, for details. After this there may be
4603 optional tabs or spaces followed by an identifier which is the name of
4604 the request. This may be followed by any number of space-separated
4605 arguments (@emph{no} tabs here).
4607 @cindex structuring source code of documents or macro packages
4608 @cindex documents, structuring the source code
4609 @cindex macro packages, structuring the source code
4610 Since a control character followed by whitespace only is ignored, it
4611 is common practice to use this feature for structuring the source code
4612 of documents or macro packages.
4626 @cindex blank line macro (@code{blm})
4627 Another possibility is to use the blank line macro request @code{blm}
4628 by assigning an empty macro to it.
4633 .blm do-nothing \" activate blank line macro
4644 .blm \" deactivate blank line macro
4647 @xref{Blank Line Traps}.
4649 @cindex zero width space character (@code{\&})
4650 @cindex character, zero width space (@code{\&})
4651 @cindex space character, zero width (@code{\&})
4652 @cindex @code{\&}, escaping control characters
4653 To begin a line with a control character without it being interpreted,
4654 precede it with @code{\&}. This represents a zero width space, which
4655 means it does not affect the output.
4657 In most cases the period is used as a control character. Several
4658 requests cause a break implicitly; using the single quote control
4659 character prevents this.
4662 * Request Arguments::
4665 @node Request Arguments, , Requests, Requests
4666 @subsubsection Request Arguments
4667 @cindex request arguments
4668 @cindex arguments to requests
4670 Arguments to requests (and macros) are processed much like the shell:
4671 The line is split into arguments according to
4672 spaces.@footnote{Plan@w{ }9's @code{troff} implementation also allows
4673 tabs for argument separation -- @code{gtroff} intentionally doesn't
4674 support this.} An argument which is intended to contain spaces can
4675 either be enclosed in double quotes, or have the spaces @dfn{escaped}
4678 Here are a few examples:
4681 .uh The Mouse Problem
4682 .uh "The Mouse Problem"
4683 .uh The\ Mouse\ Problem
4686 @cindex @code{\~}, difference to @code{\@key{SP}}
4687 @cindex @code{\@key{SP}}, difference to @code{\~}
4689 The first line is the @code{uh} macro being called with 3 arguments,
4690 @samp{The}, @samp{Mouse}, and @samp{Problem}. The latter two have the
4691 same effect of calling the @code{uh} macro with one argument, @samp{The
4692 Mouse Problem}.@footnote{The last solution, i.e., using escaped spaces,
4693 is ``classical'' in the sense that it can be found in most @code{troff}
4694 documents. Nevertheless, it is not optimal in all situations, since
4695 @w{@samp{\ }} inserts a fixed-width, non-breaking space character which
4696 can't stretch. @code{gtroff} provides a different command @code{\~} to
4697 insert a stretchable, non-breaking space.}
4699 @cindex @code{"}, in a macro argument
4700 @cindex double quote, in a macro argument
4701 A double quote which isn't preceded by a space doesn't start a macro
4702 argument. If not closing a string, it is printed literally.
4707 .xxx a" "b c" "de"fg"
4711 has the arguments @samp{a"}, @w{@samp{b c}}, @samp{de}, and @samp{fg"}.
4712 Don't rely on this obscure behaviour!
4714 There are two possibilities to get a double quote reliably.
4718 Enclose the whole argument with double quotes and use two consecutive double
4719 quotes to represent a single one. This traditional solution has the
4720 disadvantage that double quotes don't survive argument expansion again if
4721 called in compatibility mode (using the @option{-C} option of @code{groff}):
4725 . tm xx: `\\$1' `\\$2' `\\$3'
4727 . yy "\\$1" "\\$2" "\\$3"
4730 . tm yy: `\\$1' `\\$2' `\\$3'
4732 .xx A "test with ""quotes""" .
4733 @result{} xx: `A' `test with "quotes"' `.'
4734 @result{} yy: `A' `test with ' `quotes""'
4738 If not in compatibility mode, you get the expected result
4741 xx: `A' `test with "quotes"' `.'
4742 yy: `A' `test with "quotes"' `.'
4746 since @code{gtroff} preserves the input level.
4749 Use the double quote glyph @code{\(dq}. This works with and without
4750 compatibility mode enabled since @code{gtroff} doesn't convert @code{\(dq}
4751 back to a double quote input character.
4753 Not that this method won't work with @acronym{UNIX} @code{troff} in general
4754 since the glyph `dq' isn't defined normally.
4757 @cindex @code{ds} request, and double quotes
4758 Double quotes in the @code{ds} request are handled differently.
4759 @xref{Strings}, for more details.
4761 @c ---------------------------------------------------------------------
4763 @node Macros, Escapes, Requests, Embedded Commands
4767 @code{gtroff} has a @dfn{macro} facility for defining a series of lines
4768 which can be invoked by name. They are called in the same manner as
4769 requests -- arguments also may be passed in the same manner.
4771 @xref{Writing Macros}, and @ref{Request Arguments}.
4773 @c ---------------------------------------------------------------------
4775 @node Escapes, , Macros, Embedded Commands
4779 Escapes may occur anywhere in the input to @code{gtroff}. They usually
4780 begin with a backslash and are followed by a single character which
4781 indicates the function to be performed. The escape character can be
4782 changed; see @ref{Character Translations}.
4784 Escape sequences which require an identifier as a parameter accept three
4785 possible syntax forms.
4789 The next single character is the identifier.
4791 @cindex @code{(}, starting a two-character identifier
4793 If this single character is an opening parenthesis, take the following
4794 two characters as the identifier. Note that there is no closing
4795 parenthesis after the identifier.
4797 @cindex @code{[}, starting an identifier
4798 @cindex @code{]}, ending an identifier
4800 If this single character is an opening bracket, take all characters
4801 until a closing bracket as the identifier.
4813 @cindex @code{'}, delimiting arguments
4814 @cindex argument delimiting characters
4815 @cindex characters, argument delimiting
4816 @cindex delimiting characters for arguments
4817 Other escapes may require several arguments and/or some special format.
4818 In such cases the argument is traditionally enclosed in single quotes
4819 (and quotes are always used in this manual for the definitions of escape
4820 sequences). The enclosed text is then processed according to what that
4821 escape expects. Example:
4827 @cindex @code{\o}, possible quote characters
4828 @cindex @code{\b}, possible quote characters
4829 @cindex @code{\X}, possible quote characters
4830 Note that the quote character can be replaced with any other character
4831 which does not occur in the argument (even a newline or a space
4832 character) in the following escapes: @code{\o}, @code{\b}, and
4833 @code{\X}. This makes e.g.
4842 @result{} A caf@'e in Paris
4846 possible, but it is better not to use this feature to avoid confusion.
4848 @cindex @code{\%}, used as delimiter
4849 @cindex @code{\@key{SP}}, used as delimiter
4850 @cindex @code{\|}, used as delimiter
4851 @cindex @code{\^}, used as delimiter
4852 @cindex @code{\@{}, used as delimiter
4853 @cindex @code{\@}}, used as delimiter
4854 @cindex @code{\'}, used as delimiter
4855 @cindex @code{\`}, used as delimiter
4856 @cindex @code{\-}, used as delimiter
4857 @cindex @code{\_}, used as delimiter
4858 @cindex @code{\!}, used as delimiter
4859 @cindex @code{\?}, used as delimiter
4860 @cindex @code{\@@}, used as delimiter
4861 @cindex @code{\)}, used as delimiter
4862 @cindex @code{\/}, used as delimiter
4863 @cindex @code{\,}, used as delimiter
4864 @cindex @code{\&}, used as delimiter
4866 @cindex @code{\:}, used as delimiter
4869 @cindex @code{\@r{<colon>}}, used as delimiter
4871 @cindex @code{\~}, used as delimiter
4872 @cindex @code{\0}, used as delimiter
4873 @cindex @code{\a}, used as delimiter
4874 @cindex @code{\c}, used as delimiter
4875 @cindex @code{\d}, used as delimiter
4876 @cindex @code{\e}, used as delimiter
4877 @cindex @code{\E}, used as delimiter
4878 @cindex @code{\p}, used as delimiter
4879 @cindex @code{\r}, used as delimiter
4880 @cindex @code{\t}, used as delimiter
4881 @cindex @code{\u}, used as delimiter
4882 The following escapes sequences (which are handled similarly to
4883 characters since they don't take a parameter) are also allowed as
4884 delimiters: @code{\%}, @w{@samp{\ }}, @code{\|}, @code{\^}, @code{\@{},
4885 @code{\@}}, @code{\'}, @code{\`}, @code{\-}, @code{\_}, @code{\!},
4886 @code{\?}, @code{\@@}, @code{\)}, @code{\/}, @code{\,}, @code{\&},
4887 @code{\:}, @code{\~}, @code{\0}, @code{\a}, @code{\c}, @code{\d},
4888 @code{\e}, @code{\E}, @code{\p}, @code{\r}, @code{\t}, and @code{\u}.
4889 Again, don't use these if possible.
4891 @cindex @code{\A}, allowed delimiters
4892 @cindex @code{\B}, allowed delimiters
4893 @cindex @code{\Z}, allowed delimiters
4894 @cindex @code{\C}, allowed delimiters
4895 @cindex @code{\w}, allowed delimiters
4896 No newline characters as delimiters are allowed in the following
4897 escapes: @code{\A}, @code{\B}, @code{\Z}, @code{\C}, and @code{\w}.
4899 @cindex @code{\D}, allowed delimiters
4900 @cindex @code{\h}, allowed delimiters
4901 @cindex @code{\H}, allowed delimiters
4902 @cindex @code{\l}, allowed delimiters
4903 @cindex @code{\L}, allowed delimiters
4904 @cindex @code{\N}, allowed delimiters
4905 @cindex @code{\R}, allowed delimiters
4906 @cindex @code{\s}, allowed delimiters
4907 @cindex @code{\S}, allowed delimiters
4908 @cindex @code{\v}, allowed delimiters
4909 @cindex @code{\x}, allowed delimiters
4910 Finally, the escapes @code{\D}, @code{\h}, @code{\H}, @code{\l},
4911 @code{\L}, @code{\N}, @code{\R}, @code{\s}, @code{\S}, @code{\v},
4912 and @code{\x} can't use the following characters as delimiters:
4916 @cindex numbers, and delimiters
4917 @cindex digits, and delimiters
4918 The digits @code{0}-@code{9}.
4921 @cindex operators, as delimiters
4922 @cindex @code{+}, as delimiter
4923 @cindex @code{-}, as delimiter
4924 @cindex @code{/}, as delimiter
4925 @cindex @code{*}, as delimiter
4926 @cindex @code{%}, as delimiter
4927 @cindex @code{<}, as delimiter
4928 @cindex @code{>}, as delimiter
4929 @cindex @code{=}, as delimiter
4930 @cindex @code{&}, as delimiter
4932 @cindex @code{:}, as delimiter
4935 @cindex <colon>, as delimiter
4937 @cindex @code{(}, as delimiter
4938 @cindex @code{)}, as delimiter
4939 @cindex @code{.}, as delimiter
4940 The (single-character) operators @samp{+-/*%<>=&:().}.
4943 @cindex space character
4944 @cindex character, space
4945 @cindex tab character
4946 @cindex character, tab
4947 @cindex newline character
4948 @cindex character, newline
4949 The space, tab, and newline characters.
4952 @cindex @code{\%}, used as delimiter
4954 @cindex @code{\:}, used as delimiter
4957 @cindex @code{\@r{<colon>}}, used as delimiter
4959 @cindex @code{\@{}, used as delimiter
4960 @cindex @code{\@}}, used as delimiter
4961 @cindex @code{\'}, used as delimiter
4962 @cindex @code{\`}, used as delimiter
4963 @cindex @code{\-}, used as delimiter
4964 @cindex @code{\_}, used as delimiter
4965 @cindex @code{\!}, used as delimiter
4966 @cindex @code{\@@}, used as delimiter
4967 @cindex @code{\/}, used as delimiter
4968 @cindex @code{\c}, used as delimiter
4969 @cindex @code{\e}, used as delimiter
4970 @cindex @code{\p}, used as delimiter
4971 All escape sequences except @code{\%}, @code{\:}, @code{\@{}, @code{\@}},
4972 @code{\'}, @code{\`}, @code{\-}, @code{\_}, @code{\!}, @code{\@@},
4973 @code{\/}, @code{\c}, @code{\e}, and @code{\p}.
4976 @cindex printing backslash (@code{\\}, @code{\e}, @code{\E}, @code{\[rs]})
4977 @cindex backslash, printing (@code{\\}, @code{\e}, @code{\E}, @code{\[rs]})
4978 To have a backslash (actually, the current escape character) appear in the
4979 output several escapes are defined: @code{\\}, @code{\e} or @code{\E}.
4980 These are very similar, and only differ with respect to being used in
4981 macros or diversions. @xref{Character Translations}, for an exact
4982 description of those escapes.
4984 @xref{Implementation Differences}, @ref{Copy-in Mode}, and @ref{Diversions},
4985 @ref{Identifiers}, for more information.
4991 @node Comments, , Escapes, Escapes
4992 @subsubsection Comments
4995 Probably one of the most@footnote{Unfortunately, this is a lie. But
4996 hopefully future @code{gtroff} hackers will believe it @code{:-)}}
4997 common forms of escapes is the comment.
5000 Start a comment. Everything to the end of the input line is ignored.
5002 This may sound simple, but it can be tricky to keep the comments from
5003 interfering with the appearance of the final output.
5005 @cindex @code{ds}, @code{ds1} requests, and comments
5006 @cindex @code{as}, @code{as1} requests, and comments
5007 If the escape is to the right of some text or a request, that portion
5008 of the line is ignored, but the space leading up to it is noticed by
5009 @code{gtroff}. This only affects the @code{ds} and @code{as}
5010 request and its variants.
5012 @cindex tabs, before comments
5013 @cindex comments, lining up with tabs
5014 One possibly irritating idiosyncracy is that tabs must not be used to
5015 line up comments. Tabs are not treated as whitespace between the
5016 request and macro arguments.
5018 @cindex undefined request
5019 @cindex request, undefined
5020 A comment on a line by itself is treated as a blank line, because
5021 after eliminating the comment, that is all that remains:
5038 To avoid this, it is common to start the line with @code{.\"} which
5039 causes the line to be treated as an undefined request and thus ignored
5042 @cindex @code{'}, as a comment
5043 Another commenting scheme seen sometimes is three consecutive single
5044 quotes (@code{'''}) at the beginning of a line. This works, but
5045 @code{gtroff} gives a warning about an undefined macro (namely
5046 @code{''}), which is harmless, but irritating.
5050 To avoid all this, @code{gtroff} has a new comment mechanism using the
5051 @code{\#} escape. This escape works the same as @code{\"} except that
5052 the newline is also ignored:
5072 Ignore all input until @code{gtroff} encounters the macro named
5073 @code{.}@var{yy} on a line by itself (or @code{..} if @var{yy} is not
5074 specified). This is useful for commenting out large blocks of text:
5079 This is part of a large block
5080 of text that has been
5081 temporarily(?) commented out.
5083 We can restore it simply by removing
5084 the .ig request and the ".." at the
5087 More text text text...
5094 text text text@dots{} More text text text@dots{}
5098 Note that the commented-out block of text does not
5101 The input is read in copy-mode; auto-incremented registers @emph{are}
5102 affected (@pxref{Auto-increment}).
5106 @c =====================================================================
5108 @node Registers, Manipulating Filling and Adjusting, Embedded Commands, gtroff Reference
5112 Numeric variables in @code{gtroff} are called @dfn{registers}. There
5113 are a number of built-in registers, supplying anything from the date to
5114 details of formatting parameters.
5116 @xref{Identifiers}, for details on register identifiers.
5119 * Setting Registers::
5120 * Interpolating Registers::
5122 * Assigning Formats::
5123 * Built-in Registers::
5126 @c ---------------------------------------------------------------------
5128 @node Setting Registers, Interpolating Registers, Registers, Registers
5129 @subsection Setting Registers
5130 @cindex setting registers (@code{nr}, @code{\R})
5131 @cindex registers, setting (@code{nr}, @code{\R})
5133 Define or set registers using the @code{nr} request or the
5136 @DefreqList {nr, ident value}
5137 @DefescListEnd {\\R, ', ident value, '}
5138 Set number register @var{ident} to @var{value}. If @var{ident}
5139 doesn't exist, @code{gtroff} creates it.
5141 The argument to @code{\R} usually has to be enclosed in quotes.
5142 @xref{Escapes}, for details on parameter delimiting characters.
5144 The @code{\R} escape doesn't produce an input token in @code{gtroff};
5145 with other words, it vanishes completely after @code{gtroff} has
5149 For example, the following two lines are equivalent:
5152 .nr a (((17 + (3 * 4))) % 4)
5153 \R'a (((17 + (3 * 4))) % 4)'
5157 Both @code{nr} and @code{\R} have two additional special forms to
5158 increment or decrement a register.
5160 @DefreqList {nr, ident @t{+}@Var{value}}
5161 @DefreqItem {nr, ident @t{-}@Var{value}}
5162 @DefescItem {\\R, ', ident @t{+}@Var{value}, '}
5163 @DefescListEnd {\\R, ', ident @t{-}@Var{value}, '}
5164 Increment (decrement) register @var{ident} by @var{value}.
5173 @cindex negating register values
5174 To assign the negated value of a register to another register, some care
5175 must be taken to get the desired result:
5189 The surrounding parentheses prevent the interpretation of the minus sign
5190 as a decrementing operator. An alternative is to start the assignment
5206 @cindex removing number register (@code{rr})
5207 @cindex number register, removing (@code{rr})
5208 @cindex register, removing (@code{rr})
5209 Remove number register @var{ident}. If @var{ident} doesn't exist, the
5213 @Defreq {rnn, ident1 ident2}
5214 @cindex renaming number register (@code{rnn})
5215 @cindex number register, renaming (@code{rnn})
5216 @cindex register, renaming (@code{rnn})
5217 Rename number register @var{ident1} to @var{ident2}. If either
5218 @var{ident1} or @var{ident2} doesn't exist, the request is ignored.
5221 @Defreq {aln, ident1 ident2}
5222 @cindex alias, number register, creating (@code{aln})
5223 @cindex creating alias, for number register (@code{aln})
5224 @cindex number register, creating alias (@code{aln})
5225 @cindex register, creating alias (@code{aln})
5226 Create an alias @var{ident1} for a number register @var{ident2}. The
5227 new name and the old name are exactly equivalent. If @var{ident1} is
5228 undefined, a warning of type @samp{reg} is generated, and the request
5229 is ignored. @xref{Debugging}, for information about warnings.
5232 @c ---------------------------------------------------------------------
5234 @node Interpolating Registers, Auto-increment, Setting Registers, Registers
5235 @subsection Interpolating Registers
5236 @cindex interpolating registers (@code{\n})
5237 @cindex registers, interpolating (@code{\n})
5239 Numeric registers can be accessed via the @code{\n} escape.
5241 @DefescList {\\n, , i, }
5242 @DefescItem {\\n, @lparen{}, id, }
5243 @DefescListEnd {\\n, @lbrack{}, ident, @rbrack}
5244 @cindex nested assignments
5245 @cindex assignments, nested
5246 @cindex indirect assignments
5247 @cindex assignments, indirect
5248 Interpolate number register with name @var{ident} (one-character name@w{
5249 }@var{i}, two-character name @var{id}). This means that the value of the
5250 register is expanded in-place while @code{gtroff} is parsing the input line.
5251 Nested assignments (also called indirect assignments) are possible.
5272 @c ---------------------------------------------------------------------
5274 @node Auto-increment, Assigning Formats, Interpolating Registers, Registers
5275 @subsection Auto-increment
5276 @cindex auto-increment
5277 @cindex increment, automatic
5279 Number registers can also be auto-incremented and auto-decremented.
5280 The increment or decrement value can be specified with a third
5281 argument to the @code{nr} request or @code{\R} escape.
5283 @Defreq {nr, ident value incr}
5284 @cindex @code{\R}, difference to @code{nr}
5285 Set number register @var{ident} to @var{value}; the increment for
5286 auto-incrementing is set to @var{incr}. Note that the @code{\R}
5287 escape doesn't support this notation.
5290 To activate auto-incrementing, the escape @code{\n} has a special
5293 @DefescList {\\n, +, i, }
5294 @DefescItem {\\n, -, i, }
5295 @DefescItem {\\n, @lparen{}+, id, }
5296 @DefescItem {\\n, @lparen{}-, id, }
5297 @DefescItem {\\n, +@lparen{}, id, }
5298 @DefescItem {\\n, -@lparen{}, id, }
5299 @DefescItem {\\n, @lbrack{}+, ident, @rbrack{}}
5300 @DefescItem {\\n, @lbrack{}-, ident, @rbrack{}}
5301 @DefescItem {\\n, +@lbrack{}, ident, @rbrack{}}
5302 @DefescListEnd {\\n, -@lbrack{}, ident, @rbrack{}}
5303 Before interpolating, increment or decrement @var{ident}
5304 (one-character name@w{ }@var{i}, two-character name @var{id}) by the
5305 auto-increment value as specified with the @code{nr} request (or the
5306 @code{\R} escape). If no auto-increment value has been specified,
5307 these syntax forms are identical to @code{\n}.
5316 \n+a, \n+a, \n+a, \n+a, \n+a
5318 \n-(xx, \n-(xx, \n-(xx, \n-(xx, \n-(xx
5320 \n+[foo], \n+[foo], \n+[foo], \n+[foo], \n+[foo]
5328 -5, -10, -15, -20, -25
5332 @cindex increment value without changing the register
5333 @cindex value, incrementing without changing the register
5334 To change the increment value without changing the value of a register
5335 (@var{a} in the example), the following can be used:
5341 @c ---------------------------------------------------------------------
5343 @node Assigning Formats, Built-in Registers, Auto-increment, Registers
5344 @subsection Assigning Formats
5345 @cindex assigning formats (@code{af})
5346 @cindex formats, assigning (@code{af})
5348 When a register is used in the text of an input file (as opposed to
5349 part of an expression), it is textually replaced (or interpolated)
5350 with a representation of that number. This output format can be
5351 changed to a variety of formats (numbers, Roman numerals, etc.). This
5352 is done using the @code{af} request.
5354 @Defreq {af, ident format}
5355 Change the output format of a number register. The first argument
5356 @var{ident} is the name of the number register to be changed, and the
5357 second argument @var{format} is the output format. The following
5358 output formats are available:
5362 Decimal arabic numbers. This is the default format: 0, 1, 2, 3,@w{
5366 Decimal numbers with as many digits as specified. So, @samp{00} would
5367 result in printing numbers as 01, 02, 03,@w{ }@enddots{}
5369 In fact, any digit instead of zero will do; @code{gtroff} only counts
5370 how many digits are specified. As a consequence, @code{af}'s default
5371 format @samp{1} could be specified as @samp{0} also (and exactly this is
5372 returned by the @code{\g} escape, see below).
5375 @cindex Roman numerals
5376 @cindex numerals, Roman
5377 Upper-case Roman numerals: 0, I, II, III, IV,@w{ }@enddots{}
5380 Lower-case Roman numerals: 0, i, ii, iii, iv,@w{ }@enddots{}
5383 Upper-case letters: 0, A, B, C, @dots{},@w{ }Z, AA, AB,@w{ }@enddots{}
5386 Lower-case letters: 0, a, b, c, @dots{},@w{ }z, aa, ab,@w{ }@enddots{}
5389 Omitting the number register format causes a warning of type
5390 @samp{missing}. @xref{Debugging}, for more details. Specifying a
5391 nonexistent format causes an error.
5393 The following example produces @samp{10, X, j, 010}:
5397 .af a 1 \" the default format
5407 @cindex Roman numerals, maximum and minimum
5408 @cindex maximum values of Roman numerals
5409 @cindex minimum values of Roman numerals
5410 The largest number representable for the @samp{i} and @samp{I} formats
5411 is 39999 (or @minus{}39999); @acronym{UNIX} @code{troff} uses @samp{z}
5412 and @samp{w} to represent 10000 and 5000 in Roman numerals, and so does
5413 @code{gtroff}. Currently, the correct glyphs of Roman numeral five
5414 thousand and Roman numeral ten thousand (Unicode code points
5415 @code{U+2182} and @code{U+2181}, respectively) are not available.
5417 If @var{ident} doesn't exist, it is created.
5419 @cindex read-only register, changing format
5420 @cindex changing format, and read-only registers
5421 Changing the output format of a read-only register causes an error. It
5422 is necessary to first copy the register's value to a writeable register,
5423 then apply the @code{af} request to this other register.
5426 @DefescList {\\g, , i, }
5427 @DefescItem {\\g, @lparen{}, id, }
5428 @DefescListEnd {\\g, @lbrack{}, ident, @rbrack{}}
5429 @cindex format of register (@code{\g})
5430 @cindex register, format (@code{\g})
5431 Return the current format of the specified register @var{ident}
5432 (one-character name@w{ }@var{i}, two-character name @var{id}). For
5433 example, @samp{\ga} after the previous example would produce the
5434 string @samp{000}. If the register hasn't been defined yet, nothing
5438 @c ---------------------------------------------------------------------
5440 @node Built-in Registers, , Assigning Formats, Registers
5441 @subsection Built-in Registers
5442 @cindex built-in registers
5443 @cindex registers, built-in
5445 The following lists some built-in registers which are not described
5446 elsewhere in this manual. Any register which begins with a @samp{.} is
5447 read-only. A complete listing of all built-in registers can be found in
5448 appendix@w{ }@ref{Register Index}.
5452 @cindex current input file name register (@code{.F})
5453 @cindex input file name, current, register (@code{.F})
5455 This string-valued register returns the current input file name.
5458 @cindex horizontal resolution register (@code{.H})
5459 @cindex resolution, horizontal, register (@code{.H})
5461 Horizontal resolution in basic units.
5464 @cindex vertical resolution register (@code{.V})
5465 @cindex resolution, vertical, register (@code{.V})
5467 Vertical resolution in basic units.
5470 @cindex seconds, current time (@code{seconds})
5471 @cindex time, current, seconds (@code{seconds})
5472 @cindex current time, seconds (@code{seconds})
5474 The number of seconds after the minute, normally in the range@w{ }0
5475 to@w{ }59, but can be up to@w{ }61 to allow for leap seconds. Initialized
5476 at start-up of @code{gtroff}.
5479 @cindex minutes, current time (@code{minutes})
5480 @cindex time, current, minutes (@code{minutes})
5481 @cindex current time, minutes (@code{minutes})
5483 The number of minutes after the hour, in the range@w{ }0 to@w{ }59.
5484 Initialized at start-up of @code{gtroff}.
5487 @cindex hours, current time (@code{hours})
5488 @cindex time, current, hours (@code{hours})
5489 @cindex current time, hours (@code{hours})
5491 The number of hours past midnight, in the range@w{ }0 to@w{ }23.
5492 Initialized at start-up of @code{gtroff}.
5495 @cindex day of the week register (@code{dw})
5496 @cindex date, day of the week register (@code{dw})
5498 Day of the week (1-7).
5501 @cindex day of the month register (@code{dy})
5502 @cindex date, day of the month register (@code{dy})
5504 Day of the month (1-31).
5507 @cindex month of the year register (@code{mo})
5508 @cindex date, month of the year register (@code{mo})
5510 Current month (1-12).
5513 @cindex date, year register (@code{year}, @code{yr})
5514 @cindex year, current, register (@code{year}, @code{yr})
5520 The current year minus@w{ }1900. Unfortunately, the documentation of
5521 @acronym{UNIX} Version@w{ }7's @code{troff} had a year@w{ }2000 bug: It
5522 incorrectly claimed that @code{yr} contains the last two digits of the
5523 year. That claim has never been true of either @acronym{AT&T}
5524 @code{troff} or GNU @code{troff}. Old @code{troff} input that looks
5528 '\" The following line stopped working after 1999
5529 This document was formatted in 19\n(yr.
5533 can be corrected as follows:
5536 This document was formatted in \n[year].
5540 or, to be portable to older @code{troff} versions, as follows:
5544 This document was formatted in \n(y4.
5551 @cindex input line number register (@code{.c}, @code{c.})
5552 @cindex line number, input, register (@code{.c}, @code{c.})
5553 The current @emph{input} line number. Register @samp{.c} is read-only,
5554 whereas @samp{c.} (a @code{gtroff} extension) is writable also,
5555 affecting both @samp{.c} and @samp{c.}.
5559 @cindex output line number register (@code{ln})
5560 @cindex line number, output, register (@code{ln})
5561 The current @emph{output} line number after a call to the @code{nm}
5562 request to activate line numbering.
5564 @xref{Miscellaneous}, for more information about line numbering.
5568 @cindex major version number register (@code{.x})
5569 @cindex version number, major, register (@code{.x})
5570 The major version number. For example, if the version number is@w{
5571 }1.03 then @code{.x} contains@w{ }@samp{1}.
5575 @cindex minor version number register (@code{.y})
5576 @cindex version number, minor, register (@code{.y})
5577 The minor version number. For example, if the version number is@w{
5578 }1.03 then @code{.y} contains@w{ }@samp{03}.
5582 @cindex revision number register (@code{.Y})
5583 The revision number of @code{groff}.
5587 @cindex process ID of @code{gtroff} register (@code{$$})
5588 @cindex @code{gtroff}, process ID register (@code{$$})
5589 The process ID of @code{gtroff}.
5593 @cindex @code{gtroff}, identification register (@code{.g})
5594 @cindex GNU-specific register (@code{.g})
5595 Always@w{ }1. Macros should use this to determine whether they are
5596 running under GNU @code{troff}.
5600 @cindex @acronym{ASCII} approximation output register (@code{.A})
5601 If the command line option @option{-a} is used to produce an
5602 @acronym{ASCII} approximation of the output, this is set to@w{ }1, zero
5603 otherwise. @xref{Groff Options}.
5607 This register is set to@w{ }1 (and to@w{ }0 otherwise) if the current
5608 page is actually being printed, i.e., if the @option{-o} option is being
5609 used to only print selected pages. @xref{Groff Options}, for more
5614 If @code{gtroff} is called with the @option{-T} command line option, the
5615 number register @code{.T} is set to@w{ }1, and zero otherwise.
5616 @xref{Groff Options}.
5619 @cindex output device name string register (@code{.T})
5620 Additionally, @code{gtroff} predefines a single read-write string
5621 register @code{.T} which contains the current output device (for
5622 example, @samp{latin1} or @samp{ps}).
5626 @c =====================================================================
5628 @node Manipulating Filling and Adjusting, Manipulating Hyphenation, Registers, gtroff Reference
5629 @section Manipulating Filling and Adjusting
5630 @cindex manipulating filling and adjusting
5631 @cindex filling and adjusting, manipulating
5632 @cindex adjusting and filling, manipulating
5633 @cindex justifying text
5634 @cindex text, justifying
5638 @cindex @code{bp} request, causing implicit linebreak
5639 @cindex @code{ce} request, causing implicit linebreak
5640 @cindex @code{cf} request, causing implicit linebreak
5641 @cindex @code{fi} request, causing implicit linebreak
5642 @cindex @code{fl} request, causing implicit linebreak
5643 @cindex @code{in} request, causing implicit linebreak
5644 @cindex @code{nf} request, causing implicit linebreak
5645 @cindex @code{rj} request, causing implicit linebreak
5646 @cindex @code{sp} request, causing implicit linebreak
5647 @cindex @code{ti} request, causing implicit linebreak
5648 @cindex @code{trf} request, causing implicit linebreak
5649 Various ways of causing @dfn{breaks} were given in @ref{Implicit Line
5650 Breaks}. The @code{br} request likewise causes a break. Several
5651 other requests also cause breaks, but implicitly. These are
5652 @code{bp}, @code{ce}, @code{cf}, @code{fi}, @code{fl}, @code{in},
5653 @code{nf}, @code{rj}, @code{sp}, @code{ti}, and @code{trf}.
5656 Break the current line, i.e., the input collected so far is emitted
5659 If the no-break control character is used, @code{gtroff} suppresses
5670 Initially, @code{gtroff} fills and adjusts text to both margins.
5671 Filling can be disabled via the @code{nf} request and re-enabled with
5672 the @code{fi} request.
5676 @cindex fill mode (@code{fi})
5677 @cindex mode, fill (@code{fi})
5678 Activate fill mode (which is the default). This request implicitly
5679 enables adjusting; it also inserts a break in the text currently being
5680 filled. The read-only number register @code{.u} is set to@w{ }1.
5682 The fill mode status is associated with the current environment
5683 (@pxref{Environments}).
5685 See @ref{Line Control}, for interaction with the @code{\c} escape.
5689 @cindex no-fill mode (@code{nf})
5690 @cindex mode, no-fill (@code{nf})
5691 Activate no-fill mode. Input lines are output as-is, retaining line
5692 breaks and ignoring the current line length. This command implicitly
5693 disables adjusting; it also causes a break. The number register
5694 @code{.u} is set to@w{ }0.
5696 The fill mode status is associated with the current environment
5697 (@pxref{Environments}).
5699 See @ref{Line Control}, for interaction with the @code{\c} escape.
5702 @DefreqList {ad, [@Var{mode}]}
5706 Activation and deactivation of adjusting is done implicitly with
5707 calls to the @code{fi} or @code{nf} requests.
5709 @var{mode} can have one of the following values:
5713 @cindex ragged-right
5714 Adjust text to the left margin. This produces what is traditionally
5715 called ragged-right text.
5719 Adjust text to the right margin, producing ragged-left text.
5722 @cindex centered text
5723 @cindex @code{ce} request, difference to @samp{.ad@w{ }c}
5724 Center filled text. This is different to the @code{ce} request which
5725 only centers text without filling.
5729 Justify to both margins. This is the default used by @code{gtroff}.
5732 With no argument, @code{gtroff} adjusts lines in the same way it did
5733 before adjusting was deactivated (with a call to @code{na}, for
5744 .ad \" back to centering
5748 @cindex adjustment mode register (@code{.j})
5749 The current adjustment mode is available in the read-only number
5750 register @code{.j}; it can be stored and subsequently used to set
5753 The adjustment mode status is associated with the current environment
5754 (@pxref{Environments}).
5758 Disable adjusting. This request won't change the current adjustment
5759 mode: A subsequent call to @code{ad} uses the previous adjustment
5762 The adjustment mode status is associated with the current environment
5763 (@pxref{Environments}).
5767 @DefescListEnd {\\p, , , }
5768 Adjust the current line and cause a break.
5770 In most cases this produces very ugly results since @code{gtroff}
5771 doesn't have a sophisticated paragraph building algorithm (as @TeX{}
5772 have, for example); instead, @code{gtroff} fills and adjusts a paragraph
5776 This is an uninteresting sentence.
5777 This is an uninteresting sentence.\p
5778 This is an uninteresting sentence.
5785 This is an uninteresting sentence. This is an
5786 uninteresting sentence.
5787 This is an uninteresting sentence.
5791 @DefreqList {ss, word_space_size [@Var{sentence_space_size}]}
5793 @DefregListEnd {.sss}
5794 @cindex word space size register (@code{.ss})
5795 @cindex size of word space register (@code{.ss})
5796 @cindex space between words register (@code{.ss})
5797 @cindex sentence space size register (@code{.sss})
5798 @cindex size of sentence space register (@code{.sss})
5799 @cindex space between sentences register (@code{.sss})
5800 Change the minimum size of a space between filled words. It takes its
5801 units as one twelfth of the space width parameter for the current
5802 font. Initially both the @var{word_space_size} and
5803 @var{sentence_space_size} are@w{ }12.
5807 If two arguments are given to the @code{ss} request, the second
5808 argument sets the sentence space size. If the second argument is not
5809 given, sentence space size is set to @var{word_space_size}. The
5810 sentence space size is used in two circumstances: If the end of a
5811 sentence occurs at the end of a line in fill mode, then both an
5812 inter-word space and a sentence space are added; if two spaces follow
5813 the end of a sentence in the middle of a line, then the second space
5814 is a sentence space. If a second argument is never given to the
5815 @code{ss} request, the behaviour of @acronym{UNIX} @code{troff} is the
5816 same as that exhibited by GNU @code{troff}. In GNU @code{troff}, as
5817 in @acronym{UNIX} @code{troff}, a sentence should always be followed
5818 by either a newline or two spaces.
5820 The read-only number registers @code{.ss} and @code{.sss} hold the
5821 values of the parameters set by the first and second arguments of the
5824 The word space and sentence space values are associated with the current
5825 environment (@pxref{Environments}).
5827 Contrary to @acronym{AT&T} @code{troff}, this request is @emph{not}
5828 ignored if a TTY output device is used; the given values are then
5829 rounded down to a multiple of@w{ }12 (@pxref{Implementation Differences}).
5831 The request is ignored if there is no parameter.
5834 @DefreqList {ce, [@Var{nnn}]}
5835 @DefregListEnd {.ce}
5836 @cindex centering lines (@code{ce})
5837 @cindex lines, centering (@code{ce})
5838 Center text. While the @w{@samp{.ad c}} request also centers text,
5839 it fills the text as well. @code{ce} does not fill the
5840 text it affects. This request causes a break. The number of lines
5841 still to be centered is associated with the current environment
5842 (@pxref{Environments}).
5844 The following example demonstrates the differences.
5850 This is a small text fragment which shows the differences
5851 between the `.ce' and the `.ad c' request.
5855 This is a small text fragment which shows the differences
5856 between the `.ce' and the `.ad c' request.
5860 And here the result:
5863 This is a small text fragment which
5864 shows the differences
5865 between the `.ce' and the `.ad c' request.
5867 This is a small text fragment which
5868 shows the differences between the `.ce'
5869 and the `.ad c' request.
5872 With no arguments, @code{ce} centers the next line of text. @var{nnn}
5873 specifies the number of lines to be centered. If the argument is zero
5874 or negative, centering is disabled.
5876 The basic length for centering text is the line length (as set with the
5877 @code{ll} request) minus the indentation (as set with the @code{in}
5878 request). Temporary indentation is ignored.
5880 As can be seen in the previous example, it is a common idiom to turn
5881 on centering for a large number of lines, and to turn off centering
5882 after text to be centered. This is useful for any request which takes
5883 a number of lines as an argument.
5885 The @code{.ce} read-only number register contains the number of lines
5886 remaining to be centered, as set by the @code{ce} request.
5889 @DefreqList {rj, [@Var{nnn}]}
5890 @DefregListEnd {.rj}
5891 @cindex justifying text (@code{rj})
5892 @cindex text, justifying (@code{rj})
5893 @cindex right-justifying (@code{rj})
5894 Justify unfilled text to the right margin. Arguments are identical to
5895 the @code{ce} request. The @code{.rj} read-only number register is
5896 the number of lines to be right-justified as set by the @code{rj}
5897 request. This request causes a break. The number of lines still to be
5898 right-justified is associated with the current environment
5899 (@pxref{Environments}).
5903 @c =====================================================================
5905 @node Manipulating Hyphenation, Manipulating Spacing, Manipulating Filling and Adjusting, gtroff Reference
5906 @section Manipulating Hyphenation
5907 @cindex manipulating hyphenation
5908 @cindex hyphenation, manipulating
5910 As discussed in @ref{Hyphenation}, @code{gtroff} hyphenates words.
5911 There are a number of ways to influence hyphenation.
5913 @DefreqList {hy, [@Var{mode}]}
5914 @DefregListEnd {.hy}
5915 Enable hyphenation. The request has an optional numeric argument,
5916 @var{mode}, to restrict hyphenation if necessary:
5920 The default argument if @var{mode} is omitted. Hyphenate without
5921 restrictions. This is also the start-up value of @code{gtroff}.
5924 Do not hyphenate the last word on a page or column.
5927 Do not hyphenate the last two characters of a word.
5930 Do not hyphenate the first two characters of a word.
5933 Values in the previous table are additive. For example, the value@w{
5934 }12 causes @code{gtroff} to neither hyphenate the last two nor the first
5935 two characters of a word.
5937 @cindex hyphenation restrictions register (@code{.hy})
5938 The current hyphenation restrictions can be found in the read-only
5939 number register @samp{.hy}.
5941 The hyphenation mode is associated with the current environment
5942 (@pxref{Environments}).
5946 Disable hyphenation (i.e., set the hyphenation mode to zero). Note
5947 that the hyphenation mode of the last call to @code{hy} is not
5950 The hyphenation mode is associated with the current environment
5951 (@pxref{Environments}).
5954 @DefreqList {hlm, [@Var{nnn}]}
5956 @DefregListEnd {.hlc}
5957 @cindex explicit hyphen (@code{\%})
5958 @cindex hyphen, explicit (@code{\%})
5959 @cindex consecutive hyphenated lines (@code{hlm})
5960 @cindex lines, consecutive hyphenated (@code{hlm})
5961 @cindex hyphenated lines, consecutive (@code{hlm})
5962 Set the maximum number of consecutive hyphenated lines to @var{nnn}.
5963 If this number is negative, there is no maximum. The default value
5964 is@w{ }@minus{}1 if @var{nnn} is omitted. This value is associated
5965 with the current environment (@pxref{Environments}). Only lines
5966 output from a given environment count towards the maximum associated
5967 with that environment. Hyphens resulting from @code{\%} are counted;
5968 explicit hyphens are not.
5970 The current setting of @code{hlm} is available in the @code{.hlm}
5971 read-only number register. Also the number of immediately preceding
5972 consecutive hyphenated lines are available in the read-only number
5973 register @samp{.hlc}.
5976 @Defreq {hw, word1 word2 @dots{}}
5977 Define how @var{word1}, @var{word2}, etc.@: are to be hyphenated. The
5978 words must be given with hyphens at the hyphenation points. For
5986 Besides the space character, any character whose hyphenation code value
5987 is zero can be used to separate the arguments of @code{hw} (see the
5988 documentation for the @code{hcode} request below for more information).
5989 In addition, this request can be used more than once.
5991 Hyphenation exceptions specified with the @code{hw} request are
5992 associated with the current hyphenation language; it causes an error
5993 if there is no current hyphenation language.
5995 This request is ignored if there is no parameter.
5997 In old versions of @code{troff} there was a limited amount of space to
5998 store such information; fortunately, with @code{gtroff}, this is no
5999 longer a restriction.
6002 @DefescList {\\%, , , }
6003 @deffnx Escape @t{\:}
6008 @esindex @r{<colon>}
6010 @cindex hyphenation character (@code{\%})
6011 @cindex character, hyphenation (@code{\%})
6012 @cindex disabling hyphenation (@code{\%})
6013 @cindex hyphenation, disabling (@code{\%})
6014 To tell @code{gtroff} how to hyphenate words on the fly, use the
6015 @code{\%} escape, also known as the @dfn{hyphenation character}.
6016 Preceding a word with this character prevents it from being
6017 hyphenated; putting it inside a word indicates to @code{gtroff} that
6018 the word may be hyphenated at that point. Note that this mechanism
6019 only affects that one occurrence of the word; to change the
6020 hyphenation of a word for the entire document, use the @code{hw}
6023 The @code{\:} escape inserts a zero-width break point
6024 (that is, the word breaks but without adding a hyphen).
6027 ... check the /var/log/\:httpd/\:access_log file ...
6030 @cindex @code{\X}, followed by @code{\%}
6031 @cindex @code{\Y}, followed by @code{\%}
6032 @cindex @code{\%}, following @code{\X} or @code{\Y}
6033 Note that @code{\X} and @code{\Y} start a word, that is, the @code{\%}
6034 escape in (say) @w{@samp{ \X'...'\%foobar}} and
6035 @w{@samp{ \Y'...'\%foobar}} no longer prevents hyphenation but inserts
6036 a hyphenation point at the beginning of @samp{foobar}; most likely
6037 this isn't what you want to do.
6040 @Defreq {hc, [@Var{char}]}
6041 Change the hyphenation character to @var{char}. This character then
6042 works the same as the @code{\%} escape, and thus, no longer appears in
6043 the output. Without an argument, @code{hc} resets the hyphenation
6044 character to be @code{\%} (the default) only.
6046 The hyphenation character is associated with the current environment
6047 (@pxref{Environments}).
6050 @DefreqList {hpf, pattern_file}
6051 @DefreqItem {hpfa, pattern_file}
6052 @DefreqListEnd {hpfcode, a b [c d @dots{}]}
6053 @cindex hyphenation patterns (@code{hpf})
6054 @cindex patterns for hyphenation (@code{hpf})
6055 Read in a file of hyphenation patterns. This file is searched for in
6056 the same way as @file{@var{name}.tmac} (or @file{tmac.@var{name}}) is
6057 searched for if the @option{-m@var{name}} option is specified.
6059 It should have the same format as (simple) @TeX{} patterns files.
6060 More specifically, the following scanning rules are implemented.
6064 A percent sign starts a comment (up to the end of the line)
6065 even if preceded by a backslash.
6068 No support for `digraphs' like @code{\$}.
6071 @code{^^@var{xx}} (@var{x} is 0-9 or a-f) and @code{^^@var{x}} (character
6072 code of @var{x} in the range 0-127) are recognized; other use of @code{^}
6079 @code{hpf} checks for the expression @code{\patterns@{@dots{}@}}
6080 (possibly with whitespace before and after the braces).
6081 Everything between the braces is taken as hyphenation patterns.
6082 Consequently, @code{@{} and @code{@}} are not allowed in patterns.
6085 Similarly, @code{\hyphenation@{@dots{}@}} gives a list of hyphenation
6089 @code{\endinput} is recognized also.
6092 For backwards compatibility, if @code{\patterns} is missing,
6093 the whole file is treated as a list of hyphenation patterns
6094 (only recognizing the @code{%} character as the start of a comment).
6097 If no @code{hpf} request is specified (either in the document or in a
6098 macro package), @code{gtroff} won't hyphenate at all.
6100 The @code{hpfa} request appends a file of patterns to the current list.
6102 The @code{hpfcode} request defines mapping values for character codes in
6103 hyphenation patterns. @code{hpf} or @code{hpfa} then apply the mapping
6104 (after reading the patterns) before replacing or appending them to
6105 the current list of patterns. Its arguments are pairs of character codes
6106 -- integers from 0 to@w{ }255. The request maps character code@w{ }@var{a}
6107 to code@w{ }@var{b}, code@w{ }@var{c} to code@w{ }@var{d}, and so on. You
6108 can use character codes which would be invalid otherwise.
6113 The set of hyphenation patterns is associated with the current language
6114 set by the @code{hla} request. The @code{hpf} request is usually
6115 invoked by the @file{troffrc} or @file{troffrc-end} file; by default,
6116 @file{troffrc} loads hyphenation patterns for American English (in file
6119 A second call to @code{hpf} (for the same language) will replace the
6120 hyphenation patterns with the new ones.
6122 Invoking @code{hpf} causes an error if there is no current hyphenation
6126 @Defreq {hcode, c1 code1 c2 code2 @dots{}}
6127 @cindex hyphenation code (@code{hcode})
6128 @cindex code, hyphenation (@code{hcode})
6129 Set the hyphenation code of character @var{c1} to @var{code1}, that of
6130 @var{c2} to @var{code2}, etc. A hyphenation code must be a single
6131 input character (not a special character) other than a digit or a
6132 space. Initially each lower-case letter (@samp{a}-@samp{z}) has its
6133 hyphenation code set to itself, and each upper-case letter
6134 (@samp{A}-@samp{Z}) has a hyphenation code which is the lower-case
6137 This request is ignored if it has no parameter.
6140 @DefreqList {hym, [@Var{length}]}
6141 @DefregListEnd {.hym}
6142 @cindex hyphenation margin (@code{hym})
6143 @cindex margin for hyphenation (@code{hym})
6144 @cindex @code{ad} request, and hyphenation margin
6145 Set the (right) hyphenation margin to @var{length}. If the current
6146 adjustment mode is not @samp{b} or @samp{n}, the line is not
6147 hyphenated if it is shorter than @var{length}. Without an argument,
6148 the hyphenation margin is reset to its default value, which is@w{ }0.
6149 The default scaling indicator for this request is @samp{m}. The
6150 hyphenation margin is associated with the current environment
6151 (@pxref{Environments}).
6153 A negative argument resets the hyphenation margin to zero, emitting
6154 a warning of type @samp{range}.
6156 @cindex hyphenation margin register (@code{.hym})
6157 The current hyphenation margin is available in the @code{.hym} read-only
6161 @DefreqList {hys, [@Var{hyphenation_space}]}
6162 @DefregListEnd {.hys}
6163 @cindex hyphenation space (@code{hys})
6164 @cindex @code{ad} request, and hyphenation space
6165 Set the hyphenation space to @var{hyphenation_space}. If the current
6166 adjustment mode is @samp{b} or @samp{n}, don't hyphenate the line
6167 if it can be justified by adding no more than @var{hyphenation_space}
6168 extra space to each word space. Without argument, the hyphenation
6169 space is set to its default value, which is@w{ }0. The default
6170 scaling indicator for this request is @samp{m}. The hyphenation
6171 space is associated with the current environment
6172 (@pxref{Environments}).
6174 A negative argument resets the hyphenation space to zero, emitting a
6175 warning of type @samp{range}.
6177 @cindex hyphenation space register (@code{.hys})
6178 The current hyphenation space is available in the @code{.hys} read-only
6182 @Defreq {shc, [@Var{glyph}]}
6183 @cindex soft hyphen character, setting (@code{shc})
6184 @cindex character, soft hyphen, setting (@code{shc})
6185 @cindex glyph, soft hyphen (@code{hy})
6186 @cindex soft hyphen glyph (@code{hy})
6187 @cindex @code{char} request, and soft hyphen character
6188 @cindex @code{tr} request, and soft hyphen character
6189 Set the @dfn{soft hyphen character} to @var{glyph}.@footnote{@dfn{Soft
6190 hyphen character} is a misnomer since it is an output glyph.} If the
6191 argument is omitted, the soft hyphen character is set to the default
6192 glyph @code{\(hy} (this is the start-up value of @code{gtroff} also).
6193 The soft hyphen character is the glyph that is inserted when a word is
6194 hyphenated at a line break. If the soft hyphen character does not
6195 exist in the font of the character immediately preceding a potential
6196 break point, then the line is not broken at that point. Neither
6197 definitions (specified with the @code{char} request) nor translations
6198 (specified with the @code{tr} request) are considered when finding the
6199 soft hyphen character.
6202 @DefreqList {hla, language}
6203 @DefregListEnd {.hla}
6204 @cindex @code{hpf} request, and hyphenation language
6205 @cindex @code{hw} request, and hyphenation language
6208 Set the current hyphenation language to the string @var{language}.
6209 Hyphenation exceptions specified with the @code{hw} request and
6210 hyphenation patterns specified with the @code{hpf} and @code{hpfa}
6211 requests are both associated with the current hyphenation language.
6212 The @code{hla} request is usually invoked by the @file{troffrc} or the
6213 @file{troffrc-end} files; @file{troffrc} sets the default language to
6216 @cindex hyphenation language register (@code{.hla})
6217 The current hyphenation language is available as a string in the
6218 read-only number register @samp{.hla}.
6221 .ds curr_language \n[.hla]
6228 @c =====================================================================
6230 @node Manipulating Spacing, Tabs and Fields, Manipulating Hyphenation, gtroff Reference
6231 @section Manipulating Spacing
6232 @cindex manipulating spacing
6233 @cindex spacing, manipulating
6235 @Defreq {sp, [@Var{distance}]}
6236 Space downwards @var{distance}. With no argument it advances 1@w{
6237 }line. A negative argument causes @code{gtroff} to move up the page
6238 the specified distance. If the argument is preceded by a @samp{|}
6239 then @code{gtroff} moves that distance from the top of the page. This
6240 request causes a line break. The default scaling indicator is @samp{v}.
6243 @DefreqList {ls, [@Var{nnn}]}
6245 @cindex double-spacing (@code{ls})
6246 Output @w{@var{nnn}@minus{}1} blank lines after each line of text.
6247 With no argument, @code{gtroff} uses the previous value before the
6248 last @code{ls} call.
6251 .ls 2 \" This causes double-spaced output
6252 .ls 3 \" This causes triple-spaced output
6253 .ls \" Again double-spaced
6256 The line spacing is associated with the current environment
6257 (@pxref{Environments}).
6259 @cindex line spacing register (@code{.L})
6260 The read-only number register @code{.L} contains the current line
6264 @xref{Changing Type Sizes}, for the requests @code{vs} and @code{pvs}
6265 as alternatives to @code{ls}.
6267 @DefescList {\\x, ', spacing, '}
6269 Sometimes, extra vertical spacing is only needed occasionally, e.g.@:
6270 to allow space for a tall construct (like an equation). The @code{\x}
6271 escape does this. The escape is given a numerical argument, usually
6272 enclosed in quotes (like @samp{\x'3p'}); the default scaling indicator
6273 is @samp{v}. If this number is positive extra vertical space is
6274 inserted below the current line. A negative number adds space above.
6275 If this escape is used multiple times on the same line, the maximum of
6278 @xref{Escapes}, for details on parameter delimiting characters.
6280 @cindex extra post-vertical line space register (@code{.a})
6281 The @code{.a} read-only number register contains the most recent
6282 (nonnegative) extra vertical line space.
6284 Using @code{\x} can be necessary in combination with the @code{\b}
6285 escape, as the following example shows.
6288 This is a test with the \[rs]b escape.
6290 This is a test with the \[rs]b escape.
6292 This is a test with \b'xyz'\x'-1m'\x'1m'.
6294 This is a test with the \[rs]b escape.
6296 This is a test with the \[rs]b escape.
6303 This is a test with the \b escape.
6304 This is a test with the \b escape.
6306 This is a test with y.
6308 This is a test with the \b escape.
6309 This is a test with the \b escape.
6315 @DefregListEnd {.ns}
6316 @cindex @code{sp} request, and no-space mode
6317 @cindex no-space mode (@code{ns})
6318 @cindex mode, no-space (@code{ns})
6319 @cindex blank lines, disabling
6320 @cindex lines, blank, disabling
6321 Enable @dfn{no-space mode}. In this mode, spacing (either via
6322 @code{sp} or via blank lines) is disabled. The @code{bp} request to
6323 advance to the next page is also disabled, except if it is accompanied
6324 by a page number (see @ref{Page Control}, for more information). This
6325 mode ends when actual text is output or the @code{rs} request is
6326 encountered which ends no-space mode. The read-only number register
6327 @code{.ns} is set to@w{ }1 as long as no-space mode is active.
6329 This request is useful for macros that conditionally
6330 insert vertical space before the text starts
6331 (for example, a paragraph macro could insert some space
6332 except when it is the first paragraph after a section header).
6336 @c =====================================================================
6338 @node Tabs and Fields, Character Translations, Manipulating Spacing, gtroff Reference
6339 @section Tabs and Fields
6340 @cindex tabs, and fields
6341 @cindex fields, and tabs
6343 @cindex @acronym{EBCDIC} encoding of a tab
6344 A tab character (@acronym{ASCII} char@w{ }9, @acronym{EBCDIC} char@w{
6345 }5) causes a horizontal movement to the next tab stop (much
6346 like it did on a typewriter).
6349 @cindex tab character, non-interpreted (@code{\t})
6350 @cindex character, tab, non-interpreted (@code{\t})
6351 This escape is a non-interpreted tab character. In copy mode
6352 (@pxref{Copy-in Mode}), @code{\t} is the same as a real tab character.
6355 @DefreqList {ta, [@Var{n1} @Var{n2} @dots{} @Var{nn} @t{T} @Var{r1} @Var{r2} @dots{} @Var{rn}]}
6356 @DefregListEnd {.tabs}
6357 Change tab stop positions. This request takes a series of tab
6358 specifiers as arguments (optionally divided into two groups with the
6359 letter @samp{T}) which indicate where each tab stop is to be
6360 (overriding any previous settings).
6362 Tab stops can be specified absolutely, i.e., as the distance from the
6363 left margin. For example, the following sets 6@w{ }tab stops every
6367 .ta 1i 2i 3i 4i 5i 6i
6370 Tab stops can also be specified using a leading @samp{+}
6371 which means that the specified tab stop is set relative to
6372 the previous tab stop. For example, the following is equivalent to the
6376 .ta 1i +1i +1i +1i +1i +1i
6379 @code{gtroff} supports an extended syntax to specify repeat values after
6380 the @samp{T} mark (these values are always taken as relative) -- this is
6381 the usual way to specify tabs set at equal intervals. The following is,
6382 yet again, the same as the previous examples. It does even more since
6383 it defines an infinite number of tab stops separated by one inch.
6389 Now we are ready to interpret the full syntax given at the beginning:
6390 Set tabs at positions @var{n1}, @var{n2}, @dots{}, @var{nn} and then set
6391 tabs at @var{nn}+@var{r1}, @var{nn}+@var{r2}, @dots{}, @var{nn}+@var{rn}
6392 and then at @var{nn}+@var{rn}+@var{r1}, @var{nn}+@var{rn}+@var{r2},
6393 @dots{}, @var{nn}+@var{rn}+@var{rn}, and so on.
6395 Example: @samp{4c +6c T 3c 5c 2c} is equivalent to @samp{4c 10c 13c 18c
6396 20c 23c 28c 30c @dots{}}.
6398 The material in each tab column (i.e., the column between two tab stops)
6399 may be justified to the right or left or centered in the column. This
6400 is specified by appending @samp{R}, @samp{L}, or @samp{C} to the tab
6401 specifier. The default justification is @samp{L}. Example:
6411 The default unit of the @code{ta} request is @samp{m}.
6414 A tab stop is converted into a non-breakable horizontal movement which
6415 can be neither stretched nor squeezed. For example,
6424 creates a single line which is a bit longer than 10@w{ }inches (a string
6425 is used to show exactly where the tab characters are). Now consider the
6435 @code{gtroff} first converts the tab stops of the line into unbreakable
6436 horizontal movements, then splits the line after the second @samp{b}
6437 (assuming a sufficiently short line length). Usually, this isn't what
6441 Superfluous tabs (i.e., tab characters which do not correspond to a tab
6442 stop) are ignored except the first one which delimits the characters
6443 belonging to the last tab stop for right-justifying or centering.
6444 Consider the following example
6448 .ds ZZ foo\tbar\tfoobar
6449 .ds ZZZ foo\tbar\tfoo\tbar
6460 which produces the following output:
6469 The first line right-justifies the second `foo' relative to the tab
6470 stop. The second line right-justifies `foobar'. The third line finally
6471 right-justifies only `foo' because of the additional tab character which
6472 marks the end of the string belonging to the last defined tab stop.
6475 Tab stops are associated with the current environment
6476 (@pxref{Environments}).
6479 Calling @code{ta} without an argument removes all tab stops.
6482 @cindex tab stops, for TTY output devices
6483 The start-up value of @code{gtroff} is @w{@samp{T 0.5i}} in troff mode
6484 and @w{@samp{T 0.8i}} in nroff mode (the latter is done with an
6485 explicit call to the @code{ta} request in the file @file{tty.tmac}.
6488 @cindex tab settings register (@code{.tabs})
6489 The read-only number register @code{.tabs} contains a string
6490 representation of the current tab settings suitable for use as an
6491 argument to the @code{ta} request.
6494 .ds tab-string \n[.tabs]
6499 @cindex @code{.S} register, Plan@w{ }9 alias for @code{.tabs}
6500 @cindex @code{.tabs} register, Plan@w{ }9 alias (@code{.S})
6501 The @code{troff} version of the Plan@w{ }9 operating system uses
6502 register @code{.S} for the same purpose.
6505 @Defreq {tc, [@Var{fill-glyph}]}
6506 @cindex tab repetition character (@code{tc})
6507 @cindex character, tab repetition (@code{tc})
6508 @cindex glyph, tab repetition (@code{tc})
6509 Normally @code{gtroff} fills the space to the next tab stop with
6510 whitespace. This can be changed with the @code{tc} request. With no
6511 argument @code{gtroff} reverts to using whitespace, which is the
6512 default. The value of this @dfn{tab repetition character} is
6513 associated with the current environment
6514 (@pxref{Environments}).@footnote{@dfn{Tab repetition character} is a
6515 misnomer since it is an output glyph.}
6518 @DefreqList {linetabs, n}
6519 @DefregListEnd {.linetabs}
6520 @cindex tab, line-tabs mode
6521 @cindex line-tabs mode
6522 @cindex mode, line-tabs
6523 If @var{n} is missing or not zero, enable @dfn{line-tabs} mode,
6524 or disable it otherwise (the default).
6525 In line-tabs mode, @code{gtroff} computes tab distances
6526 relative to the (current) output line instead of the input line.
6528 For example, the following code:
6541 in normal mode, results in the output
6548 in line-tabs mode, the same code outputs
6554 Line-tabs mode is associated with the current environment.
6555 The read-only register @code{.linetabs} is set to@w{ }1 if in line-tabs
6556 mode, and 0 in normal mode.
6564 @c ---------------------------------------------------------------------
6566 @node Leaders, Fields, Tabs and Fields, Tabs and Fields
6570 Sometimes it may may be desirable to use the @code{tc} request to fill a
6571 particular tab stop with a given glyph (for example dots in a table
6572 of contents), but also normal tab stops on the rest of the line. For
6573 this @code{gtroff} provides an alternate tab mechanism, called
6574 @dfn{leaders} which does just that.
6576 @cindex leader character
6577 A leader character (character code@w{ }1) behaves similarly to a tab
6578 character: It moves to the next tab stop. The only difference is that
6579 for this movement, the fill glyph defaults to a period character and
6583 @cindex leader character, non-interpreted (@code{\a})
6584 @cindex character, leader, non-interpreted (@code{\a})
6585 This escape is a non-interpreted leader character. In copy mode
6586 (@pxref{Copy-in Mode}), @code{\a} is the same as a real leader
6590 @Defreq {lc, [@Var{fill-glyph}]}
6591 @cindex leader repetition character (@code{lc})
6592 @cindex character, leader repetition (@code{lc})
6593 @cindex glyph, leader repetition (@code{lc})
6594 Declare the @dfn{leader repetition character}.@footnote{@dfn{Leader
6595 repetition character} is a misnomer since it is an output glyph.}
6596 Without an argument, leaders act the same as tabs (i.e., using
6597 whitespace for filling). @code{gtroff}'s start-up value is a dot
6598 (@samp{.}). The value of the leader repetition character is
6599 associated with the current environment (@pxref{Environments}).
6602 @cindex table of contents
6603 @cindex contents, table of
6604 For a table of contents, to name an example, tab stops may be defined so
6605 that the section number is one tab stop, the title is the second with
6606 the remaining space being filled with a line of dots, and then the page
6607 number slightly separated from the dots.
6610 .ds entry 1.1\tFoo\a\t12
6620 1.1 Foo.......................................... 12
6623 @c ---------------------------------------------------------------------
6625 @node Fields, , Leaders, Tabs and Fields
6629 @cindex field delimiting character (@code{fc})
6630 @cindex delimiting character, for fields (@code{fc})
6631 @cindex character, field delimiting (@code{fc})
6632 @cindex field padding character (@code{fc})
6633 @cindex padding character, for fields (@code{fc})
6634 @cindex character, field padding (@code{fc})
6635 @dfn{Fields} are a more general way of laying out tabular data. A field
6636 is defined as the data between a pair of @dfn{delimiting characters}.
6637 It contains substrings which are separated by @dfn{padding characters}.
6638 The width of a field is the distance on the @emph{input} line from the
6639 position where the field starts to the next tab stop. A padding
6640 character inserts stretchable space similar to @TeX{}'s @code{\hss}
6641 command (thus it can even be negative) to make the sum of all substring
6642 lengths plus the stretchable space equal to the field width. If more
6643 than one padding character is inserted, the available space is evenly
6644 distributed among them.
6646 @Defreq {fc, [@Var{delim-char} [@Var{padding-char}]]}
6647 Define a delimiting and a padding character for fields. If the latter
6648 is missing, the padding character defaults to a space character. If
6649 there is no argument at all, the field mechanism is disabled (which is
6650 the default). Note that contrary to e.g.@: the tab repetition
6651 character, delimiting and padding characters are @emph{not} associated
6652 to the current environment (@pxref{Environments}).
6665 and here the result:
6674 @c =====================================================================
6676 @node Character Translations, Troff and Nroff Mode, Tabs and Fields, gtroff Reference
6677 @section Character Translations
6678 @cindex character translations
6679 @cindex translations of characters
6681 @cindex control character, changing (@code{cc})
6682 @cindex character, control, changing (@code{cc})
6683 @cindex no-break control character, changing (@code{c2})
6684 @cindex character, no-break control, changing (@code{c2})
6685 @cindex control character, no-break, changing (@code{c2})
6686 The control character (@samp{.}) and the no-break control character
6687 (@samp{'}) can be changed with the @code{cc} and @code{c2} requests,
6690 @Defreq {cc, [@Var{c}]}
6691 Set the control character to@w{ }@var{c}. With no argument the default
6692 control character @samp{.} is restored. The value of the control
6693 character is associated with the current environment
6694 (@pxref{Environments}).
6697 @Defreq {c2, [@Var{c}]}
6698 Set the no-break control character to@w{ }@var{c}. With no argument the
6699 default control character @samp{'} is restored. The value of the
6700 no-break control character is associated with the current environment
6701 (@pxref{Environments}).
6705 @cindex disabling @code{\} (@code{eo})
6706 @cindex @code{\}, disabling (@code{eo})
6707 Disable the escape mechanism completely. After executing this
6708 request, the backslash character @samp{\} no longer starts an escape
6711 This request can be very helpful in writing macros since it is not
6712 necessary then to double the escape character. Here an example:
6715 .\" This is a simplified version of the
6716 .\" .BR request from the man macro package
6720 . while (\n[.$] >= 2) \@{\
6721 . as result \fB\$1\fR\$2
6724 . if \n[.$] .as result \fB\$1
6732 @Defreq {ec, [@Var{c}]}
6733 @cindex escape character, changing (@code{ec})
6734 @cindex character, escape, changing (@code{ec})
6735 Set the escape character to@w{ }@var{c}. With no argument the default
6736 escape character @samp{\} is restored. It can be also used to
6737 re-enable the escape mechanism after an @code{eo} request.
6739 Note that changing the escape character globally will likely break
6740 macro packages since @code{gtroff} has no mechanism to `intern' macros,
6741 i.e., to convert a macro definition into an internal form which is
6742 independent of its representation (@TeX{} has this mechanism).
6743 If a macro is called, it is executed literally.
6747 @DefreqListEnd {ecr, }
6748 The @code{ecs} request saves the current escape character
6749 in an internal register.
6750 Use this request in combination with the @code{ec} request to
6751 temporarily change the escape character.
6753 The @code{ecr} request restores the escape character
6754 saved with @code{ecs}.
6755 Without a previous call to @code{ecs}, this request
6756 sets the escape character to @code{\}.
6759 @DefescList {\\\\, , , }
6760 @DefescItem {\\e, , , }
6761 @DefescListEnd {\\E, , , }
6762 Print the current escape character (which is the backslash character
6763 @samp{\} by default).
6765 @code{\\} is a `delayed' backslash; more precisely, it is the default
6766 escape character followed by a backslash, which no longer has special
6767 meaning due to the leading escape character. It is @emph{not} an escape
6768 sequence in the usual sense! In any unknown escape sequence
6769 @code{\@var{X}} the escape character is ignored and @var{X} is printed.
6770 But if @var{X} is equal to the current escape character, no warning is
6773 As a consequence, only at top-level or in a diversion a backslash glyph is
6774 printed; in copy-in mode, it expands to a single backslash which then
6775 combines with the following character to an escape sequence.
6777 The @code{\E} escape differs from @code{\e} by printing an escape
6778 character that is not interpreted in copy mode.
6779 Use this to define strings with escapes that work
6780 when used in copy mode (for example, as a macro argument).
6781 The following example defines strings to begin and end
6785 .ds @{ \v'-.3m'\s'\Es[.s]*60/100'
6789 Another example to demonstrate the differences between the various escape
6790 sequences, using a strange escape character, @samp{-}.
6802 The result is surprising for most users, expecting @samp{1} since
6803 @samp{foo} is a valid identifier. What has happened? As mentioned
6804 above, the leading escape character makes the following character
6805 ordinary. Written with the default escape character the sequence
6806 @samp{--} becomes @samp{\-} -- this is the minus sign.
6808 If the escape character followed by itself is a valid escape sequence,
6809 only @code{\E} yields the expected result:
6822 Similar to @code{\\}, the sequence @code{\.} isn't a real escape sequence.
6823 As before, a warning message is suppressed if the escape character is
6824 followed by a dot, and the dot itself is printed.
6841 The first backslash is consumed while the macro is read, and the second
6842 is swallowed while exexuting macro @code{foo}.
6845 A @dfn{translation} is a mapping of an input character to an output
6846 glyph. The mapping occurs at output time, i.e., the input character
6847 gets assigned the metric information of the mapped output character
6848 right before input tokens are converted to nodes (@pxref{Gtroff
6849 Internals}, for more on this process).
6851 @DefreqList {tr, @Var{a}@Var{b}@Var{c}@Var{d}@dots{}}
6852 @DefreqListEnd {trin, @Var{a}@Var{b}@Var{c}@Var{d}@dots{}}
6853 Translate character @var{a} to glyph@w{ }@var{b}, character @var{c} to
6854 glyph@w{ }@var{d}, etc. If there is an odd number of arguments, the
6855 last one is translated to an unstretchable space (@w{@samp{\ }}).
6857 The @code{trin} request is identical to @code{tr},
6858 but when you unformat a diversion with @code{asciify}
6859 it ignores the translation.
6860 @xref{Diversions}, for details about the @code{asciify} request.
6866 @cindex @code{\(}, and translations
6867 @cindex @code{\[}, and translations
6868 @cindex @code{\'}, and translations
6869 @cindex @code{\`}, and translations
6870 @cindex @code{\-}, and translations
6871 @cindex @code{\_}, and translations
6872 @cindex @code{\C}, and translations
6873 @cindex @code{\N}, and translations
6874 @cindex @code{char} request, and translations
6875 @cindex special characters
6876 @cindex character, special
6877 @cindex numbered glyph (@code{\N})
6878 @cindex glyph, numbered (@code{\N})
6879 Special characters (@code{\(@var{xx}}, @code{\[@var{xxx}]},
6880 @code{\C'@var{xxx}'}, @code{\'}, @code{\`}, @code{\-}, @code{\_}),
6881 glyphs defined with the @code{char} request, and numbered glyphs
6882 (@code{\N'@var{xxx}'}) can be translated also.
6885 @cindex @code{\e}, and translations
6886 The @code{\e} escape can be translated also.
6889 @cindex @code{\%}, and translations
6890 @cindex @code{\~}, and translations
6891 Characters can be mapped onto the @code{\%} and @code{\~} escapes (but
6892 @code{\%} and @code{\~} can't be mapped onto another glyph).
6895 @cindex backspace character, and translations
6896 @cindex character, backspace, and translations
6897 @cindex leader character, and translations
6898 @cindex character, leader, and translations
6899 @cindex newline character, and translations
6900 @cindex character, newline, and translations
6901 @cindex tab character, and translations
6902 @cindex character, tab, and translations
6903 @cindex @code{\a}, and translations
6904 @cindex @code{\t}, and translations
6905 The following characters can't be translated: space (with one exception,
6906 see below), backspace, newline, leader (and @code{\a}), tab (and
6910 @cindex @code{shc} request, and translations
6911 Translations are not considered for finding the soft hyphen character
6912 set with the @code{shc} request.
6915 @cindex @code{\&}, and translations
6916 The pair @samp{@var{c}\&} (this is an arbitrary character@w{
6917 }@var{c} followed by the zero width space character) maps this
6918 character to nothing.
6927 It is even possible to map the space character to nothing:
6936 As shown in the example, the space character can't be the first
6937 character/glyph pair as an argument of @code{tr}. Additionally, it is
6938 not possible to map the space character to any other glyph; requests
6939 like @w{@samp{.tr aa x}} undo @w{@samp{.tr aa \&}} instead.
6941 If justification is active, lines are justified in spite of the
6942 `empty' space character (but there is no minimal distance, i.e.@: the
6943 space character, between words).
6946 After an output glyph has been constructed (this happens at the
6947 moment immediately before the glyph is appended to an output
6948 glyph list, either by direct output, in a macro, diversion, or
6949 string), it is no longer affected by @code{tr}.
6952 Translating character to glyphs where one of them or both are
6953 undefined is possible also; @code{tr} does not check whether the
6954 entities in its argument do exist.
6956 @xref{Gtroff Internals}.
6959 @code{troff} no longer has a hard-coded dependency on @w{Latin-1};
6960 all @code{char@var{XXX}} entities have been removed from the font
6961 description files. This has a notable consequence which shows up in
6962 warnings like @code{can't find character with input code @var{XXX}}
6963 if the @code{tr} request isn't handled properly.
6965 Consider the following translation:
6972 This maps input character @code{@'e} onto glyph @code{@'E}, which is
6973 identical to glyph @code{char201}. But this glyph intentionally
6974 doesn't exist! Instead, @code{\[char201]} is treated as an input
6975 character entity and is by default mapped onto @code{\['E]}, and
6976 @code{gtroff} doesn't handle translations of translations.
6978 The right way to write the above translation is
6985 With other words, the first argument of @code{tr} should be an input
6986 character or entity, and the second one a glyph entity.
6989 Without an argument, the @code{tr} request is ignored.
6993 @Defreq {trnt, @Var{a}@Var{b}@Var{c}@Var{d}@dots{}}
6994 @cindex @code{\!}, and @code{trnt}
6995 @code{trnt} is the same as the @code{tr} request except that the
6996 translations do not apply to text that is transparently throughput
6997 into a diversion with @code{\!}. @xref{Diversions}, for more
7011 prints @samp{b} to the standard error stream; if @code{trnt} is used
7012 instead of @code{tr} it prints @samp{a}.
7016 @c =====================================================================
7018 @node Troff and Nroff Mode, Line Layout, Character Translations, gtroff Reference
7019 @section Troff and Nroff Mode
7025 Originally, @code{nroff} and @code{troff} were two separate programs,
7026 the former for TTY output, the latter for everything else. With GNU
7027 @code{troff}, both programs are merged into one executable, sending
7028 its output to a device driver (@code{grotty} for TTY devices,
7029 @code{grops} for @sc{PostScript}, etc.) which interprets the
7030 intermediate output of @code{gtroff}. For @acronym{UNIX} @code{troff}
7031 it makes sense to talk about @dfn{Nroff mode} and @dfn{Troff mode}
7032 since the differences are hardcoded. For GNU @code{troff}, this
7033 distinction is not appropriate because @code{gtroff} simply takes the
7034 information given in the font files for a particular device without
7035 handling requests specially if a TTY output device is used.
7037 Usually, a macro package can be used with all output devices.
7038 Nevertheless, it is sometimes necessary to make a distinction between
7039 TTY and non-TTY devices: @code{gtroff} provides two built-in
7040 conditions @samp{n} and @samp{t} for the @code{if}, @code{ie}, and
7041 @code{while} requests to decide whether @code{gtroff} shall behave
7042 like @code{nroff} or like @code{troff}.
7047 Make the @samp{t} built-in condition true (and the @samp{n} built-in
7048 condition false) for @code{if}, @code{ie}, and @code{while}
7049 conditional requests. This is the default if @code{gtroff}
7050 (@emph{not} @code{groff}) is started with the @option{-R} switch to
7051 avoid loading of the start-up files @file{troffrc} and
7052 @file{troffrc-end}. Without @option{-R}, @code{gtroff} stays in troff
7053 mode if the output device is not a TTY (e.g.@: `ps').
7058 Make the @samp{n} built-in condition true (and the @samp{t} built-in
7059 condition false) for @code{if}, @code{ie}, and @code{while}
7060 conditional requests. This is the default if @code{gtroff} uses a TTY
7061 output device; the code for switching to nroff mode is in the file
7062 @file{tty.tmac} which is loaded by the start-up file @code{troffrc}.
7065 @xref{Conditionals and Loops}, for more details on built-in
7069 @c =====================================================================
7071 @node Line Layout, Line Control, Troff and Nroff Mode, gtroff Reference
7072 @section Line Layout
7074 @cindex layout, line
7076 @cindex dimensions, line
7077 @cindex line dimensions
7078 The following drawing shows the dimensions which @code{gtroff} uses for
7079 placing a line of output onto the page. They are labeled with the
7080 request which manipulates each dimension.
7084 |<-----------ll------------>|
7085 +----+----+----------------------+----+
7087 +----+----+----------------------+----+
7089 |<--------paper width---------------->|
7093 These dimensions are:
7097 @cindex left margin (@code{po})
7098 @cindex margin, left (@code{po})
7099 @cindex page offset (@code{po})
7100 @cindex offset, page (@code{po})
7101 @dfn{Page offset} -- this is the leftmost position of text on the final
7102 output, defining the @dfn{left margin}.
7105 @cindex indentation (@code{in})
7106 @cindex line indentation (@code{in})
7107 @dfn{Indentation} -- this is the distance from the left margin where
7111 @cindex line length (@code{ll})
7112 @cindex length of line (@code{ll})
7113 @dfn{Line length} -- this is the distance from the left margin to right
7117 A simple demonstration:
7121 This is text without indentation.
7122 The line length has been set to 3\~inch.
7125 Now the left and right margins are both increased.
7128 Calling .in and .ll without parameters restore
7129 the previous values.
7135 This is text without indenta-
7136 tion. The line length has
7141 Calling .in and .ll without
7142 parameters restore the previ-
7146 @DefreqList {po, [@Var{offset}]}
7147 @DefreqItem {po, @t{+}@Var{offset}}
7148 @DefreqItem {po, @t{-}@Var{offset}}
7151 Set horizontal page offset to @var{offset} (or increment or decrement
7152 the current value by @var{offset}). Note that this request does not
7153 cause a break, so changing the page offset in the middle of text being
7154 filled may not yield the expected result. The initial value is
7155 1@dmn{i}. For TTY output devices, it is set to 0 in the startup file
7156 @file{troffrc}; the default scaling indicator is @samp{m} (and
7157 not @samp{v} as incorrectly documented in the original
7158 @acronym{UNIX} troff manual).
7160 The current page offset can be found in the read-only number register
7163 If @code{po} is called without an argument, the page offset is reset to
7164 the previous value before the last call to @code{po}.
7179 @DefreqList {in, [@Var{indent}]}
7180 @DefreqItem {in, @t{+}@Var{indent}}
7181 @DefreqItem {in, @t{-}@Var{indent}}
7183 Set indentation to @var{indent} (or increment or decrement the
7184 current value by @var{indent}). This request causes a break.
7185 Initially, there is no indentation.
7187 If @code{in} is called without an argument, the indentation is reset to
7188 the previous value before the last call to @code{in}. The default
7189 scaling indicator is @samp{m}.
7191 The indentation is associated with the current environment
7192 (@pxref{Environments}).
7194 If a negative indentation value is specified (which is not allowed),
7195 @code{gtroff} emits a warning of type @samp{range} and sets the
7196 indentation to zero.
7198 The effect of @code{in} is delayed until a partially collected line (if
7199 it exists) is output. A temporary indent value is reset to zero also.
7201 The current indentation (as set by @code{in}) can be found in the
7202 read-only number register @samp{.i}.
7205 @DefreqList {ti, offset}
7206 @DefreqItem {ti, @t{+}@Var{offset}}
7207 @DefreqItem {ti, @t{-}@Var{offset}}
7208 @DefregListEnd {.in}
7209 Temporarily indent the next output line by @var{offset}. If an
7210 increment or decrement value is specified, adjust the temporary
7211 indentation relative to the value set by the @code{in} request.
7213 This request causes a break; its value is associated with the current
7214 environment (@pxref{Environments}). The default scaling indicator
7215 is @samp{m}. A call of @code{ti} without an argument is ignored.
7217 If the total indentation value is negative (which is not allowed),
7218 @code{gtroff} emits a warning of type @samp{range} and sets the
7219 temporary indentation to zero. `Total indentation' is either
7220 @var{offset} if specified as an absolute value, or the temporary plus
7221 normal indentation, if @var{offset} is given as a relative value.
7223 The effect of @code{ti} is delayed until a partially collected line (if
7224 it exists) is output.
7226 The read-only number register @code{.in} is the indentation that applies
7227 to the current output line.
7229 The difference between @code{.i} and @code{.in} is that the latter takes
7230 into account whether a partially collected line still uses the old
7231 indentation value or a temporary indentation value is active.
7234 @DefreqList {ll, [@Var{length}]}
7235 @DefreqItem {ll, @t{+}@Var{length}}
7236 @DefreqItem {ll, @t{-}@Var{length}}
7238 @DefregListEnd {.ll}
7239 Set the line length to @var{length} (or increment or decrement the
7240 current value by @var{length}). Initially, the line length is set to
7241 6.5@dmn{i}. The effect of @code{ll} is delayed until a partially
7242 collected line (if it exists) is output. The default scaling
7243 indicator is @samp{m}.
7245 If @code{ll} is called without an argument, the line length is reset to
7246 the previous value before the last call to @code{ll}. If a negative
7247 line length is specified (which is not allowed), @code{gtroff} emits a
7248 warning of type @samp{range} and sets the line length to zero.
7250 The line length is associated with the current environment
7251 (@pxref{Environments}).
7253 @cindex line length register (@code{.l})
7254 The current line length (as set by @code{ll}) can be found in the
7255 read-only number register @samp{.l}. The read-only number register
7256 @code{.ll} is the line length that applies to the current output line.
7258 Similar to @code{.i} and @code{.in}, the difference between @code{.l}
7259 and @code{.ll} is that the latter takes into account whether a partially
7260 collected line still uses the old line length value.
7264 @c =====================================================================
7266 @node Line Control, Page Layout, Line Layout, gtroff Reference
7267 @section Line Control
7268 @cindex line control
7269 @cindex control, line
7271 It is important to understand how @code{gtroff} handles input and output
7274 Many escapes use positioning relative to the input line. For example,
7278 This is a \h'|1.2i'test.
7293 The main usage of this feature is to define macros which act exactly
7294 at the place where called.
7297 .\" A simple macro to underline a word
7299 . nop \\$1\l'|0\[ul]'
7304 In the above example, @samp{|0} specifies a negative distance from the
7305 current position (at the end of the just emitted argument @code{\$1}) back
7306 to the beginning of the input line. Thus, the @samp{\l} escape draws a
7307 line from right to left.
7309 @cindex input line continuation (@code{\})
7310 @cindex line, input, continuation (@code{\})
7311 @cindex continuation, input line (@code{\})
7312 @cindex output line, continuation (@code{\c})
7313 @cindex line, output, continuation (@code{\c})
7314 @cindex continuation, output line (@code{\c})
7315 @cindex interrupted line
7316 @cindex line, interrupted
7317 @code{gtroff} makes a difference between input and output line
7318 continuation; the latter is also called @dfn{interrupting} a line.
7320 @DefescList {\\@key{RET}, , ,}
7321 @DefescItem {\\c, , ,}
7322 @DefregListEnd{.int}
7323 Continue a line. @code{\@key{RET}} (this is a backslash at the end
7324 of a line immediately followed by a newline) works on the input level,
7325 suppressing the effects of the following newline in the input.
7330 @result{} This is a .test
7333 The @samp{|} operator is also affected.
7335 @cindex @code{\R}, after @code{\c}
7336 @code{\c} works on the output level. Anything after this escape on the
7337 same line is ignored, except @code{\R} which works as usual. Anything
7338 before @code{\c} on the same line will be appended to the current partial
7339 output line. The next non-command line after an interrupted line counts
7340 as a new input line.
7342 The visual results depend on whether no-fill mode is active.
7346 @cindex @code{\c}, and no-fill mode
7347 @cindex no-fill mode, and @code{\c}
7348 @cindex mode, no-fill, and @code{\c}
7349 If no-fill mode is active (using the @code{nf} request), the next input
7350 text line after @code{\c} will be handled as a continuation of the same
7357 @result{} This is a test.
7361 @cindex @code{\c}, and fill mode
7362 @cindex fill mode, and @code{\c}
7363 @cindex mode, fill, and @code{\c}
7364 If fill mode is active (using the @code{fi} request), a word interrupted
7365 with @code{\c} will be continued with the text on the next input text line,
7366 without an intervening space.
7371 @result{} This is a test.
7375 Note that an intervening control line which causes a break is stronger
7376 than @code{\c}, flushing out the current partial line in the usual way.
7378 @cindex interrupted line register (@code{.int})
7379 The @code{.int} register contains a positive value
7380 if the last output line was interrupted with @code{\c}; this is
7381 associated with the current environment (@pxref{Environments}).
7385 @c =====================================================================
7387 @node Page Layout, Page Control, Line Control, gtroff Reference
7388 @section Page Layout
7390 @cindex layout, page
7392 @code{gtroff} provides some very primitive operations for controlling
7395 @DefreqList {pl, [@Var{length}]}
7396 @DefreqItem {pl, @t{+}@Var{length}}
7397 @DefreqItem {pl, @t{-}@Var{length}}
7399 @cindex page length (@code{pl})
7400 @cindex length of page (@code{pl})
7401 Set the @dfn{page length} to @var{length} (or increment or decrement
7402 the current value by @var{length}). This is the length of the
7403 physical output page. The default scaling indicator is @samp{v}.
7405 @cindex page length register (@code{.p})
7406 The current setting can be found in the read-only number register
7411 @cindex bottom margin
7412 @cindex margin, bottom
7413 Note that this only specifies the size of the page, not the top and
7414 bottom margins. Those are not set by @code{gtroff} directly.
7415 @xref{Traps}, for further information on how to do this.
7417 Negative @code{pl} values are possible also, but not very useful: No
7418 trap is sprung, and each line is output on a single page (thus
7419 suppressing all vertical spacing).
7421 If no argument or an invalid argument is given, @code{pl} sets the page
7422 length to 11@dmn{i}.
7428 @code{gtroff} provides several operations which help in setting up top
7429 and bottom titles (or headers and footers).
7431 @Defreq {tl, @t{'}@Var{left}@t{'}@Var{center}@t{'}@Var{right}@t{'}}
7432 @cindex title line (@code{tl})
7433 @cindex three-part title (@code{tl})
7434 @cindex page number character (@code{%})
7435 Print a @dfn{title line}. It consists of three parts: a left
7436 justified portion, a centered portion, and a right justified portion.
7437 The argument separator @samp{'} can be replaced with any character not
7438 occurring in the title line. The @samp{%} character is replaced with
7439 the current page number. This character can be changed with the
7440 @code{pc} request (see below).
7442 Without argument, @code{tl} is ignored.
7448 A title line is not restricted to the top or bottom of a page.
7451 @code{tl} prints the title line immediately, ignoring a partially filled
7452 line (which stays untouched).
7455 It is not an error to omit closing delimiters. For example,
7456 @w{@samp{.tl /foo}} is equivalent to @w{@samp{.tl /foo///}}: It prints a
7457 title line with the left justified word @samp{foo}; the centered and
7458 right justfied parts are empty.
7461 @code{tl} accepts the same parameter delimiting characters as the
7462 @code{\A} escape; see @ref{Escapes}.
7466 @DefreqList {lt, [@Var{length}]}
7467 @DefreqItem {lt, @t{+}@Var{length}}
7468 @DefreqItem {lt, @t{-}@Var{length}}
7469 @DefregListEnd {.lt}
7470 @cindex length of title line (@code{lt})
7471 @cindex title line, length (@code{lt})
7472 @cindex title line length register (@code{.lt})
7473 The title line is printed using its own line length, which is
7474 specified (or incremented or decremented) with the @code{lt} request.
7475 Initially, the title line length is set to 6.5@dmn{i}. If a negative
7476 line length is specified (which is not allowed), @code{gtroff} emits a
7477 warning of type @samp{range} and sets the title line length to zero.
7478 The default scaling indicator is @samp{m}. If @code{lt} is called
7479 without an argument, the title length is reset to the previous value
7480 before the last call to @code{lt}.
7482 The current setting of this is available in the @code{.lt} read-only
7483 number register; it is associated with the current environment
7484 (@pxref{Environments}).
7488 @DefreqList {pn, page}
7489 @DefreqItem {pn, @t{+}@Var{page}}
7490 @DefreqItem {pn, @t{-}@Var{page}}
7491 @DefregListEnd {.pn}
7492 @cindex page number (@code{pn})
7493 @cindex number, page (@code{pn})
7494 Change (increase or decrease) the page number of the @emph{next} page.
7495 The only argument is the page number; the request is ignored without a
7498 The read-only number register @code{.pn} contains the number of the next
7499 page: either the value set by a @code{pn} request, or the number of the
7500 current page plus@w{ }1.
7504 @cindex page number register (@code{%})
7505 A read-write register holding the current page number.
7508 @Defreq {pc, [@Var{char}]}
7509 @cindex changing the page number character (@code{pc})
7510 @cindex page number character, changing (@code{pc})
7512 Change the page number character (used by the @code{tl} request) to a
7513 different character. With no argument, this mechanism is disabled.
7514 Note that this doesn't affect the number register@w{ }@code{%}.
7520 @c =====================================================================
7522 @node Page Control, Fonts, Page Layout, gtroff Reference
7523 @section Page Control
7524 @cindex page control
7525 @cindex control, page
7527 @DefreqList {bp, [@Var{page}]}
7528 @DefreqItem {bp, @t{+}@Var{page}}
7529 @DefreqListEnd {bp, @t{-}@Var{page}}
7530 @cindex new page (@code{bp})
7531 @cindex page, new (@code{bp})
7532 Stop processing the current page and move to the next page. This
7533 request causes a break. It can also take an argument to set
7534 (increase, decrease) the page number of the next page. The only
7535 difference between @code{bp} and @code{pn} is that @code{pn} does not
7536 cause a break or actually eject a page.
7539 .de newpage \" define macro
7541 'sp .5i \" vertical space
7542 .tl 'left top'center top'right top' \" title
7543 'sp .3i \" vertical space
7547 @cindex @code{bp} request, and top-level diversion
7548 @cindex top-level diversion, and @code{bp}
7549 @cindex diversion, top-level, and @code{bp}
7550 @code{bp} has no effect if not called within the top-level diversion
7551 (@pxref{Diversions}).
7554 @Defreq {ne, [@Var{space}]}
7555 @cindex orphan lines, preventing with @code{ne}
7556 @cindex conditional page break (@code{ne})
7557 @cindex page break, conditional (@code{ne})
7558 It is often necessary to force a certain amount of space before a new
7559 page occurs. This is most useful to make sure that there is not a
7560 single @dfn{orphan} line left at the bottom of a page. The @code{ne}
7561 request ensures that there is a certain distance, specified by the
7562 first argument, before the next page is triggered (see @ref{Traps},
7563 for further information). The default scaling indicator for @code{ne}
7564 is @samp{v}; the default value of @var{space} is@w{ }1@dmn{v} if no
7567 For example, to make sure that no fewer than 2@w{ }lines get orphaned,
7568 do the following before each paragraph:
7575 @code{ne} will then automatically cause a page break if there is space
7579 @DefreqList {sv, [@Var{space}]}
7580 @DefreqListEnd {os, }
7581 @cindex @code{ne} request, comparison with @code{sv}
7582 @code{sv} is similar to the @code{ne} request; it reserves the
7583 specified amount of vertical space. If the desired amount of space
7584 exists before the next trap (or the bottom page boundary if no trap is
7585 set), the space is output immediately (ignoring a partially filled line
7586 which stays untouched). If there is not enough space, it is stored for
7587 later output via the @code{os} request. The default value is@w{ }1@dmn{v}
7588 if no argument is given; the default scaling indicator is @samp{v}.
7590 @cindex @code{sv} request, and no-space mode
7591 @cindex @code{os} request, and no-space mode
7592 Both @code{sv} and @code{os} ignore no-space mode. While the @code{sv}
7593 request allows negative values for @var{space}, @code{os} will ignore
7598 This register contains the current vertical position. If the vertical
7599 position is zero and the top of page transition hasn't happened yet,
7600 @code{nl} is set to negative value. @code{gtroff} itself does this at
7601 the very beginning of a document before anything has been printed, but
7602 the main usage is to plant a header trap on a page if this page has
7605 Consider the following:
7637 Without resetting @code{nl} to a negative value, the just planted trap
7638 would be active beginning with the @emph{next} page, not the current
7641 @xref{Diversions}, for a comparison with the @code{.h} and @code{.d}
7645 @c =====================================================================
7647 @node Fonts, Sizes, Page Control, gtroff Reference
7651 @code{gtroff} can switch fonts at any point in the text.
7653 The basic set of fonts is @samp{R}, @samp{I}, @samp{B}, and @samp{BI}.
7654 These are Times Roman, Italic, Bold, and Bold Italic. For non-TTY
7655 devices, there is also at least one symbol font which contains various
7656 special symbols (Greek, mathematics).
7664 * Artificial Fonts::
7665 * Ligatures and Kerning::
7668 @c ---------------------------------------------------------------------
7670 @node Changing Fonts, Font Families, Fonts, Fonts
7671 @subsection Changing Fonts
7674 @DefreqList {ft, [@Var{font}]}
7675 @DefescItem {\\f, , f, }
7676 @DefescItem {\\f, @lparen{}, fn, }
7677 @DefescListEnd {\\f, @lbrack{}, font, @rbrack}
7678 @cindex changing fonts (@code{ft}, @code{\f})
7679 @cindex fonts, changing (@code{ft}, @code{\f})
7680 @cindex @code{sty} request, and changing fonts
7681 @cindex @code{fam} request, and changing fonts
7682 @cindex @code{\F}, and changing fonts
7686 The @code{ft} request and the @code{\f} escape change the current font
7687 to @var{font} (one-character name@w{ }@var{f}, two-character name
7690 If @var{font} is a style name (as set with the @code{sty} request or
7691 with the @code{styles} command in the @file{DESC} file), use it within
7692 the current font family (as set with the @code{fam} request, @code{\F}
7693 escape, or with the @code{family} command in the @file{DESC} file).
7695 @cindex previous font (@code{ft}, @code{\f[]}, @code{\fP})
7696 @cindex font, previous (@code{ft}, @code{\f[]}, @code{\fP})
7697 With no argument or using @samp{P} as an argument, @code{.ft} switches
7698 to the previous font. Use @code{\f[]} to do this with the escape. The
7699 old syntax forms @code{\fP} or @code{\f[P]} are also supported.
7701 Fonts are generally specified as upper-case strings, which are usually
7702 1@w{ }to 4 characters representing an abbreviation or acronym of the
7703 font name. This is no limitation, just a convention.
7705 The example below produces two identical lines.
7714 eggs, bacon, \fBspam\fP and sausage.
7717 Note that @code{\f} doesn't produce an input token in @code{gtroff}.
7718 As a consequence, it can be used in requests like @code{mc} (which
7719 expects a single character as an argument) to change the font on
7726 @xref{Font Positions}, for an alternative syntax.
7729 @Defreq {ftr, f [@Var{g}]}
7730 @cindex @code{ft} request, and font translations
7731 @cindex @code{ul} request, and font translations
7732 @cindex @code{bd} request, and font translations
7733 @cindex @code{\f}, and font translations
7734 @cindex @code{cs} request, and font translations
7735 @cindex @code{tkf} request, and font translations
7736 @cindex @code{special} request, and font translations
7737 @cindex @code{fspecial} request, and font translations
7738 @cindex @code{fp} request, and font translations
7739 @cindex @code{sty} request, and font translations
7740 Translate font@w{ }@var{f} to font@w{ }@var{g}. Whenever a font named@w{
7741 }@var{f} is referred to in a @code{\f} escape sequence, or in the
7742 @code{ft}, @code{ul}, @code{bd}, @code{cs}, @code{tkf},
7743 @code{special}, @code{fspecial}, @code{fp}, or @code{sty} requests,
7744 font@w{ }@var{g} is used. If @var{g} is missing or equal to@w{ }@var{f}
7745 the translation is undone.
7748 @c ---------------------------------------------------------------------
7750 @node Font Families, Font Positions, Changing Fonts, Fonts
7751 @subsection Font Families
7752 @cindex font families
7753 @cindex families, font
7755 @cindex styles, font
7757 Due to the variety of fonts available, @code{gtroff} has added the
7758 concept of @dfn{font families} and @dfn{font styles}. The fonts are
7759 specified as the concatenation of the font family and style. Specifying
7760 a font without the family part causes @code{gtroff} to use that style of
7763 @cindex PostScript fonts
7764 @cindex fonts, PostScript
7765 Currently, fonts for the devices @option{-Tps}, @option{-Tdvi}, and
7766 @option{-Tlbp} are set up to this mechanism.
7767 By default, @code{gtroff} uses the Times family with the four styles
7768 @samp{R}, @samp{I}, @samp{B}, and @samp{BI}.
7770 This way, it is possible to use the basic four fonts and to select a
7771 different font family on the command line (@pxref{Groff Options}).
7773 @DefreqList {fam, [@Var{family}]}
7775 @DefescItem {\\F, , f, }
7776 @DefescItem {\\F, @lparen{}, fm, }
7777 @DefescItem {\\F, @lbrack{}, family, @rbrack}
7778 @DefregListEnd {.fn}
7779 @cindex changing font family (@code{fam}, @code{\F})
7780 @cindex font family, changing (@code{fam}, @code{\F})
7781 Switch font family to @var{family} (one-character name@w{ }@var{f},
7782 two-character name @var{fm}). If no argument is given, switch
7783 back to the previous font family. Use @code{\F[]} to do this with the
7784 escape. Note that @code{\FP} doesn't work; it selects font family
7787 The value at start-up is @samp{T}.
7788 The current font family is available in the read-only number register
7789 @samp{.fam} (this is a string-valued register); it is associated with
7790 the current environment.
7794 .fam H \" helvetica family
7795 spam, \" used font is family H + style R = HR
7796 .ft B \" family H + style B = font HB
7798 .fam T \" times family
7799 spam, \" used font is family T + style B = TB
7800 .ft AR \" font AR (not a style)
7802 .ft R \" family T + style R = font TR
7806 Note that @code{\F} doesn't produce an input token in @code{gtroff}.
7807 As a consequence, it can be used in requests like @code{mc} (which
7808 expects a single character as an argument) to change the font family on
7815 The @samp{.fn} register contains the current @dfn{real font name}
7816 of the current font.
7817 This is a string-valued register.
7818 If the current font is a style, the value of @code{\n[.fn]}
7819 is the proper concatenation of family and style name.
7822 @Defreq {sty, n style}
7823 @cindex changing font style (@code{sty})
7824 @cindex font style, changing (@code{sty})
7825 @cindex @code{cs} request, and font styles
7826 @cindex @code{bd} request, and font styles
7827 @cindex @code{tkf} request, and font styles
7828 @cindex @code{uf} request, and font styles
7829 @cindex @code{fspecial} request, and font styles
7830 Associate @var{style} with font position@w{ }@var{n}. A font position
7831 can be associated either with a font or with a style. The current
7832 font is the index of a font position and so is also either a font or a
7833 style. If it is a style, the font that is actually used is the font
7834 which name is the concatenation of the name of the current
7835 family and the name of the current style. For example, if the current
7836 font is@w{ }1 and font position@w{ }1 is associated with style
7837 @samp{R} and the current font family is @samp{T}, then font
7838 @samp{TR} will be used. If the current font is not a style, then the
7839 current family is ignored. If the requests @code{cs}, @code{bd},
7840 @code{tkf}, @code{uf}, or @code{fspecial} are applied to a style,
7841 they will instead be applied to the member of the current family
7842 corresponding to that style.
7844 @var{n}@w{ }must be a non-negative integer value.
7848 The default family can be set with the @option{-f} option
7849 (@pxref{Groff Options}). The @code{styles} command in the @file{DESC}
7850 file controls which font positions (if any) are initially associated
7851 with styles rather than fonts. For example, the default setting for
7852 @sc{PostScript} fonts
7868 @code{fam} and @code{\F} always check whether the current font position
7869 is valid; this can give surprising results if the current font position is
7870 associated with a style.
7872 In the following example, we want to access the @sc{PostScript} font
7873 @code{FooBar} from the font family @code{Foo}:
7878 @result{} warning: can't find font `FooR'
7882 The default font position at start-up is@w{ }1; for the
7883 @sc{PostScript} device, this is associated with style @samp{R}, so
7884 @code{gtroff} tries to open @code{FooR}.
7886 A solution to this problem is to use a dummy font like the following:
7889 .fp 0 dummy TR \" set up dummy font at position 0
7890 .sty \n[.fp] Bar \" register style `Bar'
7891 .ft 0 \" switch to font at position 0
7892 .fam Foo \" activate family `Foo'
7893 .ft Bar \" switch to font `FooBar'
7896 @xref{Font Positions}.
7899 @c ---------------------------------------------------------------------
7901 @node Font Positions, Using Symbols, Font Families, Fonts
7902 @subsection Font Positions
7903 @cindex font positions
7904 @cindex positions, font
7906 For the sake of old phototypesetters and compatibility with old versions
7907 of @code{troff}, @code{gtroff} has the concept of font @dfn{positions},
7908 on which various fonts are mounted.
7910 @DefreqList {fp, pos font [@Var{external-name}]}
7912 @DefregListEnd {.fp}
7913 @cindex mounting font (@code{fp})
7914 @cindex font, mounting (@code{fp})
7915 Mount font @var{font} at position @var{pos} (which must be a
7916 non-negative integer). This numeric position can then be referred to
7917 with font changing commands. When @code{gtroff} starts it is using
7918 font position@w{ }1 (which must exist; position@w{ }0 is unused
7919 usually at start-up).
7921 @cindex font position register (@code{.f})
7922 The current font in use, as a font position, is available in the
7923 read-only number register @samp{.f}. This can be useful to remember the
7924 current font for later recall. It is associated with the current
7925 environment (@pxref{Environments}).
7928 .nr save-font \n[.f]
7930 ... text text text ...
7934 @cindex next free font position register (@code{.fp})
7935 The number of the next free font position is available in the read-only
7936 number register @samp{.fp}. This is useful when mounting a new font,
7940 .fp \n[.fp] NEATOFONT
7943 @pindex DESC@r{, and font mounting}
7944 Fonts not listed in the @file{DESC} file are automatically mounted on
7945 the next available font position when they are referenced. If a font
7946 is to be mounted explicitly with the @code{fp} request on an unused
7947 font position, it should be mounted on the first unused font position,
7948 which can be found in the @code{.fp} register. Although @code{gtroff}
7949 does not enforce this strictly, it is not allowed to mount a font at a
7950 position whose number is much greater (approx.@: 1000 positions) than
7951 that of any currently used position.
7953 The @code{fp} request has an optional third argument. This argument
7954 gives the external name of the font, which is used for finding the font
7955 description file. The second argument gives the internal name of the
7956 font which is used to refer to the font in @code{gtroff} after it has
7957 been mounted. If there is no third argument then the internal name is
7958 used as the external name. This feature makes it possible to use
7959 fonts with long names in compatibility mode.
7962 Both the @code{ft} request and the @code{\f} escape have alternative
7963 syntax forms to access font positions.
7965 @DefreqList {ft, nnn}
7966 @DefescItem {\\f, , n, }
7967 @DefescItem {\\f, @lparen{}, nn, }
7968 @DefescListEnd {\\f, @lbrack{}, nnn, @rbrack}
7969 @cindex changing font position (@code{\f})
7970 @cindex font position, changing (@code{\f})
7971 @cindex @code{sty} request, and font positions
7972 @cindex @code{fam} request, and font positions
7973 @cindex @code{\F}, and font positions
7977 Change the current font position to @var{nnn} (one-digit position@w{
7978 }@var{n}, two-digit position @var{nn}), which must be a non-negative
7981 If @var{nnn} is associated with a style (as set with the @code{sty}
7982 request or with the @code{styles} command in the @file{DESC} file), use
7983 it within the current font family (as set with the @code{fam} request,
7984 the @code{\F} escape, or with the @code{family} command in the @file{DESC}
7991 .ft \" switch back to font 1
7995 this is font 1 again
7998 @xref{Changing Fonts}, for the standard syntax form.
8001 @c ---------------------------------------------------------------------
8003 @node Using Symbols, Special Fonts, Font Positions, Fonts
8004 @subsection Using Symbols
8005 @cindex using symbols
8006 @cindex symbols, using
8011 A @dfn{glyph} is a graphical representation of a @dfn{character}.
8012 While a character is an abstract entity containing semantic
8013 information, a glyph is something which can be actually seen on screen
8014 or paper. It is possible that a character has multiple glyph
8015 representation forms (for example, the character `A' can be either
8016 written in a roman or an italic font, yielding two different glyphs);
8017 sometimes more than one character maps to a single glyph (this is a
8018 @dfn{ligature} -- the most common is `fi').
8021 @cindex special fonts
8024 A @dfn{symbol} is simply a named glyph. Within @code{gtroff}, all
8025 glyph names of a particular font are defined in its font file. If the
8026 user requests a glyph not available in this font, @code{gtroff} looks
8027 up an ordered list of @dfn{special fonts}. By default, the
8028 @sc{PostScript} output device supports the two special fonts @samp{SS}
8029 (slanted symbols) and @samp{S} (symbols) (the former is looked up
8030 before the latter). Other output devices use different names for
8031 special fonts. Fonts mounted with the @code{fonts} keyword in the
8032 @file{DESC} file are globally available. To install additional
8033 special fonts locally (i.e.@: for a particular font), use the
8034 @code{fspecial} request.
8036 In summary, @code{gtroff} tries the following to find a given symbol:
8040 If the symbol has been defined with the @code{char} request, use it.
8041 This hides a symbol with the same name in the current font.
8044 Check the current font.
8047 If the symbol has been defined with the @code{fchar} request, use it.
8050 Check all fonts given with the @code{fspecial} request, in the order
8051 of appearance in @code{fspecial} calls.
8054 Check all fonts given with the @code{special} request, in the order
8055 of appearance in @code{special} calls (inclusively the special fonts
8056 defined in the @file{DESC} file, which come first).
8059 As a last resort, consult all fonts loaded up to now (in the order they
8060 have been called the first time) for special fonts and check them.
8063 @xref{Font Files}, and @ref{Special Fonts}, for more details.
8065 @DefescList {\\, @lparen{}, nm, }
8066 @DefescListEnd {\\, @lbrack{}, name, @rbrack}
8067 Insert a symbol @var{name} (two-character name @var{nm}). There is no
8068 special syntax for one-character names -- the natural form
8069 @samp{\@var{n}} would collide with escapes.@footnote{Note that a
8070 one-character symbol is not the same as an input character, i.e., the
8071 character @code{a} is not the same as @code{\[a]}. By default,
8072 @code{groff} defines only a single one-character symbol, @code{\[-]};
8073 it is usually accessed as @code{\-}. On the other hand, @code{gtroff}
8074 has the special feature that @code{\[char@var{XXX}]} is the same as the
8075 input character with character code @var{XXX}. For example,
8076 @code{\[char97]} is identical to the letter @code{a} if @acronym{ASCII}
8077 encoding is active.}
8079 If @var{name} is undefined, a warning of type @samp{char} is generated,
8080 and the escape is ignored. @xref{Debugging}, for information about
8083 @cindex list of available glyphs (@cite{groff_char(7)} man page)
8084 @cindex available glyphs, list (@cite{groff_char(7)} man page)
8085 @cindex glyphs, available, list (@cite{groff_char(7)} man page)
8086 The list of available symbols is device dependent; see the
8087 @cite{groff_char(7)} man page for a complete list for the given output
8088 device. For example, say
8091 man -Tdvi groff_char > groff_char.dvi
8095 for a list using the default DVI fonts (not all versions of the
8096 @code{man} program support the @option{-T} option). If you want to
8097 use an additional macro package to change the used fonts, @code{groff}
8098 must be called directly:
8101 groff -Tdvi -mec -man groff_char.7 > groff_char.dvi
8104 @c XXX list of common symbols
8107 @Defesc {\\C, ', xxx, '}
8108 @cindex named character (@code{\C})
8109 @cindex character, named (@code{\C})
8110 Typeset the glyph named @var{xxx}.@footnote{@code{\C} is actually a
8111 misnomer since it accesses an output glyph.} Normally it is more
8112 convenient to use @code{\[@var{xxx}]}, but @code{\C} has the advantage
8113 that it is compatible with newer versions of @acronym{AT&T}
8114 @code{troff} and is available in compatibility mode.
8117 @Defesc {\\N, ', n, '}
8118 @cindex numbered glyph (@code{\N})
8119 @cindex glyph, numbered (@code{\N})
8120 @cindex @code{char} request, used with @code{\N}
8122 Typeset the glyph with code@w{ }@var{n} in the current font
8123 (@code{n}@w{ }is @strong{not} the input character code). The
8124 number @var{n}@w{ }can be any non-negative decimal integer. Most devices
8125 only have glyphs with codes between 0 and@w{ }255; the Unicode
8126 output device uses codes in the range 0--65535. If the current
8127 font does not contain a glyph with that code, special fonts are
8128 @emph{not} searched. The @code{\N} escape sequence can be
8129 conveniently used in conjunction with the @code{char} request:
8132 .char \[phone] \f[ZD]\N'37'
8137 @cindex unnamed glyphs
8138 @cindex glyphs, unnamed
8139 The code of each glyph is given in the fourth column in the font
8140 description file after the @code{charset} command. It is possible to
8141 include unnamed glyphs in the font description file by using a
8142 name of @samp{---}; the @code{\N} escape sequence is the only way to
8146 Some escape sequences directly map onto special glyphs.
8149 This is a backslash followed by the apostrophe character, @acronym{ASCII}
8150 character @code{0x27} (@acronym{EBCDIC} character @code{0x7D}). The same
8151 as @code{\[aa]}, the acute accent.
8155 This is a backslash followed by @acronym{ASCII} character @code{0x60}
8156 (@acronym{EBCDIC} character @code{0x79} usually). The same as
8157 @code{\[ga]}, the grave accent.
8161 This is the same as @code{\[-]}, the minus sign in the current font.
8164 @Defreq {cflags, n c1 c2 @dots{}}
8165 @cindex glyph properties (@code{cflags})
8166 @cindex character properties (@code{cflags})
8167 @cindex properties of glyphs (@code{cflags})
8168 @cindex properties of characters (@code{cflags})
8169 Input characters and symbols have certain properties associated
8170 with it.@footnote{Note that the output glyphs themselves don't have
8171 such properties. For @code{gtroff}, a glyph is a numbered box with
8172 a given width, depth, and height, nothing else. All manipulations
8173 with the @code{cflags} request work on the input level.} These
8174 properties can be modified with the @code{cflags} request. The
8175 first argument is the sum of the desired flags and the remaining
8176 arguments are the characters or symbols to have those properties.
8177 It is possible to omit the spaces between the characters or symbols.
8181 @cindex end-of-sentence characters
8182 @cindex characters, end-of-sentence
8183 The character ends sentences (initially characters @samp{.?!} have this
8187 @cindex hyphenating characters
8188 @cindex characters, hyphenation
8189 Lines can be broken before the character (initially no characters have
8193 @cindex @code{hy} glyph, and @code{cflags}
8194 @cindex @code{em} glyph, and @code{cflags}
8195 Lines can be broken after the character (initially the character
8196 @samp{-} and the symbols @samp{\(hy} and @samp{\(em} have this property).
8199 @cindex overlapping characters
8200 @cindex characters, overlapping
8201 @cindex @code{ul} glyph, and @code{cflags}
8202 @cindex @code{rn} glyph, and @code{cflags}
8203 @cindex @code{ru} glyph, and @code{cflags}
8204 The character overlaps horizontally (initially the symbols
8205 @samp{\(ul\(rn\(ru} have this property).
8208 @cindex @code{br} glyph, and @code{cflags}
8209 The character overlaps vertically (initially symbol @samp{\(br} has
8213 @cindex transparent characters
8214 @cindex character, transparent
8215 @cindex @code{"}, at end of sentence
8216 @cindex @code{'}, at end of sentence
8217 @cindex @code{)}, at end of sentence
8218 @cindex @code{]}, at end of sentence
8219 @cindex @code{*}, at end of sentence
8220 @cindex @code{dg} glyph, at end of sentence
8221 @cindex @code{rq} glyph, at end of sentence
8222 An end-of-sentence character followed by any number of characters with
8223 this property is treated as the end of a sentence if followed by a
8224 newline or two spaces; in other words the character is
8225 @dfn{transparent} for the purposes of end-of-sentence recognition --
8226 this is the same as having a zero space factor in @TeX{} (initially
8227 characters @samp{"')]*} and the symbols @samp{\(dg\(rq} have this
8232 @DefreqList {char, g [@Var{string}]}
8233 @DefreqListEnd {fchar, g [@Var{string}]}
8234 @cindex defining character (@code{char})
8235 @cindex character, defining (@code{char})
8236 @cindex creating new characters (@code{char})
8237 @cindex defining symbol (@code{char})
8238 @cindex symbol, defining (@code{char})
8239 @cindex defining glyph (@code{char})
8240 @cindex glyph, defining (@code{char})
8241 @cindex escape character, while defining glyph
8242 @cindex character, escape, while defining glyph
8243 @cindex @code{tr} request, and glyph definitions
8244 @cindex @code{cp} request, and glyph definitions
8245 @cindex @code{rc} request, and glyph definitions
8246 @cindex @code{lc} request, and glyph definitions
8247 @cindex @code{\l}, and glyph definitions
8248 @cindex @code{\L}, and glyph definitions
8249 @cindex @code{\&}, and glyph definitions
8250 @cindex @code{\e}, and glyph definitions
8251 @cindex @code{hcode} request, and glyph definitions
8252 Define a new glyph@w{ }@var{g} to be @var{string} (which can be
8253 empty).@footnote{@code{char} is a misnomer since an output glyph is
8254 defined.} Every time glyph@w{ }@var{g} needs to be printed,
8255 @var{string} is processed in a temporary environment and the result is
8256 wrapped up into a single object. Compatibility mode is turned off and
8257 the escape character is set to @samp{\} while @var{string} is being
8258 processed. Any emboldening, constant spacing or track kerning is
8259 applied to this object rather than to individual characters in
8262 A glyph defined by this request can be used just
8263 like a normal glyph provided by the output device. In particular,
8264 other characters can be translated to it with the @code{tr} or
8265 @code{trin} requests; it can be made the leader character by the
8266 @code{lc} request; repeated patterns can be drawn with the glyph
8267 using the @code{\l} and @code{\L} escape sequences; words containing
8268 the glyph can be hyphenated correctly if the @code{hcode} request
8269 is used to give the glyph's symbol a hyphenation code.
8271 There is a special anti-recursion feature: Use of @code{g} within
8272 the glyph's definition is handled like normal characters and symbols
8273 not defined with @code{char}.
8275 Note that the @code{tr} and @code{trin} requests take precedence if
8276 @code{char} accesses the same symbol.
8290 The @code{fchar} request defines a fallback glyph:
8291 @code{gtroff} only checks for glyphs defined with @code{fchar}
8292 if it cannot find the glyph in the current font.
8293 @code{gtroff} carries out this test before checking special fonts.
8296 @Defreq {rchar, c1 c2 @dots{}}
8297 @cindex removing glyph definition (@code{rchar})
8298 @cindex glyph, removing definition (@code{rchar})
8299 Remove the definitions of glyphs @var{c1}, @var{c2},@w{
8300 }@enddots{} This undoes the effect of a @code{char} or @code{fchar}
8303 It is possible to omit the whitespace between arguments.
8306 @xref{Special Characters}.
8308 @c ---------------------------------------------------------------------
8310 @node Special Fonts, Artificial Fonts, Using Symbols, Fonts
8311 @subsection Special Fonts
8312 @cindex special fonts
8313 @cindex fonts, special
8315 Special fonts are those that @code{gtroff} searches
8316 when it cannot find the requested glyph in the current font.
8317 The Symbol font is usually a special font.
8319 @code{gtroff} provides the following two requests to add more special
8320 fonts. @xref{Using Symbols}, for a detailed description of the glyph
8321 searching mechanism in @code{gtroff}.
8323 Usually, only non-TTY devices have special fonts.
8325 @DefreqList {special, s1 s2 @dots{}}
8326 @DefreqListEnd {fspecial, f s1 s2 @dots{}}
8329 Use the @code{special} request to define special fonts. They are
8330 appended to the list of global special fonts in the given order.
8331 The first entries in this list are the fonts defined with the
8332 @code{fonts} command in the @file{DESC} file which are marked as
8333 special in the corresponding font description files.
8335 Use the @code{fspecial} request to designate special fonts
8336 only when font@w{ }@var{f} font is active. They are appended to the
8337 list of special fonts for @var{f} in the given order. Initially, this
8341 @c ---------------------------------------------------------------------
8343 @node Artificial Fonts, Ligatures and Kerning, Special Fonts, Fonts
8344 @subsection Artificial Fonts
8345 @cindex artificial fonts
8346 @cindex fonts, artificial
8348 There are a number of requests and escapes for artificially creating
8349 fonts. These are largely vestiges of the days when output devices
8350 did not have a wide variety of fonts, and when @code{nroff} and
8351 @code{troff} were separate programs. Most of them are no longer
8352 necessary in GNU @code{troff}. Nevertheless, they are supported.
8354 @DefescList {\\H, ', height, '}
8355 @DefescItem {\\H, ', @t{+}@Var{height}, '}
8356 @DefescListEnd {\\H, ', @t{-}@Var{height}, '}
8357 @cindex changing the font height (@code{\H})
8358 @cindex font height, changing (@code{\H})
8359 @cindex height, font, changing (@code{\H})
8360 Change (increment, decrement) the height of the current font, but not
8361 the width. If @var{height} is zero, restore the original height.
8362 Default scaling indicator is @samp{z}.
8364 Currently, only the @option{-Tps} device supports this feature.
8366 Note that @code{\H} doesn't produce an input token in @code{gtroff}.
8367 As a consequence, it can be used in requests like @code{mc} (which
8368 expects a single character as an argument) to change the font on
8375 In compatibility mode, @code{gtroff} behaves differently: If an
8376 increment or decrement is used, it is always taken relative to the
8377 current point size and not relative to the previously selected font
8382 \H'+5'test \H'+5'test
8386 prints the word @samp{test} twice with the same font height (five
8387 points larger than the current font size).
8390 @DefescList {\\S, ', slant, '}
8391 @cindex changing the font slant (@code{\S})
8392 @cindex font slant, changing (@code{\S})
8393 @cindex slant, font, changing (@code{\S})
8394 Slant the current font by @var{slant} degrees. Positive values slant
8397 Currently, only the @option{-Tps} device supports this feature.
8399 Note that @code{\S} doesn't produce an input token in @code{gtroff}.
8400 As a consequence, it can be used in requests like @code{mc} (which
8401 expects a single character as an argument) to change the font on
8408 This request is incorrectly documented in the original @acronym{UNIX}
8409 troff manual; the slant is always set to an absolute value.
8412 @Defreq {ul, [@Var{lines}]}
8413 @cindex underlining (@code{ul})
8414 The @code{ul} request normally underlines subsequent lines if a TTY
8415 output device is used. Otherwise, the lines are printed in italics
8416 (only the term `underlined' is used in the following). The single
8417 argument is the number of input lines to be underlined; with no
8418 argument, the next line is underlined. If @var{lines} is zero or
8419 negative, stop the effects of @code{ul} (if it was active). Requests
8420 and empty lines do not count for computing the number of underlined
8421 input lines, even if they produce some output like @code{tl}. Lines
8422 inserted by macros (e.g.@: invoked by a trap) do count.
8424 At the beginning of @code{ul}, the current font is stored and the
8425 underline font is activated. Within the span of a @code{ul} request,
8426 it is possible to change fonts, but after the last line affected by
8427 @code{ul} the saved font is restored.
8429 This number of lines still to be underlined is associated with the
8430 current environment (@pxref{Environments}). The underline font can be
8431 changed with the @code{uf} request.
8433 @c XXX @xref should be changed to grotty
8435 @c @xref{Troff and Nroff Mode}, for a discussion how underlining is
8436 @c implemented in for TTY output devices, and which problems can arise.
8438 The @code{ul} request does not underline spaces.
8441 @Defreq {cu, [@Var{lines}]}
8442 @cindex continuous underlining (@code{cu})
8443 @cindex underlining, continuous (@code{cu})
8444 The @code{cu} request is similar to @code{ul} but underlines spaces as
8445 well (if a TTY output device is used).
8449 @cindex underline font (@code{uf})
8450 @cindex font for underlining (@code{uf})
8451 Set the underline font (globally) used by @code{ul} and @code{cu}. By
8452 default, this is the font at position@w{ }2. @var{font} can be either
8453 a non-negative font position or the name of a font.
8456 @DefreqList {bd, font [@Var{offset}]}
8457 @DefreqItem {bd, font1 font2 [@Var{offset}]}
8459 @cindex imitating bold face (@code{bd})
8460 @cindex bold face, imitating (@code{bd})
8461 Artificially create a bold font by printing each glyph twice,
8464 Two syntax forms are available.
8468 Imitate a bold font unconditionally. The first argument specifies the
8469 font to embolden, and the second is the number of basic units, minus
8470 one, by which the two glyphs are offset. If the second argument is
8471 missing, emboldening is turned off.
8473 @var{font} can be either a non-negative font position or the name of a
8476 @var{offset} is available in the @code{.b} read-only register if a
8477 special font is active; in the @code{bd} request, its default unit is
8480 @cindex @code{fspecial} request, and imitating bold
8482 @cindex embolding of special fonts
8483 @cindex special fonts, emboldening
8485 Imitate a bold form conditionally. Embolden @var{font1} by
8486 @var{offset} only if font @var{font2} is the current font. This
8487 command can be issued repeatedly to set up different emboldening
8488 values for different current fonts. If the second argument is
8489 missing, emboldening is turned off for this particular current font.
8491 This affects special fonts only (either set up with the @code{special}
8492 command in font files or with the @code{fspecial} request).
8496 @Defreq {cs, font [@Var{width} [@Var{em-size}]]}
8497 @cindex constant glyph space mode (@code{cs})
8498 @cindex mode for constant glyph space (@code{cs})
8499 @cindex glyph, constant space
8500 @cindex @code{ps} request, and constant glyph space mode
8501 Switch to and from @dfn{constant glyph space mode}. If activated, the
8502 width of every glyph is @math{@var{width}/36} ems. The em size is
8503 given absolutely by @var{em-size}; if this argument is missing, the em
8504 value is taken from the current font size (as set with the @code{ps}
8505 request) when the font is effectively in use. Without second and
8506 third argument, constant glyph space mode is deactivated.
8508 Default scaling indicator for @var{em-size} is @samp{z}; @var{width} is
8512 @c ---------------------------------------------------------------------
8514 @node Ligatures and Kerning, , Artificial Fonts, Fonts
8515 @subsection Ligatures and Kerning
8516 @cindex ligatures and kerning
8517 @cindex kerning and ligatures
8519 Ligatures are groups of characters that are run together, i.e, producing
8520 a single glyph. For example, the letters `f' and `i' can form a
8521 ligature `fi' as in the word `file'. This produces a cleaner look
8522 (albeit subtle) to the printed output. Usually, ligatures are not
8523 available in fonts for TTY output devices.
8525 Most @sc{PostScript} fonts support the fi and fl ligatures. The C/A/T
8526 typesetter that was the target of @acronym{AT&T} @code{troff} also
8527 supported `ff', `ffi', and `ffl' ligatures. Advanced typesetters or
8528 `expert' fonts may include ligatures for `ft' and `ct', although GNU
8529 @code{troff} does not support these (yet).
8531 @DefreqList {lg, [@Var{flag}]}
8532 @DefregListEnd {.lg}
8533 @cindex activating ligatures (@code{lg})
8534 @cindex ligatures, activating (@code{lg})
8535 @cindex ligatures enabled register (@code{.lg})
8536 Switch the ligature mechanism on or off; if the parameter is non-zero
8537 or missing, ligatures are enabled, otherwise disabled. Default is on.
8538 The current ligature mode can be found in the read-only number register
8539 @code{.lg} (set to 1 or@w{ }2 if ligatures are enabled, 0@w{ }otherwise).
8541 Setting the ligature mode to@w{ }2 enables the two-character ligatures
8542 (fi, fl, and ff) and disables the three-character ligatures (ffi and
8546 @dfn{Pairwise kerning} is another subtle typesetting mechanism that
8547 modifies the distance between a glyph pair to improve readability.
8548 In most cases (but not always) the distance is decreased.
8550 For example, compare the combination of the letters `V' and `A'. With
8551 kerning, `VA' is printed. Without kerning it appears as `V@w{}A'.
8553 Typewriter-like fonts and fonts for terminals where all glyphs
8554 have the same width don't use kerning.
8556 @DefreqList {kern, [@Var{flag}]}
8557 @DefregListEnd {.kern}
8558 @cindex activating kerning (@code{kern})
8559 @cindex kerning, activating (@code{kern})
8560 @cindex kerning enabled register (@code{.kern})
8561 Switch kerning on or off. If the parameter is non-zero or missing,
8562 enable pairwise kerning, otherwise disable it. The read-only number
8563 register @code{.kern} is set to@w{ }1 if pairwise kerning is enabled,
8566 @cindex zero width space character (@code{\&})
8567 @cindex character, zero width space (@code{\&})
8568 @cindex space character, zero width (@code{\&})
8569 If the font description file contains pairwise kerning information,
8570 glyphs from that font are kerned. Kerning between two glyphs
8571 can be inhibited by placing @code{\&} between them: @samp{V\&A}.
8573 @xref{Font File Format}.
8576 @cindex track kerning
8577 @cindex kerning, track
8578 @dfn{Track kerning} expands or reduces the space between glyphs.
8579 This can be handy, for example, if you need to squeeze a long word
8580 onto a single line or spread some text to fill a narrow column. It
8581 must be used with great care since it is usually considered bad
8582 typography if the reader notices the effect.
8584 @Defreq {tkf, f s1 n1 s2 n2}
8585 @cindex activating track kerning (@code{tkf})
8586 @cindex track kerning, activating (@code{tkf})
8587 Enable track kerning for font@w{ }@var{f}. If the current font is@w{
8588 }@var{f} the width of every glyph is increased by an amount
8589 between @var{n1} and @var{n2} (@var{n1}, @var{n2} can be negative); if
8590 the current point size is less than or equal to @var{s1} the width is
8591 increased by @var{n1}; if it is greater than or equal to @var{s2} the
8592 width is increased by @var{n2}; if the point size is greater than or
8593 equal to @var{s1} and less than or equal to @var{s2} the increase in
8594 width is a linear function of the point size.
8596 The default scaling indicator is @samp{z} for @var{s1} and @var{s2},
8597 @samp{p} for @var{n1} and @var{n2}.
8599 Note that the track kerning amount is added even to the rightmost glyph
8600 in a line; for large values it is thus recommended to increase the line
8601 length by the same amount to compensate it.
8604 Sometimes, when typesetting letters of different fonts, more or less
8605 space at such boundaries are needed. There are two escapes to help
8609 @cindex italic correction (@code{\/})
8610 @cindex correction, italic (@code{\/})
8611 @cindex correction between italic and roman glyph (@code{\/}, @code{\,})
8612 @cindex roman glyph, correction after italic glyph (@code{\/})
8613 @cindex italic glyph, correction before roman glyph (@code{\/})
8614 @cindex glyph, italic correction (@code{\/})
8615 Increase the width of the preceding glyph so that the spacing
8616 between that glyph and the following glyph is correct if the
8617 following glyph is a roman glyph. For example, if an
8618 italic@w{ }@code{f} is immediately followed by a roman right
8619 parenthesis, then in many fonts the top right portion of the@w{ }@code{f}
8620 overlaps the top left of the right parenthesis. Use this escape
8621 sequence whenever an italic glyph is immediately followed by a
8622 roman glyph without any intervening space. This small amount of
8623 space is also called @dfn{italic correction}.
8629 @result{} {@it f}@r{)}
8631 @result{} @i{f}@r{)}
8637 @Defesc {\\\,, , , }
8638 @cindex left italic correction (@code{\,})
8639 @cindex correction, left italic (@code{\,})
8640 @cindex glyph, left italic correction (@code{\,})
8641 @cindex roman glyph, correction before italic glyph (@code{\,})
8642 @cindex italic glyph, correction after roman glyph (@code{\,})
8643 Modify the spacing of the following glyph so that the spacing
8644 between that glyph and the preceding glyph is correct if the
8645 preceding glyph is a roman glyph. Use this escape sequence
8646 whenever a roman glyph is immediately followed by an italic
8647 glyph without any intervening space. In analogy to above, this
8648 space could be called @dfn{left italic correction}, but this term
8655 @result{} @r{q}@i{f}
8657 @result{} @r{q}@math{@ptexcomma}@i{f}
8664 Insert a zero-width character, which is invisible. Its intended use
8665 is to stop interaction of a character with its surrounding.
8669 It prevents the insertion of extra space after an end-of-sentence
8675 @result{} Test. Test.
8678 @result{} Test. Test.
8682 It prevents interpretation of a control character at the beginning of
8687 @result{} warning: `Test' not defined
8693 It prevents kerning between two glyphs.
8701 @result{} @r{V@w{}A}
8707 It is needed to map an arbitrary character to nothing in the @code{tr}
8708 request (@pxref{Character Translations}).
8713 This escape is similar to @code{\&} except that it behaves like a
8714 character declared with the @code{cflags} request to be transparent
8715 for the purposes of an end-of-sentence character.
8717 Its main usage is in macro definitions to protect against arguments
8718 starting with a control character.
8730 @result{}This is a test.' This is a test.
8734 @result{}This is a test.' This is a test.
8739 @c =====================================================================
8741 @node Sizes, Strings, Fonts, gtroff Reference
8747 @cindex size of type
8748 @cindex vertical spacing
8749 @cindex spacing, vertical
8750 @code{gtroff} uses two dimensions with each line of text, type size
8751 and vertical spacing. The @dfn{type size} is approximately the height
8752 of the tallest glyph.@footnote{This is usually the parenthesis.
8753 Note that in most cases the real dimensions of the glyphs in a font
8754 are @emph{not} related to its type size! For example, the standard
8755 @sc{PostScript} font families `Times Roman', `Helvetica', and
8756 `Courier' can't be used together at 10@dmn{pt}; to get acceptable
8757 output, the size of `Helvetica' has to be reduced by one point, and
8758 the size of `Courier' must be increased by one point.} @dfn{Vertical
8759 spacing} is the amount of space @code{gtroff} allows for a line of
8760 text; normally, this is about 20%@w{ }larger than the current type
8761 size. Ratios smaller than this can result in hard-to-read text;
8762 larger than this, it spreads the text out more vertically (useful for
8763 term papers). By default, @code{gtroff} uses 10@w{ }point type on
8764 12@w{ }point spacing.
8767 The difference between type size and vertical spacing is known, by
8768 typesetters, as @dfn{leading} (this is pronounced `ledding').
8771 * Changing Type Sizes::
8772 * Fractional Type Sizes::
8775 @c ---------------------------------------------------------------------
8777 @node Changing Type Sizes, Fractional Type Sizes, Sizes, Sizes
8778 @subsection Changing Type Sizes
8780 @DefreqList {ps, [@Var{size}]}
8781 @DefreqItem {ps, @t{+}@Var{size}}
8782 @DefreqItem {ps, @t{-}@Var{size}}
8783 @DefescItem {\\s, , size, }
8785 @cindex changing type sizes (@code{ps}, @code{\s})
8786 @cindex type sizes, changing (@code{ps}, @code{\s})
8787 @cindex point sizes, changing (@code{ps}, @code{\s})
8788 Use the @code{ps} request or the @code{\s} escape to change (increase,
8789 decrease) the type size (in points). Specify @var{size} as either an
8790 absolute point size, or as a relative change from the current size.
8791 The size@w{ }0, or no argument, goes back to the previous size.
8793 Default scaling indicator of @code{size} is @samp{z}. If @code{size}
8794 is zero or negative, it is set to 1@dmn{u}.
8796 @cindex type size registers (@code{.s}, @code{.ps})
8797 @cindex point size registers (@code{.s}, @code{.ps})
8798 The read-only number register @code{.s} returns the point size in
8799 points as a decimal fraction. This is a string. To get the point
8800 size in scaled points, use the @code{.ps} register instead.
8802 @code{.s} is associated with the current environment
8803 (@pxref{Environments}).
8810 wink, wink, \s+2nudge, nudge,\s+8 say no more!
8814 The @code{\s} escape may be called in a variety of ways. Much like
8815 other escapes there must be a way to determine where the argument ends
8816 and the text begins. Any of the following forms are valid:
8820 Set the point size to @var{n}@w{ }points. @var{n}@w{ }must be either
8821 0 or in the range 4 to@w{ }39.
8825 Increase or decrease the point size by @var{n}@w{ }points. @var{n}@w{
8826 }must be exactly one digit.
8829 Set the point size to @var{nn}@w{ }points. @var{nn} must be exactly
8836 Increase or decrease the point size by @var{nn}@w{ }points. @var{nn}
8837 must be exactly two digits.
8840 Note that @code{\s} doesn't produce an input token in @code{gtroff}.
8841 As a consequence, it can be used in requests like @code{mc} (which
8842 expects a single character as an argument) to change the font on
8849 @xref{Fractional Type Sizes}, for yet another syntactical form of
8850 using the @code{\s} escape.
8853 @Defreq {sizes, s1 s2 @dots{} sn [0]}
8854 Some devices may only have certain permissible sizes, in which case
8855 @code{gtroff} rounds to the nearest permissible size.
8856 The @file{DESC} file specifies which sizes are permissible for the device.
8858 Use the @code{sizes} request to change the permissible sizes
8859 for the current output device.
8860 Arguments are in scaled points;
8861 the @code{sizescale} line in the
8862 @file{DESC} file for the output device
8863 provides the scaling factor.
8864 For example, if the scaling factor is 1000,
8865 then the value 12000 is 12@w{ }points.
8867 Each argument can be a single point size (such as @samp{12000}),
8868 or a range of sizes (such as @samp{4000-72000}).
8869 You can optionally end the list with a zero.
8872 @DefreqList {vs, [@Var{space}]}
8873 @DefreqItem {vs, @t{+}@Var{space}}
8874 @DefreqItem {vs, @t{-}@Var{space}}
8876 @cindex changing vertical line spacing (@code{vs})
8877 @cindex vertical line spacing, changing (@code{vs})
8878 @cindex vertical line spacing register (@code{.v})
8879 Change (increase, decrease) the vertical spacing by @var{space}. The
8880 default scaling indicator is @samp{p}.
8882 If @code{vs} is called without an argument, the vertical spacing is
8883 reset to the previous value before the last call to @code{vs}.
8885 @cindex @code{.V} register, and @code{vs}
8886 @code{gtroff} creates a warning of type @samp{range} if @var{space} is
8887 zero or negative; the vertical spacing is then set to the vertical
8888 resolution (as given in the @code{.V} register).
8890 The read-only number register @code{.v} contains the current vertical
8891 spacing; it is associated with the current environment
8892 (@pxref{Environments}).
8895 @cindex vertical line spacing, effective value
8896 The effective vertical line spacing consists of four components.
8900 The vertical line spacing as set with the @code{vs} request.
8902 @cindex post-vertical line spacing
8903 @cindex line spacing, post-vertical (@code{pvs})
8905 The @dfn{post-vertical line spacing} as set with the @code{pvs} request.
8906 This is vertical space which will be added after a line has been
8909 @cindex extra pre-vertical line space (@code{\x})
8910 @cindex line space, extra pre-vertical (@code{\x})
8912 The @dfn{extra pre-vertical line space} as set with the @code{\x} request,
8913 using a negative value. This is vertical space which will be added once
8914 before the current line has been output.
8916 @cindex extra post-vertical line space (@code{\x})
8917 @cindex line space, extra post-vertical (@code{\x})
8919 The @dfn{extra post-vertical line space} as set with the @code{\x} request,
8920 using a positive value. This is vertical space which will be added once
8921 after the current line has been output.
8924 @cindex double-spacing (@code{vs}, @code{pvs})
8925 It is usually better to use @code{vs} or @code{pvs} instead of @code{ls}
8926 to produce double-spaced documents: @code{vs} and @code{pvs} have a finer
8927 granularity for the inserted vertical space compared to @code{ls};
8928 furthermore, certain preprocessors assume single-spacing.
8930 @xref{Manipulating Spacing}, for more details on the @code{\x} escape
8931 and the @code{ls} request.
8933 @DefreqList {pvs, [@Var{space}]}
8934 @DefreqItem {pvs, @t{+}@Var{space}}
8935 @DefreqItem {pvs, @t{-}@Var{space}}
8936 @DefregListEnd {.pvs}
8937 @cindex @code{ls} request, alternative to (@code{pvs})
8938 @cindex post-vertical line spacing, changing (@code{pvs})
8939 @cindex post-vertical line spacing register (@code{.pvs})
8940 Change (increase, decrease) the post-vertical spacing by
8941 @var{space}. The default scaling indicator is @samp{p}.
8943 If @code{pvs} is called without an argument, the post-vertical spacing is
8944 reset to the previous value before the last call to @code{pvs}.
8946 @code{gtroff} creates a warning of type @samp{range} if @var{space} is
8947 zero or negative; the vertical spacing is then set to zero.
8949 The read-only number register @code{.pvs} contains the current
8950 post-vertical spacing; it is associated with the current environment
8951 (@pxref{Environments}).
8955 @c ---------------------------------------------------------------------
8957 @node Fractional Type Sizes, , Changing Type Sizes, Sizes
8958 @subsection Fractional Type Sizes
8959 @cindex fractional type sizes
8960 @cindex fractional point sizes
8961 @cindex type sizes, fractional
8962 @cindex point sizes, fractional
8963 @cindex sizes, fractional
8965 @cindex @code{s} unit
8966 @cindex unit, @code{s}
8967 @cindex @code{z} unit
8968 @cindex unit, @code{z}
8969 @cindex @code{ps} request, with fractional type sizes
8970 @cindex @code{cs} request, with fractional type sizes
8971 @cindex @code{tkf} request, with fractional type sizes
8972 @cindex @code{\H}, with fractional type sizes
8973 @cindex @code{\s}, with fractional type sizes
8974 A @dfn{scaled point} is equal to @math{1/@var{sizescale}} points,
8975 where @var{sizescale} is specified in the @file{DESC} file (1@w{ }by
8976 default). There is a new scale indicator @samp{z} which has the
8977 effect of multiplying by @var{sizescale}. Requests and escape
8978 sequences in @code{gtroff} interpret arguments that represent a point
8979 size as being in units of scaled points, but they evaluate each such
8980 argument using a default scale indicator of @samp{z}. Arguments
8981 treated in this way are the argument to the @code{ps} request, the
8982 third argument to the @code{cs} request, the second and fourth
8983 arguments to the @code{tkf} request, the argument to the @code{\H}
8984 escape sequence, and those variants of the @code{\s} escape sequence
8985 that take a numeric expression as their argument (see below).
8987 For example, suppose @var{sizescale} is@w{ }1000; then a scaled point
8988 is equivalent to a millipoint; the request @w{@samp{.ps 10.25}} is
8989 equivalent to @w{@samp{.ps 10.25z}} and thus sets the point size to
8990 10250@w{ }scaled points, which is equal to 10.25@w{ }points.
8992 @code{gtroff} disallows the use of the @samp{z} scale indicator in
8993 instances where it would make no sense, such as a numeric
8994 expression whose default scale indicator was neither @samp{u} nor
8995 @samp{z}. Similarly it would make
8996 no sense to use a scaling indicator other than @samp{z} or @samp{u} in a
8997 numeric expression whose default scale indicator was @samp{z}, and so
8998 @code{gtroff} disallows this as well.
9000 There is also new scale indicator @samp{s} which multiplies by the
9001 number of units in a scaled point. So, for example, @samp{\n[.ps]s} is
9002 equal to @samp{1m}. Be sure not to confuse the @samp{s} and @samp{z}
9006 A read-only number register returning the point size in scaled points.
9008 @code{.ps} is associated with the current environment
9009 (@pxref{Environments}).
9013 @DefregListEnd {.sr}
9014 @cindex last-requested point size registers (@code{.psr}, @code{.sr})
9015 @cindex point size registers, last-requested (@code{.psr}, @code{.sr})
9016 @cindex @code{.ps} register, in comparison with @code{.psr}
9017 @cindex @code{.s} register, in comparison with @code{.sr}
9018 The last-requested point size in scaled points is contained in the
9019 @code{.psr} read-only number register. The last requested point size
9020 in points as a decimal fraction can be found in @code{.sr}. This is a
9021 string-valued read-only number register.
9023 Note that the requested point sizes are device-independent, whereas
9024 the values returned by the @code{.ps} and @code{.s} registers are not.
9025 For example, if a point size of 11@dmn{pt} is requested, and a
9026 @code{sizes} request (or a @code{sizescale} line in a @file{DESC} file)
9027 specifies 10.95@dmn{pt} instead, this value is actually used.
9029 Both registers are associated with the current environment
9030 (@pxref{Environments}).
9033 The @code{\s} escape has the following syntax for working with
9034 fractional type sizes:
9039 Set the point size to @var{n}@w{ }scaled points; @var{n}@w{ }is a numeric
9040 expression with a default scale indicator of @samp{z}.
9050 Increase or or decrease the point size by @var{n}@w{ }scaled points;
9051 @var{n}@w{ }is a numeric expression with a default scale indicator of
9058 @c =====================================================================
9060 @node Strings, Conditionals and Loops, Sizes, gtroff Reference
9064 @code{gtroff} has string variables, which are entirely for user
9065 convenience (i.e.@: there are no built-in strings exept @code{.T}, but
9066 even this is a read-write string variable).
9068 @DefreqList {ds, name [@Var{string}]}
9069 @DefreqItem {ds1, name [@Var{string}]}
9070 @DefescItem {\\*, , n, }
9071 @DefescItem {\\*, @lparen{}, nm, }
9072 @DefescListEnd {\\*, @lbrack{}, name arg1 arg2 @dots{}, @rbrack{}}
9073 @cindex string interpolation (@code{\*})
9074 @cindex string expansion (@code{\*})
9075 @cindex interpolation of strings (@code{\*})
9076 @cindex expansion of strings (@code{\*})
9077 @cindex string arguments
9078 @cindex arguments, of strings
9079 Define and access a string variable @var{name} (one-character name@w{
9080 }@var{n}, two-character name @var{nm}). If @var{name} already exists,
9081 @code{ds} overwrites the previous definition. Only the syntax form
9082 using brackets can take arguments which are handled identically to
9083 macro arguments; the single exception is that a closing bracket as an
9084 argument must be enclosed in double quotes. @xref{Request Arguments},
9085 and @ref{Parameters}.
9092 This is \*[foo nice].
9093 @result{} This is a nice test.
9096 The @code{\*} escape @dfn{interpolates} (expands in-place) a
9097 previously-defined string variable. To be more precise, the stored
9098 string is pushed onto the input stack which is then parsed by
9099 @code{gtroff}. Similar to number registers, it is possible to nest
9100 strings, i.e. string variables can be called within string variables.
9102 If the string named by the @code{\*} escape does not exist, it is
9103 defined as empty, and a warning of type @samp{mac} is emitted (see
9104 @ref{Debugging}, for more details).
9106 @cindex comments, with @code{ds}
9107 @cindex @code{ds} request, and comments
9108 @strong{Caution:} Unlike other requests, the second argument to the
9109 @code{ds} request takes up the entire line including trailing spaces.
9110 This means that comments on a line with such a request can introduce
9111 unwanted space into a string.
9114 .ds UX \s-1UNIX\s0\u\s-3tm\s0\d \" UNIX trademark
9118 Instead the comment should be put on another line or have the comment
9119 escape adjacent with the end of the string.
9122 .ds UX \s-1UNIX\s0\u\s-3tm\s0\d\" UNIX trademark
9125 @cindex trailing quotes
9126 @cindex quotes, trailing
9127 @cindex leading spaces with @code{ds}
9128 @cindex spaces with @code{ds}
9129 @cindex @code{ds} request, and leading spaces
9130 To produce leading space the string can be started with a double
9131 quote. No trailing quote is needed; in fact, any trailing quote is
9132 included in your string.
9135 .ds sign " Yours in a white wine sauce,
9138 @cindex multi-line strings
9139 @cindex strings, multi-line
9140 @cindex newline character, in strings, escaping
9141 @cindex escaping newline characters, in strings
9142 Strings are not limited to a single line of text. A string can span
9143 several lines by escaping the newlines with a backslash. The
9144 resulting string is stored @emph{without} the newlines.
9147 .ds foo lots and lots \
9148 of text are on these \
9152 It is not possible to have real newlines in a string. To put a single
9153 double quote character into a string, use two consecutive double quote
9156 The @code{ds1} request turns off compatibility mode
9157 while interpreting a string. To be more precise, a @dfn{compatibility
9158 save} input token is inserted at the beginning of the string, and a
9159 @dfn{compatibility restore} input token at the end.
9163 .ds aa The value of xxx is \\n[xxx].
9164 .ds1 bb The value of xxx ix \\n[xxx].
9169 @result{} warning: number register `[' not defined
9170 @result{} The value of xxx is 0xxx].
9172 @result{} The value of xxx ix 12345.
9175 @cindex name space, common, of macros, diversions, and strings
9176 @cindex common name space of macros, diversions, and strings
9177 @cindex macros, shared name space with strings and diversions
9178 @cindex strings, shared name space with macros and diversions
9179 @cindex diversions, shared name space with macros and strings
9180 Strings, macros, and diversions (and boxes) share the same name space.
9181 Internally, even the same mechanism is used to store them. This has
9182 some interesting consequences. For example, it is possible to call a
9183 macro with string syntax and vice versa.
9190 @result{} This is a funny test.
9192 .ds yyy a funny test
9195 @result{} This is a funny test.
9198 Diversions and boxes can be also called with string syntax.
9200 Another consequence is that you can copy one-line diversions or boxes
9208 .ds yyy This is \*[xxx]\c
9210 @result{} @r{This is a }@i{test}.
9214 As the previous example shows, it is possible to store formatted
9215 output in strings. The @code{\c} escape prevents the insertion of an
9216 additional blank line in the output.
9218 Copying diversions longer than a single output line produces
9228 .ds yyy This is \*[xxx]\c
9230 @result{} test This is a funny.
9233 Usually, it is not predictable whether a diversion contains one or
9234 more output lines, so this mechanism should be avoided. With
9235 @acronym{UNIX} @code{troff}, this was the only solution to strip off a
9236 final newline from a diversion. Another disadvantage is that the
9237 spaces in the copied string are already formatted, making them
9238 unstretchable. This can cause ugly results.
9240 @cindex stripping final newline in diversions
9241 @cindex diversion, stripping final newline
9242 @cindex final newline, stripping in diversions
9243 @cindex newline, final, stripping in diversions
9244 @cindex horizontal space, unformatting
9245 @cindex space, horizontal, unformatting
9246 @cindex unformatting horizontal space
9247 A clean solution to this problem is available in GNU @code{troff},
9248 using the requests @code{chop} to remove the final newline of a
9249 diversion, and @code{unformat} to make the horizontal spaces
9262 @result{} This is a funny test.
9265 @xref{Gtroff Internals}, for more information.
9268 @DefreqList {as, name [@Var{string}]}
9269 @DefreqListEnd {as1, name [@Var{string}]}
9270 @cindex appending to a string (@code{as})
9271 @cindex string, appending (@code{as})
9272 The @code{as} request is similar to @code{ds} but appends @var{string}
9273 to the string stored as @var{name} instead of redefining it. If
9274 @var{name} doesn't exist yet, it is created.
9277 .as sign " with shallots, onions and garlic,
9280 The @code{as1} request is similar to @code{as}, but compatibility mode
9281 is switched off while the appended string is interpreted. To be more
9282 precise, a @dfn{compatibility save} input token is inserted at the
9283 beginning of the appended string, and a @dfn{compatibility restore}
9284 input token at the end.
9287 Rudimentary string manipulation routines are given with the next two
9290 @Defreq {substring, str n1 [@Var{n2}]}
9291 @cindex substring (@code{substring})
9292 Replace the string named @var{str} with the substring
9293 defined by the indices @var{n1} and@w{ }@var{n2}. The first character
9294 in the string has index@w{ }0. If @var{n2} is omitted, it is taken to
9295 be equal to the string's length. If the index value @var{n1} or
9296 @var{n2} is negative, it is counted from the end of the
9297 string, going backwards: The last character has index@w{ }@minus{}1, the
9298 character before the last character has index@w{ }@minus{}2, etc.
9308 @Defreq {length, reg str}
9309 @cindex length of a string (@code{length})
9310 @cindex string, length of (@code{length})
9311 Compute the number of characters of @var{str} and return it in the
9312 number register @var{reg}. If @var{reg} doesn't exist, it is created.
9313 @code{str} is read in copy mode.
9316 .ds xxx abcd\h'3i'efgh
9324 @cindex renaming request (@code{rn})
9325 @cindex request, renaming (@code{rn})
9326 @cindex renaming macro (@code{rn})
9327 @cindex macro, renaming (@code{rn})
9328 @cindex renaming string (@code{rn})
9329 @cindex string, renaming (@code{rn})
9330 @cindex renaming diversion (@code{rn})
9331 @cindex diversion, renaming (@code{rn})
9332 Rename the request, macro, diversion, or string @var{xx} to @var{yy}.
9336 @cindex removing request (@code{rm})
9337 @cindex request, removing (@code{rm})
9338 @cindex removing macro (@code{rm})
9339 @cindex macro, removing (@code{rm})
9340 @cindex removing string (@code{rm})
9341 @cindex string, removing (@code{rm})
9342 @cindex removing diversion (@code{rm})
9343 @cindex diversion, removing (@code{rm})
9344 Remove the request, macro, diversion, or string @var{xx}. @code{gtroff}
9345 treats subsequent invocations as if the object had never been defined.
9348 @Defreq {als, new old}
9349 @cindex alias, string, creating (@code{als})
9350 @cindex alias, macro, creating (@code{als})
9351 @cindex alias, diversion, creating (@code{als})
9352 @cindex creating alias, for string (@code{als})
9353 @cindex creating alias, for macro (@code{als})
9354 @cindex creating alias, for diversion (@code{als})
9355 @cindex string, creating alias (@code{als})
9356 @cindex macro, creating alias (@code{als})
9357 @cindex diversion, creating alias (@code{als})
9358 Create an alias named @var{new} for the request, string, macro, or
9359 diversion object named @var{old}. The new name and the old name are
9360 exactly equivalent (it is similar to a hard rather than a soft
9361 link). If @var{old} is undefined, @code{gtroff} generates a warning of
9362 type @samp{mac} and ignores the request.
9366 Remove (chop) the last character from the macro, string, or diversion
9367 named @var{xx}. This is useful for removing the newline from the end
9368 of diversions that are to be interpolated as strings. This command
9369 can be used repeatedly; see @ref{Gtroff Internals}, for details on
9370 nodes inserted additionally by @code{gtroff}.
9373 @xref{Identifiers}, and @ref{Comments}.
9376 @c =====================================================================
9378 @node Conditionals and Loops, Writing Macros, Strings, gtroff Reference
9379 @section Conditionals and Loops
9380 @cindex conditionals and loops
9381 @cindex loops and conditionals
9384 * Operators in Conditionals::
9389 @c ---------------------------------------------------------------------
9391 @node Operators in Conditionals, if-else, Conditionals and Loops, Conditionals and Loops
9392 @subsection Operators in Conditionals
9394 @cindex @code{if} request, operators to use with
9395 @cindex @code{while} request, operators to use with
9396 In @code{if} and @code{while} requests, there are several more
9397 operators available:
9402 True if the current page is even or odd numbered (respectively).
9405 True if the document is being processed in nroff mode (i.e., the
9406 @code{.nroff} command has been issued).
9409 True if the document is being processed in troff mode (i.e., the
9410 @code{.troff} command has been issued).
9413 Always false. This condition is for compatibility with other
9414 @code{troff} versions only.
9416 @item '@var{xxx}'@var{yyy}'
9417 True if the string @var{xxx} is equal to the string @var{yyy}. Other
9418 characters can be used in place of the single quotes; the same set of
9419 delimiters as for the @code{\D} escape is used (@pxref{Escapes}).
9420 @code{gtroff} formats the strings before being compared:
9431 The resulting motions, glyph sizes, and fonts have to
9432 match,@footnote{The created output nodes must be identical.
9433 @xref{Gtroff Internals}.} and not the individual motion, size, and
9434 font requests. In the previous example, @samp{|} and @samp{\fR|\fP}
9435 both result in a roman @samp{|} glyph with the same point size and
9436 at the same location on the page, so the strings are equal. If
9437 @samp{.ft@w{ }I} had been added before the @samp{.ie}, the result
9438 would be ``false'' because (the first) @samp{|} produces an italic
9439 @samp{|} rather than a roman one.
9442 True if there is a number register named @var{xxx}.
9445 True if there is a string, macro, diversion, or request named @var{xxx}.
9448 True if there is a color named @var{xxx}.
9451 True if there is a glyph @var{g} available@footnote{The name of this
9452 conditional operator is a misnomer since it tests names of output
9453 glyphs.}; @var{g} is either an @acronym{ASCII} character or a special
9454 character (@code{\(@var{gg}} or @code{\[@var{ggg}]}); the condition
9455 is also true if @var{g} has been defined by the @code{char} request.
9458 Note that these operators can't be combined with other operators like
9459 @samp{:} or @samp{&}; only a leading @samp{!} (without whitespace
9460 between the exclamation mark and the operator) can be used to negate
9472 A whitespace after @samp{!} always evaluates to zero (this bizarre
9473 behaviour is due to compatibility with @acronym{UNIX} @code{troff}).
9481 @result{} r xxx true
9484 It is possible to omit the whitespace before the argument to the
9485 @samp{r}, @samp{d}, and @samp{c} operators.
9489 @c ---------------------------------------------------------------------
9491 @node if-else, while, Operators in Conditionals, Conditionals and Loops
9495 @code{gtroff} has if-then-else constructs like other languages, although
9496 the formatting can be painful.
9498 @Defreq {if, expr anything}
9499 Evaluate the expression @var{expr}, and executes @var{anything} (the
9500 remainder of the line) if @var{expr} evaluates to non-zero (true).
9501 @var{anything} is interpreted as though it was on a line by itself
9502 (except that leading spaces are swallowed). @xref{Expressions}, for
9508 .if ((\n[xxx] == 1) & (\n[yyy] == 2)) true
9513 @Defreq{nop, anything}
9514 Executes @var{anything}.
9515 This is similar to @code{.if@w{ }1}.
9518 @DefreqList {ie, expr anything}
9519 @DefreqListEnd {el, anything}
9520 Use the @code{ie} and @code{el} requests to write an if-then-else.
9521 The first request is the `if' part and the latter is the `else' part.
9524 .ie n .ls 2 \" double-spacing in nroff
9525 .el .ls 1 \" single-spacing in troff
9529 @c there is a bug in makeinfo <= 4.1a: you can't have `@{' as an argument
9532 @c and in 4.2 you still can't use @{ in macros.
9534 @c @DefescList {\@{, , , }
9535 @c @DefescListEnd {\@}, , , }
9536 @deffn Escape @t{\@{}
9537 @deffnx Escape @t{\@}}
9540 @cindex begin of conditional block (@code{\@{})
9541 @cindex end of conditional block (@code{\@}})
9542 @cindex conditional block, begin (@code{\@{})
9543 @cindex conditional block, end (@code{\@}})
9544 @cindex block, conditional, begin (@code{\@{})
9545 @cindex block, condititional, end (@code{\@}})
9546 In many cases, an if (or if-else) construct needs to execute more than
9547 one request. This can be done using the @code{\@{} and @code{\@}}
9548 escapes. The following example shows the possible ways to use these
9549 escapes (note the position of the opening and closing braces).
9566 @c ---------------------------------------------------------------------
9568 @node while, , if-else, Conditionals and Loops
9572 @code{gtroff} provides a looping construct using the @code{while}
9573 request, which is used much like the @code{if} (and related) requests.
9575 @Defreq {while, expr anything}
9576 Evaluate the expression @var{expr}, and repeatedly execute
9577 @var{anything} (the remainder of the line) until @var{expr} evaluates
9582 .while (\na < 9) \@{\
9586 @result{} 1, 2, 3, 4, 5, 6, 7, 8, 9, 10
9591 @cindex @code{de} request, and @code{while}
9594 The body of a @code{while} request is treated like the body of a
9595 @code{de} request: @code{gtroff} temporarily stores it in a macro
9596 which is deleted after the loop has been exited. It can considerably
9597 slow down a macro if the body of the @code{while} request (within the
9598 macro) is large. Each time the macro is executed, the @code{while}
9599 body is parsed and stored again as a temporary macro.
9604 . while (\\n[num] > 0) \@{\
9605 . \" many lines of code
9611 @cindex recursive macros
9612 @cindex macros, recursive
9614 The traditional and ofter better solution (@acronym{UNIX} @code{troff}
9615 doesn't have the @code{while} request) is to use a recursive macro
9616 instead which is parsed only once during its definition.
9620 . if (\\n[num] > 0) \@{\
9621 . \" many lines of code
9634 Note that the number of available recursion levels is set to@w{ }1000
9635 (this is a compile-time constant value of @code{gtroff}).
9638 The closing brace of a @code{while} body must end a line.
9643 . while (\n[a] < 10) \@{\
9646 @result{} unbalanced \@{ \@}
9652 @cindex @code{while} request, confusing with @code{br}
9653 @cindex @code{break} request, in a @code{while} loop
9654 @cindex @code{continue} request, in a @code{while} loop
9655 Break out of a @code{while} loop. Be sure not to confuse this with
9656 the @code{br} request (causing a line break).
9659 @Defreq {continue, }
9660 Finish the current iteration of a @code{while} loop, immediately
9661 restarting the next iteration.
9667 @c =====================================================================
9669 @node Writing Macros, Page Motions, Conditionals and Loops, gtroff Reference
9670 @section Writing Macros
9671 @cindex writing macros
9672 @cindex macros, writing
9674 A @dfn{macro} is a collection of text and embedded commands which can
9675 be invoked multiple times. Use macros to define common operations.
9677 @DefreqList {de, name [@Var{end}]}
9678 @DefreqItem {de1, name [@Var{end}]}
9679 @DefreqListEnd {dei, name [@Var{end}]}
9680 Define a new macro named @var{name}. @code{gtroff} copies subsequent
9681 lines (starting with the next one) into an internal buffer until it
9682 encounters the line @samp{..} (two dots). The optional second
9683 argument to @code{de} changes this to a macro to @samp{.@var{end}}.
9685 There can be whitespace after the first dot in the line containing the
9686 ending token (either @samp{.} or macro @samp{@var{end}}).
9688 Here a small example macro called @samp{P} which causes a break and
9689 inserts some vertical space. It could be used to separate paragraphs.
9698 The following example defines a macro within another. Remember that
9699 expansion must be protected twice; once for reading the macro and
9703 \# a dummy macro to avoid a warning
9709 . nop \f[B]Hallo \\\\$1!\f[]
9715 @result{} @b{Hallo Joe!}
9719 Since @code{\f} has no expansion, it isn't necessary to protect its
9720 backslash. Had we defined another macro within @code{bar} which takes
9721 a parameter, eight backslashes would be necessary before @samp{$1}.
9723 The @code{de1} request turns off compatibility mode
9724 while executing the macro. On entry, the current compatibility mode
9725 is saved and restored at exit.
9731 The value of xxx is \\n[xxx].
9734 The value of xxx ix \\n[xxx].
9740 @result{} warning: number register
\e' not defined
9741 @result{} The value of xxx is 0xxx].
9743 @result{} The value of xxx ix 12345.
9746 The @code{dei} request defines a macro indirectly.
9747 That is, it expands strings whose names
9748 are @var{name} or @var{end} before performing the append.
9766 Using @file{trace.tmac}, you can trace calls to @code{de} and @code{de1}.
9768 Note that macro identifiers are shared with identifiers for strings and
9772 @DefreqList {am, xx}
9773 @DefreqItem {am1, xx}
9774 @DefreqListEnd {ami, xx yy}
9775 @cindex appending to a macro (@code{am})
9776 @cindex macro, appending (@code{am})
9777 Works similarly to @code{de} except it appends onto the macro named
9778 @var{xx}. So, to make the previously defined @samp{P} macro actually
9779 do indented instead of block paragraphs, add the necessary code to the
9780 existing macro like this:
9788 The @code{am1} request turns off compatibility mode
9789 while executing the appended macro piece. To be more precise, a
9790 @dfn{compatibility save} input token is inserted at the beginning of
9791 the appended code, and a @dfn{compatibility restore} input token at
9794 The @code{ami} request appends indirectly,
9795 meaning that @code{gtroff} expands strings whose names
9796 are @var{xx} or @var{yy} before performing the append.
9799 Using @file{trace.tmac}, you can trace calls to @code{am} and @code{am1}.
9802 @xref{Strings}, for the @code{als} request to rename a macro.
9804 The @code{de}, @code{am}, @code{di}, @code{da}, @code{ds}, and
9805 @code{as} requests (together with its variants) only create a new object
9806 if the name of the macro, diversion or string diversion is currently
9807 undefined or if it is defined to be a request; normally they modify the
9808 value of an existing object.
9811 Exit a macro, immediately returning to the caller.
9819 @c ---------------------------------------------------------------------
9821 @node Copy-in Mode, Parameters, Writing Macros, Writing Macros
9822 @subsection Copy-in Mode
9823 @cindex copy-in mode
9824 @cindex mode, copy-in
9826 @cindex @code{\n}, when reading text for a macro
9827 @cindex @code{\$}, when reading text for a macro
9828 @cindex @code{\*}, when reading text for a macro
9829 @cindex @code{\\}, when reading text for a macro
9830 @cindex \@key{RET}, when reading text for a macro
9831 When @code{gtroff} reads in the text for a macro, string, or diversion,
9832 it copies the text (including request lines, but excluding escapes) into
9833 an internal buffer. Escapes are converted into an internal form,
9834 except for @code{\n}, @code{\$}, @code{\*}, @code{\\} and
9835 @code{\@key{RET}} which are evaluated and inserted into the text where
9836 the escape was located. This is known as @dfn{copy-in} mode or
9839 What this means is that you can specify when these escapes are to be
9840 evaluated (either at copy-in time or at the time of use) by insulating
9841 the escapes with an extra backslash. Compare this to the @code{\def}
9842 and @code{\edef} commands in @TeX{}.
9844 The following example prints the numbers 20 and@w{ }10:
9856 @c ---------------------------------------------------------------------
9858 @node Parameters, , Copy-in Mode, Writing Macros
9859 @subsection Parameters
9862 The arguments to a macro or string can be examined using a variety of
9866 @cindex number of arguments register (@code{.$})
9867 The number of arguments passed to a macro or string. This is a read-only
9871 Any individual argument can be retrieved with one of the following
9874 @DefescList {\\$, , n, }
9875 @DefescItem {\\$, @lparen{}, nn, }
9876 @DefescListEnd {\\$, @lbrack{}, nnn, @rbrack{}}
9877 @cindex copy-in mode, and macro arguments
9878 @cindex macro, arguments (@code{\$})
9879 @cindex arguments, macro (@code{\$})
9880 Retrieve the @var{n}@dmn{th}, @var{nn}@dmn{th} or @var{nnn}@dmn{th}
9881 argument. As usual, the first form only accepts a single number
9882 (larger than zero), the second a two-digit number (larger or equal
9883 to@w{ }10), and the third any positive integer value (larger
9884 than zero). Macros and strings can have an unlimited number of arguments.
9885 Note that due to copy-in mode, use two backslashes on these in actual use
9886 to prevent interpolation until the macro is actually invoked.
9889 @Defreq {shift, [@Var{n}]}
9890 Shift the arguments 1@w{ }position, or as
9891 many positions as specified by its argument. After executing this
9892 request, argument@w{ }@var{i} becomes argument @math{@var{i}-@var{n}};
9893 arguments 1 to@w{ }@var{n} are no longer available. Shifting by
9894 negative amounts is currently undefined.
9897 @DefescList {\\$*, , , }
9898 @DefescListEnd {\\$@@, , , }
9899 In some cases it is convenient to use all of the arguments at once (for
9900 example, to pass the arguments along to another macro). The @code{\$*}
9901 escape concatenates all the arguments separated by spaces. A
9902 similar escape is @code{\$@@}, which concatenates all the
9903 arguments with each surrounded by double quotes, and separated by
9904 spaces. If not in compatibility mode, the input level of double quotes
9905 is preserved (see @ref{Request Arguments}).
9908 @Defesc {\\$0, , , }
9909 @cindex macro name register (@code{\$0})
9910 @cindex @code{als} request, and @code{\$0}
9911 The name used to invoke the current macro.
9912 The @code{als} request can make a macro have more than one name.
9917 . if \\n[error] \@{\
9918 . tm \\$0: Houston, we have a problem.
9923 .als foo generic-macro
9924 .als bar generic-macro
9928 @xref{Request Arguments}.
9931 @c =====================================================================
9933 @node Page Motions, Drawing Requests, Writing Macros, gtroff Reference
9934 @section Page Motions
9935 @cindex page motions
9936 @cindex motions, page
9938 @xref{Manipulating Spacing}, for a discussion of the main request for
9939 vertical motion, @code{sp}.
9941 @DefreqList {mk, [@Var{reg}]}
9942 @DefreqListEnd {rt, [@Var{dist}]}
9943 @cindex marking vertical page location (@code{mk})
9944 @cindex page location, vertical, marking (@code{mk})
9945 @cindex location, vertical, page, marking (@code{mk})
9946 @cindex vertical page location, marking (@code{mk})
9947 @cindex returning to marked vertical page location (@code{rt})
9948 @cindex page location, vertical, returning to marked (@code{rt})
9949 @cindex location, vertical, page, returning to marked (@code{rt})
9950 @cindex vertical page location, returning to marked (@code{rt})
9951 The request @code{mk} can be used to mark a location on a page, for
9952 movement to later. This request takes a register name as an argument
9953 in which to store the current page location. With no argument it
9954 stores the location in an internal register. The results of this can
9955 be used later by the @code{rt} or the @code{sp} request (or the
9958 The @code{rt} request returns @emph{upwards} to the location marked
9959 with the last @code{mk} request. If used with an argument, return to
9960 a position which distance from the top of the page is @var{dist} (no
9961 previous call to @code{mk} is necessary in this case). Default scaling
9962 indicator is @samp{v}.
9964 Here a primitive solution for a two-column macro.
9967 .nr column-length 1.5i
9969 .nr bottom-margin 1m
9976 . ll \\n[column-length]u
9977 . wh -\\n[bottom-margin]u 2c-trap
9984 . ie \\n[right-side] \@{\
9986 . po -(\\n[column-length]u + \\n[column-gap]u)
9988 . wh -\\n[bottom-margin]u
9991 . \" switch to right side
9993 . po +(\\n[column-length]u + \\n[column-gap]u)
10002 This is a small test which shows how the
10003 rt request works in combination with mk.
10006 Starting here, text is typeset in two columns.
10007 Note that this implementation isn't robust
10008 and thus not suited for a real two-column
10015 This is a small test which shows how the
10016 rt request works in combination with mk.
10018 Starting here, isn't robust
10019 text is typeset and thus not
10020 in two columns. suited for a
10021 Note that this real two-column
10022 implementation macro.
10026 The following escapes give fine control of movements about the page.
10028 @Defesc {\\v, ', e, '}
10029 @cindex vertical motion (@code{\v})
10030 @cindex motion, vertical (@code{\v})
10031 Move vertically, usually from the current location on the page (if no
10032 absolute position operator @samp{|} is used). The
10033 argument@w{ }@var{e} specifies the distance to move; positive is
10034 downwards and negative upwards. The default scaling indicator for this
10035 escape is @samp{v}. Beware, however, that @code{gtroff} continues text
10036 processing at the point where the motion ends, so you should always
10037 balance motions to avoid interference with text processing.
10039 @code{\v} doesn't trigger a trap. This can be quite useful; for example,
10040 consider a page bottom trap macro which prints a marker in the margin to
10041 indicate continuation of a footnote or something similar.
10044 There are some special-case escapes for vertical motion.
10046 @Defesc {\\r, , , }
10047 Move upwards@w{ }1@dmn{v}.
10050 @Defesc {\\u, , , }
10051 Move upwards@w{ }.5@dmn{v}.
10054 @Defesc {\\d, , , }
10055 Move down@w{ }.5@dmn{v}.
10058 @Defesc {\\h, ', e, '}
10059 @cindex inserting horizontal space (@code{\h})
10060 @cindex horizontal space (@code{\h})
10061 @cindex space, horizontal (@code{\h})
10062 @cindex horizontal motion (@code{\h})
10063 @cindex motion, horizontal (@code{\h})
10064 Move horizontally, usually from the current location (if no absolute
10065 position operator @samp{|} is used). The expression@w{ }@var{e}
10066 indicates how far to move: positive is rightwards and negative
10067 leftwards. The default scaling indicator for this escape is @samp{m}.
10070 There are a number of special-case escapes for horizontal motion.
10072 @Defesc {\\@key{SP}, , , }
10073 @cindex space, unbreakable
10074 @cindex unbreakable space
10075 An unbreakable and unpaddable (i.e.@: not expanded during filling)
10076 space. (Note: This is a backslash followed by a space.)
10079 @Defesc {\\~, , , }
10080 An unbreakable space that stretches like a normal inter-word space
10081 when a line is adjusted.
10084 @Defesc {\\|, , , }
10085 A 1/6@dmn{th} em space. Ignored for TTY output devices (rounded to
10089 @Defesc {\\^, , , }
10090 A 1/12@dmn{th} em space. Ignored for TTY output devices (rounded to
10094 @Defesc {\\0, , , }
10095 @cindex space, width of a digit (@code{\0})
10096 @cindex digit width space (@code{\0})
10097 A space the size of a digit.
10100 The following string sets the @TeX{} logo:
10103 .ds TeX T\h'-.1667m'\v'.224m'E\v'-.224m'\h'-.125m'X
10106 @DefescList {\\w, ', text, '}
10113 @DefregListEnd {skw}
10114 @cindex width escape (@code{\w})
10115 Return the width of the specified @var{text} in basic units.
10116 This allows horizontal movement based on the width of some
10117 arbitrary text (e.g.@: given as an argument to a macro).
10120 The length of the string `abc' is \w'abc'u.
10121 @result{} The length of the string `abc' is 72u.
10124 Font changes may occur in @var{text} which don't affect current
10127 After use, @code{\w} sets several registers:
10132 The highest and lowest point of the baseline, respectively, in @var{text}.
10136 Like the @code{st} and @code{sb} registers, but takes account of the
10137 heights and depths of glyphs. With other words, this gives the
10138 highest and lowest point of @var{text}.
10141 Defines the kinds of glyphs occurring in @var{text}:
10145 only short glyphs, no descenders or tall glyphs.
10148 at least one descender.
10151 at least one tall glyph.
10154 at least one each of a descender and a tall glyph.
10158 The amount of horizontal space (possibly negative) that should be added
10159 to the last glyph before a subscript.
10162 How far to right of the center of the last glyph in the @code{\w}
10163 argument, the center of an accent from a roman font should be placed
10168 @DefescList {\\k, , p, }
10169 @DefescItem {\\k, @lparen{}, ps, }
10170 @DefescListEnd {\\k, @lbrack{}, position, @rbrack}
10171 @cindex saving horizontal input line position (@code{\k})
10172 @cindex horizontal input line position, saving (@code{\k})
10173 @cindex input line position, horizontal, saving (@code{\k})
10174 @cindex position, horizontal input line, saving (@code{\k})
10175 @cindex line, input, horizontal position, saving (@code{\k})
10176 Store the current horizontal position in the @emph{input} line in
10177 number register with name @var{position} (one-character name@w{ }@var{p},
10178 two-character name @var{ps}). Use this, for example, to return to the
10179 beginning of a string for highlighting or other decoration.
10183 @cindex horizontal input line position register (@code{hp})
10184 @cindex input line, horizontal position, register (@code{hp})
10185 @cindex position, horizontal, in input line, register (@code{hp})
10186 @cindex line, input, horizontal position, register (@code{hp})
10187 The current horizontal position at the input line.
10191 @cindex horizontal output line position register (@code{.k})
10192 @cindex output line, horizontal position, register (@code{.k})
10193 @cindex position, horizontal, in output line, register (@code{.k})
10194 @cindex line, output, horizontal position, register (@code{.k})
10195 A read-only number register containing the current horizontal output
10199 @Defesc {\\o, ', @Var{a}@Var{b}@Var{c}, '}
10200 @cindex overstriking glyphs (@code{\o})
10201 @cindex glyphs, overstriking (@code{\o})
10202 Overstrike glyphs @var{a}, @var{b}, @var{c}, @dots{}; the glyphs
10203 are centered, and the resulting spacing is the largest width of the
10207 @Defesc {\\z, , g, , }
10208 @cindex zero-width printing (@code{\z}, @code{\Z})
10209 @cindex printing, zero-width (@code{\z}, @code{\Z})
10210 Print glyph @var{g} with zero width, i.e., without spacing. Use
10211 this to overstrike glyphs left-aligned.
10214 @Defesc {\\Z, ', anything, '}
10215 @cindex zero-width printing (@code{\z}, @code{\Z})
10216 @cindex printing, zero-width (@code{\z}, @code{\Z})
10217 Print @var{anything}, then restore the horizontal and vertical position.
10218 The argument may not contain tabs or leaders.
10220 The following is an example of a strike-through macro:
10225 \Z@@\v'-.25m'\l'\\n[ww]u'@@\\$1
10230 an actual emergency!
10235 @c =====================================================================
10237 @node Drawing Requests, Traps, Page Motions, gtroff Reference
10238 @section Drawing Requests
10239 @cindex drawing requests
10240 @cindex requests for drawing
10242 @code{gtroff} provides a number of ways to draw lines and other figures
10243 on the page. Used in combination with the page motion commands (see
10244 @ref{Page Motions}, for more info), a wide variety of figures can be
10245 drawn. However, for complex drawings these operations can be quite
10246 cumbersome, and it may be wise to use graphic preprocessors like
10247 @code{gpic} or @code{ggrn}. @xref{gpic}, and @ref{ggrn}, for more
10250 All drawing is done via escapes.
10252 @DefescList {\\l, ', @Var{l}, '}
10253 @DefescListEnd {\\l, ', @Var{l}@Var{g}, '}
10254 @cindex drawing horizontal lines (@code{\l})
10255 @cindex horizontal line, drawing (@code{\l})
10256 @cindex line, horizontal, drawing (@code{\l})
10257 Draw a line horizontally. @var{l} is the length of the line to be
10258 drawn. If it is positive, start the line at the current location and
10259 draw to the right; its end point is the new current location. Negative
10260 values are handled differently: The line starts at the current location
10261 and draws to the left, but the current location doesn't move.
10263 @var{l} can also be specified absolutely (i.e.@: with a leading
10264 @samp{|}) which draws back to the beginning of the input line.
10265 Default scaling indicator is @samp{m}.
10267 @cindex underscore glyph (@code{\[ru]})
10268 @cindex glyph, underscore (@code{\[ru]})
10269 @cindex line drawing glyph
10270 @cindex glyph, for line drawing
10271 The optional second parameter@w{ }@var{g} is a glyph to draw the line
10272 with. If this second argument is not specified, @code{gtroff} uses
10273 the underscore glyph, @code{\[ru]}.
10275 @cindex zero width space character (@code{\&})
10276 @cindex character, zero width space (@code{\&})
10277 @cindex space character, zero width (@code{\&})
10278 To separate the two arguments (to prevent @code{gtroff} from
10279 interpreting a drawing glyph as a scaling indicator if the glyph is
10280 represented by a single character) use @code{\&}.
10282 Here a small useful example:
10286 \[br]\\$*\[br]\l'|0\[rn]'\l'|0\[ul]'
10291 Note that this works by outputting a box rule (a vertical line), then
10292 the text given as an argument and then another box rule. Finally, the
10293 line drawing escapes both draw from the current location to the
10294 beginning of the @emph{input} line -- this works because the line
10295 length is negative, not moving the current point.
10298 @DefescList {\\L, ', @Var{l}, '}
10299 @DefescListEnd {\\L, ', @Var{l}@Var{g}, '}
10300 @cindex drawing vertical lines (@code{\L})
10301 @cindex vertical line drawing (@code{\L})
10302 @cindex line, vertical, drawing (@code{\L})
10303 @cindex line drawing glyph
10304 @cindex glyph for line drawing
10305 @cindex box rule glyph (@code{\[br]})
10306 @cindex glyph, box rule (@code{\[br]})
10307 Draw vertical lines. Its parameters are
10308 similar to the @code{\l} escape, except that the default scaling
10309 indicator is @samp{v}. The movement is downwards for positive values,
10310 and upwards for negative values. The default glyph is the box rule
10311 glyph, @code{\[br]}. As with the vertical motion escapes, text
10312 processing blindly continues where the line ends.
10315 This is a \L'3v'test.
10319 Here the result, produced with @code{grotty}.
10329 @Defesc {\\D, ', command arg @dots{}, '}
10330 The @code{\D} escape provides a variety of drawing functions.
10331 Note that on character devices, only vertical and horizontal lines are
10332 supported within @code{grotty}; other devices may only support a subset
10333 of the available drawing functions.
10335 The default scaling indicator for all subcommands of @code{\D} is
10336 @samp{m} for horizontal distances and @samp{v} for vertical ones.
10337 Exceptions are @w{@code{\D'f @dots{}'}} and @w{@code{\D't @dots{}'}}
10338 which use @code{u} as the default.
10341 @item \D'l @var{dx} @var{dy}'
10342 @cindex line, drawing (@w{@code{\D'l @dots{}'}})
10343 @cindex drawing a line (@w{@code{\D'l @dots{}'}})
10344 Draw a line from the current location to the relative point specified by
10345 (@var{dx},@var{dy}).
10347 The following example is a macro for creating a box around a text string;
10348 for simplicity, the box margin is taken as a fixed value, 0.2@dmn{m}.
10354 \h'-.2m'\v'(.2m - \\n[rsb]u)'\
10355 \D'l 0 -(\\n[rst]u - \\n[rsb]u + .4m)'\
10356 \D'l (\\n[@@wd]u + .4m) 0'\
10357 \D'l 0 (\\n[rst]u - \\n[rsb]u + .4m)'\
10358 \D'l -(\\n[@@wd]u + .4m) 0'\
10359 \h'.2m'\v'-(.2m - \\n[rsb]u)'\
10366 First, the width of the string is stored in register @code{@@wd}. Then,
10367 four lines are drawn to form a box, properly offset by the box margin.
10368 The registers @code{rst} and @code{rsb} are set by the @code{\w} escape,
10369 containing the largest height and depth of the whole string.
10371 @item \D'c @var{d}'
10372 @cindex circle, drawing (@w{@code{\D'c @dots{}'}})
10373 @cindex drawing a circle (@w{@code{\D'c @dots{}'}})
10374 Draw a circle with a diameter of@w{ }@var{d} with the leftmost point at the
10377 @item \D'C @var{d}'
10378 @cindex circle, solid, drawing (@w{@code{\D'C @dots{}'}})
10379 @cindex drawing a solid circle (@w{@code{\D'C @dots{}'}})
10380 @cindex solid circle, drawing (@w{@code{\D'C @dots{}'}})
10381 Draw a solid circle with the same parameters as an outlined circle. No
10384 @item \D'e @var{x} @var{y}'
10385 @cindex drawing an ellipse (@w{@code{\D'e @dots{}'}})
10386 @cindex ellipse, drawing (@w{@code{\D'e @dots{}'}})
10387 Draw an ellipse with a horizontal diameter of @var{x} and a vertical
10388 diameter of @var{y} with the leftmost point at the current position.
10390 @item \D'E @var{x} @var{y}'
10391 @cindex ellipse, solid, drawing (@w{@code{\D'E @dots{}'}})
10392 @cindex drawing a solid ellipse (@w{@code{\D'E @dots{}'}})
10393 @cindex solid ellipse, drawing (@w{@code{\D'E @dots{}'}})
10394 Draw a solid ellipse with the same parameters as an outlined ellipse.
10395 No outline is drawn.
10397 @item \D'a @var{dx1} @var{dy1} @var{dx2} @var{dy2}'
10398 @cindex arc, drawing (@w{@code{\D'a @dots{}'}})
10399 @cindex drawing an arc (@w{@code{\D'a @dots{}'}})
10400 Draw an arc clockwise from the current location through the two
10401 specified relative locations (@var{dx1},@var{dy1}) and
10402 (@var{dx2},@var{dy2}). The coordinates of the first point are relative
10403 to the current position, and the coordinates of the second point are
10404 relative to the first point.
10406 @item \D'~ @var{dx1} @var{dy1} @var{dx2} @var{dy2} @dots{}'
10407 @cindex drawing a spline (@w{@code{\D'~ @dots{}'}})
10408 @cindex spline, drawing (@w{@code{\D'~ @dots{}'}})
10409 Draw a spline from the current location to the relative point
10410 (@var{dx1},@var{dy1}) and then to (@var{dx2},@var{dy2}), and so on.
10412 @item \D'f @var{n}'
10413 @cindex gray shading (@w{@code{\D'f @dots{}'}})
10414 @cindex shading filled objects (@w{@code{\D'f @dots{}'}})
10415 Set the shade of gray to be used for filling solid objects to@w{
10416 }@var{n}; @var{n}@w{ }must be an integer between 0 and@w{ }1000, where 0
10417 corresponds solid white and 1000 to solid black, and values in between
10418 correspond to intermediate shades of gray. This applies only to solid
10419 circles, solid ellipses, and solid polygons. By default, a level of
10422 @item \D'p @var{dx1} @var{dy1} @var{dx2} @var{dy2} @dots{}'
10423 @cindex drawing a polygon (@w{@code{\D'p @dots{}'}})
10424 @cindex polygon, drawing (@w{@code{\D'p @dots{}'}})
10425 Draw a polygon from the current location to the relative position
10426 (@var{dx1},@var{dy1}) and then to (@var{dx2},@var{dy2}) and so on.
10427 When the specified data points are exhausted, a line is drawn back
10428 to the starting point.
10430 @item \D'P @var{dx1} @var{dy1} @var{dx2} @var{dy2} @dots{}'
10431 @cindex polygon, solid, drawing (@w{@code{\D'P @dots{}'}})
10432 @cindex drawing a solid polygon (@w{@code{\D'P @dots{}'}})
10433 @cindex solid polygon, drawing (@w{@code{\D'P @dots{}'}})
10434 Draw a solid polygon with the same parameters as an outlined polygon.
10435 No outline is drawn.
10437 Here a better variant of the box macro to fill the box with some color.
10438 Note that the box must be drawn before the text since colors in
10439 @code{gtroff} are not transparent; the filled polygon would hide the
10446 \h'-.2m'\v'(.2m - \\n[rsb]u)'\
10448 \D'P 0 -(\\n[rst]u - \\n[rsb]u + .4m) \
10449 (\\n[@@wd]u + .4m) 0 \
10450 0 (\\n[rst]u - \\n[rsb]u + .4m) \
10451 -(\\n[@@wd]u + .4m) 0'\
10452 \h'.2m'\v'-(.2m - \\n[rsb]u)'\
10459 @item \D't @var{n}'
10460 @cindex line thickness (@w{@code{\D't @dots{}'}})
10461 @cindex thickness of lines (@w{@code{\D't @dots{}'}})
10462 Set the current line thickness to @var{n}@w{ }machine units. A value of
10463 zero selects the smallest available line thickness. A negative value
10464 makes the line thickness proportional to the current point size (this is
10465 the default behaviour of @acronym{AT&T} @code{troff}).
10469 @xref{Graphics Commands}.
10471 @Defesc {\\b, ', string, '}
10472 @cindex pile, glyph (@code{\b})
10473 @cindex glyph pile (@code{\b})
10474 @cindex stacking glyphs (@code{\b})
10475 @dfn{Pile} a sequence of glyphs vertically, and center it vertically
10476 on the current line. Use it to build large brackets and braces.
10478 Here an example how to create a large opening brace:
10481 \b'\[lt]\[bv]\[lk]\[bv]\[lb]'
10484 @cindex @code{\b}, limitations
10485 @cindex limitations of @code{\b} escape
10486 The first glyph is on the top, the last glyph in @var{string} is
10487 at the bottom. Note that @code{gtroff} separates the glyphs
10488 vertically by 1@dmn{m}, and the whole object is centered 0.5@dmn{m}
10489 above the current baseline; the largest glyph width is used as the
10490 width for the whole object. This rather unflexible positioning
10491 algorithm doesn't work with @option{-Tdvi} since the bracket pieces vary
10492 in height for this device. Instead, use the @code{eqn} preprocessor.
10494 @xref{Manipulating Spacing}, how to adjust the vertical spacing with
10495 the @code{\x} escape.
10499 @c =====================================================================
10501 @node Traps, Diversions, Drawing Requests, gtroff Reference
10505 @dfn{Traps} are locations, which, when reached, call a specified
10506 macro. These traps can occur at a given location on the page, at a
10507 given location in the current diversion, at a blank line,
10508 after a certain number of input lines, or at the end of input.
10510 @cindex planting a trap
10511 @cindex trap, planting
10512 Setting a trap is also called @dfn{planting}.
10513 @cindex trap, springing
10514 @cindex springing a trap
10515 It is also said that a trap is @dfn{sprung} if the associated macro
10519 * Page Location Traps::
10520 * Diversion Traps::
10521 * Input Line Traps::
10522 * Blank Line Traps::
10523 * End-of-input Traps::
10526 @c ---------------------------------------------------------------------
10528 @node Page Location Traps, Diversion Traps, Traps, Traps
10529 @subsection Page Location Traps
10530 @cindex page location traps
10531 @cindex traps, page location
10533 @dfn{Page location traps} perform an action when @code{gtroff}
10534 reaches or passes a certain vertical location on the page. Page
10535 location traps have a variety of purposes, including:
10539 setting headers and footers
10542 setting body text in multiple columns
10548 @DefreqList {vpt, flag}
10549 @DefregListEnd {.vpt}
10550 @cindex enabling vertical position traps (@code{vpt})
10551 @cindex vertical position traps, enabling (@code{vpt})
10552 @cindex vertical position trap enable register (@code{.vpt})
10553 Enable vertical position traps if @var{flag} is non-zero, or disables
10554 them otherwise. Vertical position traps are traps set by the @code{wh}
10555 or @code{dt} requests. Traps set by the @code{it} request are not
10556 vertical position traps. The parameter that controls whether vertical
10557 position traps are enabled is global. Initially vertical position traps
10558 are enabled. The current setting of this is available in the
10559 @code{.vpt} read-only number register.
10562 @Defreq {wh, dist [@Var{macro}]}
10563 Set a page location trap. Positive values for @var{dist} set
10564 the trap relative to the top of the page; negative values set
10565 the trap relative to the bottom of the page. Default scaling
10566 indicator is @samp{v}.
10568 @var{macro} is the name of the macro to execute when the
10569 trap is sprung. If @var{macro} is missing, remove the first trap
10570 (if any) at @var{dist}.
10572 @cindex page headers
10573 @cindex page footers
10576 The following is a simple example of how many macro packages
10577 set headers and footers.
10580 .de hd \" Page header
10586 .de fo \" Page footer
10592 .wh 0 hd \" trap at top of the page
10593 .wh -1i fo \" trap one inch from bottom
10596 A trap at or below the bottom of the page is ignored; it can be made
10597 active by either moving it up or increasing the page length so that the
10598 trap is on the page.
10600 It is possible to have more than one trap at the same location; to do so,
10601 the traps must be defined at different locations, then moved together with
10602 the @code{ch} request; otherwise the second trap would replace the first
10603 one. Earlier defined traps hide later defined traps if moved to the same
10604 position (the many empty lines caused by the @code{bp} request are omitted):
10637 @cindex distance to next trap register (@code{.t})
10638 @cindex trap, distance, register (@code{.t})
10639 A read-only number register holding the distance to the next trap.
10641 If there are no traps between the current position and the bottom of the
10642 page, it contains the distance to the page bottom. In a diversion, the
10643 distance to the page bottom is infinite (the returned value is the biggest
10644 integer which can be represented in @code{groff}) if there are no diversion
10648 @Defreq {ch, macro dist}
10649 @cindex changing trap location (@code{ch})
10650 @cindex trap, changing location (@code{ch})
10651 Change the location of a trap.
10652 The first argument is the name of the macro to be invoked at
10653 the trap, and the second argument is the new location for the trap
10654 (note that the parameters are specified the opposite of the @code{wh}
10655 request). This is useful for building up footnotes in a diversion to
10656 allow more space at the bottom of the page for them.
10658 Default scaling indicator for @var{dist} is @samp{v}. If @var{dist}
10659 is missing, the trap is removed.
10665 ... (simplified) footnote example ...
10671 The read-only number register @code{.ne} contains the amount of space
10672 that was needed in the last @code{ne} request that caused a trap to be
10673 sprung. Useful in conjunction with the @code{.trunc} register.
10674 @xref{Page Control}, for more information.
10678 @cindex @code{ne} request, and the @code{.trunc} register
10679 @cindex truncated vertical space register (@code{.trunc})
10680 A read-only register containing the amount of vertical space truncated
10681 by the most recently sprung vertical position trap, or, if the trap was
10682 sprung by an @code{ne} request, minus the amount of vertical motion
10683 produced by the @code{ne} request. In other words, at the point a trap
10684 is sprung, it represents the difference of what the vertical position
10685 would have been but for the trap, and what the vertical position
10689 @c ---------------------------------------------------------------------
10691 @node Diversion Traps, Input Line Traps, Page Location Traps, Traps
10692 @subsection Diversion Traps
10693 @cindex diversion traps
10694 @cindex traps, diversion
10696 @Defreq {dt, dist macro}
10697 @cindex @code{.t} register, and diversions
10698 @cindex setting diversion trap (@code{dt})
10699 @cindex diversion trap, setting (@code{dt})
10700 @cindex trap, diversion, setting (@code{dt})
10701 Set a trap @emph{within} a diversion.
10702 @var{dist} is the location of the trap
10703 (identical to the @code{.wh} request; default scaling indicator is
10704 @samp{v}) and @var{macro} is the name of the macro to be invoked. The
10705 number register @code{.t} still works within diversions.
10706 @xref{Diversions}, for more information.
10709 @c ---------------------------------------------------------------------
10711 @node Input Line Traps, Blank Line Traps, Diversion Traps, Traps
10712 @subsection Input Line Traps
10713 @cindex input line traps
10714 @cindex traps, input line
10716 @DefreqList {it, n macro}
10717 @DefreqItem {itc, n macro}
10718 @cindex setting input line trap (@code{it})
10719 @cindex input line trap, setting (@code{it})
10720 @cindex trap, input line, setting (@code{it})
10721 Set an input line trap.
10722 @var{n}@w{ }is the number of lines of input which may be read before
10723 springing the trap, @var{macro} is the macro to be invoked.
10724 Request lines are not counted as input lines.
10726 For example, one possible use is to have a macro which prints the
10727 next @var{n}@w{ }lines in a bold font.
10740 @cindex input line traps and interrupted lines (@code{itc})
10741 @cindex interrupted lines and input line traps (@code{itc})
10742 @cindex traps, input line, and interrupted lines (@code{itc})
10743 @cindex lines, interrupted, and input line traps (@code{itc})
10744 The @code{itc} request is identical,
10745 except that a line interrupted with @code{\c}
10746 counts as one input line.
10748 Both requests are associated with the current environment
10749 (@pxref{Environments}); switching to another environment disables the
10750 current input trap, and going back reactivates it, restoring the number
10751 of already processed lines.
10754 @c ---------------------------------------------------------------------
10756 @node Blank Line Traps, End-of-input Traps, Input Line Traps, Traps
10757 @subsection Blank Line Traps
10758 @cindex blank line traps
10759 @cindex traps, blank line
10761 @Defreq {blm, macro}
10762 @cindex blank line macro (@code{blm})
10763 Set a blank line trap.
10764 @code{gtroff} executes @var{macro} when it encounters a blank line in
10768 @c ---------------------------------------------------------------------
10770 @node End-of-input Traps, , Blank Line Traps, Traps
10771 @subsection End-of-input Traps
10772 @cindex end-of-input traps
10773 @cindex traps, end-of-input
10775 @Defreq {em, macro}
10776 @cindex setting end-of-input trap (@code{em})
10777 @cindex end-of-input trap, setting (@code{em})
10778 @cindex trap, end-of-input, setting (@code{em})
10779 @cindex end-of-input macro (@code{em})
10780 @cindex macro, end-of-input (@code{em})
10781 Set a trap at the end of input. @var{macro} is executed after the
10782 last line of the input file has been processed.
10784 For example, if the document had to have a section at the bottom of the
10785 last page for someone to approve it, the @code{em} request could be
10791 . sp |(\\n[.t] - 6v)
10805 @c =====================================================================
10807 @node Diversions, Environments, Traps, gtroff Reference
10808 @section Diversions
10811 In @code{gtroff} it is possible to @dfn{divert} text into a named
10812 storage area. Due to the similarity to defining macros it is sometimes
10813 said to be stored in a macro. This is used for saving text for output
10814 at a later time, which is useful for keeping blocks of text on the same
10815 page, footnotes, tables of contents, and indices.
10817 @cindex top-level diversion
10818 @cindex diversion, top-level
10819 For orthogonality it is said that @code{gtroff} is in the @dfn{top-level
10820 diversion} if no diversion is active (i.e., the data is diverted to the
10823 @DefreqList {di, macro}
10824 @DefreqListEnd {da, macro}
10825 @cindex beginning diversion (@code{di})
10826 @cindex diversion, beginning (@code{di})
10827 @cindex ending diversion (@code{di})
10828 @cindex diversion, ending (@code{di})
10829 @cindex appending to a diversion (@code{da})
10830 @cindex diversion, appending (@code{da})
10831 Begin a diversion. Like the @code{de}
10832 request, it takes an argument of a macro name to divert subsequent text
10833 into. The @code{da} macro appends to an existing diversion.
10835 @code{di} or @code{da} without an argument ends the diversion.
10838 @DefreqList {box, macro}
10839 @DefreqListEnd {boxa, macro}
10840 Begin (or appends to) a diversion like the
10841 @code{di} and @code{da} requests.
10842 The difference is that @code{box} and @code{boxa}
10843 do not include a partially-filled line in the diversion.
10855 @result{} Before the box. After the box.
10857 @result{} In the box.
10864 Before the diversion.
10869 After the diversion.
10871 @result{} After the diversion.
10873 @result{} Before the diversion. In the diversion.
10876 @code{box} or @code{boxa} without an argument ends the diversion.
10880 @DefregListEnd {.d}
10881 @cindex @code{nl} register, and @code{.d}
10882 @cindex nested diversions
10883 @cindex diversion, nested
10884 @cindex diversion name register (@code{.z})
10885 @cindex vertical position in diversion register (@code{.d})
10886 @cindex position, vertical, in diversion, register (@code{.d})
10887 @cindex diversion, vertical position in, register (@code{.d})
10888 Diversions may be nested. The read-only number register @code{.z}
10889 contains the name of the current diversion (this is a string-valued
10890 register). The read-only number register @code{.d} contains the current
10891 vertical place in the diversion. If not in a diversion it is the same
10892 as the register @code{nl}.
10896 @cindex high-water mark register (@code{.h})
10897 @cindex mark, high-water, register (@code{.h})
10898 @cindex position of lowest text line (@code{.h})
10899 @cindex text line, position of lowest (@code{.h})
10900 The @dfn{high-water mark} on the current page. It corresponds to the
10901 text baseline of the lowest line on the page. This is a read-only
10905 .tm .h==\n[.h], nl==\n[nl]
10906 @result{} .h==0, nl==-1
10910 .tm .h==\n[.h], nl==\n[nl]
10911 @result{} .h==40, nl==120
10914 @cindex @code{.h} register, difference to @code{nl}
10915 @cindex @code{nl} register, difference to @code{.h}
10917 As can be seen in the previous example, empty lines are not considered
10918 in the return value of the @code{.h} register.
10922 @DefregListEnd {dl}
10923 After completing a diversion, the read-write number registers @code{dn}
10924 and @code{dl} contain the vertical and horizontal size of the diversion.
10927 .\" Center text both horizontally & vertically
10929 .\" Enclose macro definitions in .eo and .ec
10930 .\" to avoid the doubling of the backslash
10932 .\" macro .(c starts centering mode
10943 .\" macro .)c terminates centering mode
10948 . nr @@s (((\n[.t]u - \n[dn]u) / 2u) - 1v)
10960 .\" End of macro definitions, restore escape mechanism
10965 @DefescList {\\!, , , }
10966 @DefescListEnd {\\?, , @Var{anything}, \\?}
10967 @cindex transparent output (@code{\!}, @code{\?})
10968 @cindex output, transparent (@code{\!}, @code{\?})
10969 Prevent requests, macros, and escapes from being
10970 interpreted when read into a diversion. This takes the given text
10971 and @dfn{transparently} embeds it into the diversion. This is useful for
10972 macros which shouldn't be invoked until the diverted text is actually
10975 The @code{\!} escape transparently embeds text up to
10976 and including the end of the line.
10977 The @code{\?} escape transparently embeds text until the next
10978 occurrence of the @code{\?} escape. For example:
10985 @var{anything} may not contain newlines; use @code{\!} to embed
10986 newlines in a diversion. The escape sequence @code{\?} is also
10987 recognized in copy mode and turned into a single internal code; it is
10988 this code that terminates @var{anything}. Thus the following example
10995 \?\\?\\\\?\\\\\\\\nx\\\\?\\?\?
11009 Both escapes read the data in copy mode.
11011 @cindex @code{\!}, in top-level diversion
11012 @cindex top-level diversion, and @code{\!}
11013 @cindex diversion, top-level, and @code{\!}
11014 If @code{\!} is used in the top-level diversion, its argument is
11015 directly embedded into the @code{gtroff} intermediate output. This can
11016 be used for example to control a postprocessor which processes the data
11017 before it is sent to the device driver.
11019 @cindex @code{\?}, in top-level diversion
11020 @cindex top-level diversion, and @code{\?}
11021 @cindex diversion, top-level, and @code{\?}
11022 The @code{\?} escape used in the top-level diversion produces no output
11023 at all; its argument is simply ignored.
11026 @cindex @code{\!}, and @code{output}
11027 @cindex @code{output} request, and @code{\!}
11028 @Defreq {output, string}
11029 Emit @var{string} directly to the @code{gtroff} intermediate output
11030 (subject to copy-mode interpretation); this is similar to @code{\!} used
11031 at the top level. An initial double quote in @var{string} is stripped off
11032 to allow initial blanks.
11034 This request can't be used before the first page has started -- if you get
11035 an error, simply insert @code{.br} before the @code{output} request.
11037 Without argument, @code{output} is ignored.
11039 Use with caution! It is normally only needed for mark-up used by a
11040 postprocessor which does something with the output before sending it to
11041 the output device, filtering out @code{string} again.
11044 @Defreq {asciify, div}
11045 @cindex unformatting diversions (@code{asciify})
11046 @cindex diversion, unformatting (@code{asciify})
11047 @cindex @code{trin} request, and @code{asciify}
11048 @dfn{Unformat} the diversion specified by @var{div}
11049 in such a way that @acronym{ASCII} characters, characters translated with
11050 the @code{trin} request, space characters, and some escape sequences that
11051 were formatted and diverted are treated like ordinary input
11052 characters when the diversion is reread. It can be also used for gross
11053 hacks; for example, the following sets register@w{ }@code{n} to@w{ }1.
11066 @xref{Copy-in Mode}.
11069 @Defreq {unformat, div}
11070 Like @code{asciify}, unformat the specified diversion.
11071 However, @code{unformat} only unformats spaces and tabs
11073 Unformatted tabs are treated as input tokens,
11074 and spaces are stretchable again.
11076 The vertical size of lines is not preserved; glyph information (font,
11077 font size, space width, etc.)@: is retained.
11081 @c =====================================================================
11083 @node Environments, Suppressing output, Diversions, gtroff Reference
11084 @section Environments
11085 @cindex environments
11087 It happens frequently that some text should be printed in a certain
11088 format regardless of what may be in effect at the time, for example, in
11089 a trap invoked macro to print headers and footers. To solve this
11090 @code{gtroff} processes text in @dfn{environments}. An
11091 environment contains most of the parameters that control text
11092 processing. It is possible to switch amongst these environments; by
11093 default @code{gtroff} processes text in environment@w{ }0. The
11094 following is the information kept in an environment.
11098 font parameters (size, family, style, glyph height and slant, space
11099 and sentence space size)
11102 page parameters (line length, title length, vertical spacing,
11103 line spacing, indentation, line numbering, centering, right-justifying,
11104 underlining, hyphenation data)
11107 fill and adjust mode
11110 tab stops, tab and leader characters, escape character,
11111 no-break and hyphen indicators, margin character data
11114 partially collected lines
11120 drawing and fill colours
11123 These environments may be given arbitrary names (see @ref{Identifiers},
11124 for more info). Old versions of @code{troff} only had environments
11125 named @samp{0}, @samp{1}, and @samp{2}.
11127 @DefreqList {ev, [@Var{env}]}
11128 @DefregListEnd {.ev}
11129 @cindex switching environments (@code{ev})
11130 @cindex environment, switching (@code{ev})
11131 @cindex environment number/name register (@code{.ev})
11132 Switch to another environment. The argument @var{env} is the name of
11133 the environment to switch to. With no argument, @code{gtroff} switches
11134 back to the previous environment. There is no limit on the number of
11135 named environments; they are created the first time that they are
11136 referenced. The @code{.ev} read-only register contains the name or
11137 number of the current environment. This is a string-valued register.
11139 Note that a call to @code{ev} (with argument) pushes the previously
11140 active environment onto a stack. If, say, environments @samp{foo},
11141 @samp{bar}, and @samp{zap} are called (in that order), the first
11142 @code{ev} request without parameter switches back to environment
11143 @samp{bar} (which is popped off the stack), and a second call
11144 switches back to environment @samp{foo}.
11146 Here is an example:
11159 \(dg Note the large, friendly letters.
11165 @cindex copying environment (@code{evc})
11166 @cindex environment, copying (@code{evc})
11167 Copy the environment @var{env} into the current environment.
11169 The following environment data is not copied:
11173 Partially filled lines.
11176 The status whether the previous line was interrupted.
11179 The number of lines still to center, or to right-justify, or to underline
11180 (with or without underlined spaces); they are set to zero.
11183 The status whether a temporary indent is active.
11186 Input traps and its associated data.
11189 Line numbering mode is disabled; it can be reactivated with
11193 The number of consecutive hyphenated lines (set to zero).
11199 @DefregListEnd {.csk}
11200 @cindex environment, last glyph
11201 The @code{\n[.cht]} register contains the
11202 maximum extent (above the baseline)
11203 of the last glyph added to the current environment.
11205 The @code{\n[.cdp]} register contains the
11206 maximum extent (below the baseline)
11207 of the last glyph added to the current environment.
11209 The @code{\n[.csk]} register contains the
11210 @dfn{skew} (how far to the right of the glyph's center
11211 that @code{gtroff} shold place an accent)
11212 of the last glyph added to the current environment.
11216 @c =====================================================================
11218 @node Suppressing output, Colors, Environments, gtroff Reference
11219 @section Suppressing output
11221 @Defesc {\\O, , num, }
11222 @cindex suppressing output (@code{\O})
11223 @cindex output, suppressing (@code{\O})
11224 Disable or enable output depending on the value of @var{num}:
11228 Disable any glyphs from being emitted to the device driver, provided that
11229 the escape occurs at the outer level (see @code{\O[3]} and @code{\O[4]}).
11230 Motion is not suppressed so effectively @code{\O[0]} means @emph{pen up}.
11233 Enable output of glyphs, provided that the escape occurs at the outer
11241 @code{\O0} and @code{\O1} also reset the four registers @samp{opminx},
11242 @samp{opminy}, @samp{opmaxx}, and @samp{opmaxy} to @minus{}1.
11243 @xref{Register Index}. These four registers mark the top left and
11244 bottom right hand corners of a box which encompasses all written glyphs.
11246 For example the input text:
11249 Hello \O[0]world \O[1]this is a test.
11253 produces the following output:
11256 Hello this is a test.
11261 Provided that the escape occurs at the outer level, enable output of
11262 glyphs and also write out to @code{stderr} the page number and four
11263 registers encompassing the glyphs previously written since the last call
11267 Begin a nesting level. At start-up, @code{gtroff} is at outer level.
11270 End a nesting level.
11272 @item \O[5@var{P}@var{filename}]
11273 This escape is @code{grohtml} specific. Provided that this escape
11274 occurs at the outer nesting level write the @code{filename} to
11275 @code{stderr}. The position of the image, @var{P}, must be specified
11276 and must be one of @code{l}, @code{r}, @code{c}, or@w{ }@code{i} (left,
11277 right, centered, inline). @var{filename} will be associated with the
11278 production of the next inline image.
11282 @c =====================================================================
11284 @node Colors, I/O, Suppressing output, gtroff Reference
11288 @DefreqList {color, [@Var{n}]}
11289 @DefregListEnd {.color}
11290 If @var{n} is missing or non-zero, activate colors (this is the default);
11291 otherwise, turn it off.
11293 The read-only number register @code{.color} is@w{ }1 if colors are active,
11296 Internally, @code{color} sets a global flag; it does not produce a token.
11297 Similar to the @code{cp} request, you should use it at the beginning of
11298 your document to control color output.
11300 Colors can be also turned off with the @option{-c} command line option.
11303 @Defreq {defcolor, ident scheme color_components}
11304 Define color with name @var{ident}. @var{scheme} can be one of the
11305 following values: @code{rgb} (three components), @code{cym} (three
11306 components), @code{cmyk} (four components), and @code{gray} or
11307 @code{grey} (one component).
11309 @cindex default color
11310 @cindex color, default
11311 Color components can be given either as a hexadecimal string or as
11312 positive decimal integers in the range 0--65535. A hexadecimal string
11313 contains all color components concatenated. It must start with either
11314 @code{#} or @code{##}; the former specifies hex values in the range
11315 0--255 (which are internally multiplied by@w{ }257), the latter in the
11316 range 0--65535. Examples: @code{#FFC0CB} (pink), @code{##ffff0000ffff}
11317 (magenta). The default color name @c{default} can't be redefined; its
11318 value is device-specific (usually black). It is possible that the
11319 default color for @code{\m} and @code{\M} is not identical.
11321 @cindex @code{f} unit, and colors
11322 @cindex unit, @code{f}, and colors
11323 A new scaling indicator@w{ }@code{f} has been introduced which multiplies
11324 its value by 65536; this makes it convenient to specify color components
11325 as fractions in the range 0 to@w{ }1 (1f equals 65536u). Example:
11328 .defcolor darkgreen rgb 0.1f 0.5f 0.2f
11331 Note that @code{f} is the default scaling indicator for the
11332 @code{defcolor} request, thus the above statement is equivalent to
11335 .defcolor darkgreen rgb 0.1 0.5 0.2
11339 @DefescList {\\m, , c, }
11340 @DefescItem {\\m, @lparen{}, co, }
11341 @DefescListEnd {\\m, @lbrack{}, color, @rbrack}
11342 Set drawing color. The following example shows how to turn the next four
11346 \m[red]these are in red\m[] and these words are in black.
11349 The escape @code{\m[]} returns to the previous color.
11351 The drawing color is associated with the current environment
11352 (@pxref{Environments}).
11354 Note that @code{\m} doesn't produce an input token in @code{gtroff}.
11355 As a consequence, it can be used in requests like @code{mc} (which
11356 expects a single character as an argument) to change the color on
11364 @DefescList {\\M, , c, }
11365 @DefescItem {\\M, @lparen{}, co, }
11366 @DefescListEnd {\\M, @lbrack{}, color, @rbrack}
11367 Set background color for filled objects drawn with the
11368 @code{\D'@dots{}'} commands.
11370 A red ellipse can be created with the following code:
11373 \M[red]\h'0.5i'\D'E 2i 1i'\M[]
11376 The escape @code{\M[]} returns to the previous fill color.
11378 The fill color is associated with the current environment
11379 (@pxref{Environments}).
11381 Note that @code{\M} doesn't produce an input token in @code{gtroff}.
11385 @c =====================================================================
11387 @node I/O, Postprocessor Access, Colors, gtroff Reference
11390 @cindex input and output requests
11391 @cindex requests for input and output
11392 @cindex output and input requests
11394 @code{gtroff} has several requests for including files:
11397 @cindex including a file (@code{so})
11398 @cindex file, inclusion (@code{so})
11399 Read in the specified @var{file} and
11400 includes it in place of the @code{so} request. This is quite useful for
11401 large documents, e.g.@: keeping each chapter in a separate file.
11402 @xref{gsoelim}, for more information.
11404 Since @code{gtroff} replaces the @code{so} request with the contents
11405 of @code{file}, it makes a difference whether the data is terminated with
11406 a newline or not: Assuming that file @file{xxx} contains the word
11407 @samp{foo} without a final newline, this
11416 yields @samp{This is foobar}.
11419 @Defreq {pso, command}
11420 Read the standard output from the specified @var{command}
11421 and includes it in place of the @code{pso} request.
11424 @cindex mode, safer
11425 @cindex unsafe mode
11426 @cindex mode, unsafe
11427 This request causes an error if used in safer mode (which is the default).
11428 Use @code{groff}'s or @code{troff}'s @option{-U} option to activate unsafe
11431 The comment regarding a final newline for the @code{so} request is valid
11432 for @code{pso} also.
11435 @Defreq {mso, file}
11436 Identical to the @code{so} request except that @code{gtroff} searches for
11437 the specified @var{file} in the same directories as macro files for the
11438 the @option{-m} command line option. If the file name to be included
11439 has the form @file{@var{name}.tmac} and it isn't found, @code{mso} tries
11440 to include @file{tmac.@var{name}} and vice versa.
11443 @DefreqList {trf, file}
11444 @DefreqListEnd {cf, file}
11445 @cindex transparent output (@code{cf}, @code{trf})
11446 @cindex output, transparent (@code{cf}, @code{trf})
11447 Transparently output the contents of @var{file}. Each line is output
11448 as if it were preceded by @code{\!}; however, the lines are not subject
11449 to copy mode interpretation. If the file does not end with a newline,
11450 then a newline is added (@code{trf} only). For example, to define a
11451 macro@w{ }@code{x} containing the contents of file@w{ }@file{f}, use
11459 Both @code{trf} and @code{cf}, when used in a diversion,
11460 embeds an object in the diversion which, when reread, causes the
11461 contents of @var{file} to be transparently copied through to the
11462 output. In @acronym{UNIX} @code{troff}, the contents of @var{file}
11463 is immediately copied through to the output regardless of whether there
11464 is a current diversion; this behaviour is so anomalous that it must be
11467 @cindex @code{trf} request, and invalid characters
11468 @cindex characters, invalid for @code{trf} request
11469 @cindex invalid characters for @code{trf} request
11470 While @code{cf} copies the contents of @var{file} completely unprocessed,
11471 @code{trf} disallows characters such as NUL that are not valid
11472 @code{gtroff} input characters (@pxref{Identifiers}).
11474 Both requests cause a line break.
11477 @Defreq {nx, [@Var{file}]}
11478 @cindex processing next file (@code{nx})
11479 @cindex file, processing next (@code{nx})
11480 @cindex next file, processing (@code{nx})
11481 Force @code{gtroff} to continue processing of
11482 the file specified as an argument. If no argument is given, immediately
11483 jump to the end of file.
11486 @Defreq {rd, [@Var{prompt} [@Var{arg1} @Var{arg2} @dots{}]]}
11487 @cindex reading from standard input (@code{rd})
11488 @cindex standard input, reading from (@code{rd})
11489 @cindex input, standard, reading from (@code{rd})
11490 Read from standard input, and include what is read as though it
11491 were part of the input file. Text is read until a blank line
11494 If standard input is a TTY input device (keyboard), write @var{prompt}
11495 to standard error, followed by a colon (or send BEL for a beep if no
11496 argument is given).
11498 Arguments after @var{prompt} are available for the input. For example,
11505 with the input @w{@samp{This is \$2.}} prints
11512 @cindex form letters
11513 @cindex letters, form
11514 Using the @code{nx} and @code{rd} requests,
11515 it is easy to set up form letters. The form
11516 letter template is constructed like this, putting the following lines
11517 into a file called @file{repeat.let}:
11533 @cindex @code{ex} request, used with @code{nx} and @code{rd}
11535 When this is run, a file containing the following lines should be
11536 redirected in. Note that requests included in this file are executed
11537 as though they were part of the form letter. The last block of input
11538 is the @code{ex} request which tells @code{groff} to stop processing. If
11539 this was not there, @code{groff} would not know when to stop.
11543 708 NW 19th Av., #202
11550 San Diego, CA 92103
11558 Pipe the output of @code{gtroff} to the shell command(s)
11559 specified by @var{pipe}. This request must occur before
11560 @code{gtroff} has a chance to print anything.
11563 @cindex mode, safer
11564 @cindex unsafe mode
11565 @cindex mode, unsafe
11566 @code{pi} causes an error if used in safer mode (which is the default).
11567 Use @code{groff}'s or @code{troff}'s @option{-U} option to activate unsafe
11570 Multiple calls to @code{pi} are allowed, acting as a chain. For example,
11578 is the same as @w{@samp{.pi foo | bar}}.
11580 @cindex @code{groff}, and @code{pi} request
11581 @cindex @code{pi} request, and @code{groff}
11582 Note that the intermediate output format of @code{gtroff} is piped to
11583 the specified commands. Consequently, calling @code{groff} without the
11584 @option{-Z} option normally causes a fatal error.
11587 @DefreqList {sy, cmds}
11588 @DefregListEnd {systat}
11589 Execute the shell command(s) specified by @var{cmds}. The output is not
11590 saved anyplace, so it is up to the user to do so.
11593 @cindex mode, safer
11594 @cindex unsafe mode
11595 @cindex mode, unsafe
11596 This request causes an error if used in safer mode (which is the default).
11597 Use @code{groff}'s or @code{troff}'s @option{-U} option to activate unsafe
11600 For example, the following code fragment introduces the current time into a
11603 @cindex time, current
11604 @cindex current time
11607 .sy perl -e 'printf ".nr H %d\\n.nr M %d\\n.nr S %d\\n",\
11608 (localtime(time))[2,1,0]' > /tmp/x\n[$$]
11610 .sy rm /tmp/x\n[$$]
11615 Note that this works by having the @code{perl} script (run by @code{sy})
11616 print out the @code{nr} requests which set the number registers
11617 @code{H}, @code{M}, and @code{S}, and then reads those commands in with
11618 the @code{so} request.
11620 For most practical purposes, the number registers @code{seconds},
11621 @code{minutes}, and @code{hours} which are initialized at start-up of
11622 @code{gtroff} should be sufficient. Use the @code{af} request to get a
11629 \n[hours]:\n[minutes]:\n[seconds]
11632 @cindex @code{system()} return value register (@code{systat})
11633 The @code{systat} read-write number register contains the return value
11634 of the @code{system()} function executed by the last @code{sy} request.
11637 @DefreqList {open, stream file}
11638 @DefreqListEnd {opena, stream file}
11639 @cindex opening file (@code{open})
11640 @cindex file, opening (@code{open})
11641 @cindex appending to a file (@code{opena})
11642 @cindex file, appending to (@code{opena})
11643 Open the specified @var{file} for writing and
11644 associates the specified @var{stream} with it.
11646 The @code{opena} request is like @code{open}, but if the file exists,
11647 append to it instead of truncating it.
11650 @cindex mode, safer
11651 @cindex unsafe mode
11652 @cindex mode, unsafe
11653 Both @code{open} and @code{opena} cause an error if used in safer mode
11654 (which is the default). Use @code{groff}'s or @code{troff}'s @option{-U}
11655 option to activate unsafe mode.
11658 @DefreqList {write, stream data}
11659 @DefreqListEnd {writec, stream data}
11660 @cindex copy-in mode, and @code{write} requests
11661 @cindex mode, copy-in, and @code{write} requests
11662 @cindex writing to file (@code{write})
11663 @cindex file, writing to (@code{write})
11664 Write to the file associated with the specified @var{stream}.
11665 The stream must previously have
11666 been the subject of an open request. The remainder of the line is
11667 interpreted as the @code{ds} request reads its second argument: A
11668 leading @samp{"} is stripped, and it is read in copy-in mode.
11670 The @code{writec} request is like @code{write}, but only
11671 @code{write} appends a newline to the data.
11674 @Defreq {writem, stream xx}
11675 @cindex @code{asciify} request, and @code{writem}
11676 Write the contents of the macro or string @var{xx}
11677 to the file associated with the specified @var{stream}.
11679 @var{xx} is read in copy mode, i.e., already formatted elements are
11680 ignored. Consequently, diversions must be unformatted with the
11681 @code{asciify} request before calling @code{writem}. Usually, this
11682 means a loss of information.
11685 @Defreq {close, stream}
11686 @cindex closing file (@code{close})
11687 @cindex file, closing (@code{close})
11688 Close the specified @var{stream};
11689 the stream is no longer an acceptable argument to the
11690 @code{write} request.
11692 Here a simple macro to write an index entry.
11698 . write idx \\n[%] \\$*
11707 @DefescList {\\V, , e, }
11708 @DefescItem {\\V, @lparen{}, ev, }
11709 @DefescListEnd {\\V, @lbrack{}, env, @rbrack}
11710 Interpolate the contents of the specified environment variable
11711 @var{env} (one-character name@w{ }@var{e}, two-character name @var{ev})
11712 as returned by the function @code{getenv}. @code{\V} is interpreted
11717 @c =====================================================================
11719 @node Postprocessor Access, Miscellaneous, I/O, gtroff Reference
11720 @section Postprocessor Access
11721 @cindex postprocessor access
11722 @cindex access of postprocessor
11724 There are two escapes which give information directly to the
11725 postprocessor. This is particularly useful for embedding
11726 @sc{PostScript} into the final document.
11728 @Defesc {\\X, ', xxx, '}
11729 Embeds its argument into the @code{gtroff}
11730 output preceded with @w{@samp{x X}}.
11732 @cindex @code{\&}, in @code{\X}
11733 @cindex @code{\)}, in @code{\X}
11734 @cindex @code{\%}, in @code{\X}
11736 @cindex @code{\:}, in @code{\X}
11739 @cindex @code{\@r{<colon>}}, in @code{\X}
11741 The escapes @code{\&}, @code{\)}, @code{\%}, and @code{\:} are ignored
11742 within @code{\X}, @w{@samp{\ }} and @code{\~} are converted to single
11743 space characters. All other escapes (except @code{\\} which produces a
11744 backslash) cause an error.
11746 @kindex use_charnames_in_special
11747 @pindex DESC@r{, and @code{use_charnames_in_special}}
11748 @cindex @code{\X}, and special characters
11749 If the @samp{use_charnames_in_special} keyword is set in the @file{DESC}
11750 file, special characters no longer cause an error; the name @var{xx} is
11751 represented as @samp{\(@var{xx})} in the @w{@samp{x X}} output command.
11752 Additionally, the backslash is represented as @code{\\}.
11754 @samp{use_charnames_in_special} is currently used by @code{grohtml} only.
11757 @DefescList {\\Y, , n, }
11758 @DefescItem {\\Y, @lparen{}, nm, }
11759 @DefescListEnd {\\Y, @lbrack{}, name, @rbrack}
11760 This is approximately equivalent to @samp{\X'\*[@var{name}]'}
11761 (one-character name@w{ }@var{n}, two-character name @var{nm}).
11762 However, the contents of the string or macro @var{name} are not
11763 interpreted; also it is permitted for @var{name} to have been defined
11764 as a macro and thus contain newlines (it is not permitted for the
11765 argument to @code{\X} to contain newlines). The inclusion of
11766 newlines requires an extension to the @acronym{UNIX} @code{troff}
11767 output format, and confuses drivers that do not know about this
11768 extension (@pxref{Device Control Commands}).
11771 @xref{Output Devices}.
11774 @c =====================================================================
11776 @node Miscellaneous, Gtroff Internals, Postprocessor Access, gtroff Reference
11777 @section Miscellaneous
11779 This section documents parts of @code{gtroff} which cannot (yet) be
11780 categorized elsewhere in this manual.
11782 @Defreq {nm, [@Var{start} [@Var{inc} [@Var{space} [@Var{indent}]]]]}
11783 @cindex printing line numbers (@code{nm})
11784 @cindex line numbers, printing (@code{nm})
11785 @cindex numbers, line, printing (@code{nm})
11786 Print line numbers.
11787 @var{start} is the line number of the @emph{next}
11788 output line. @var{inc} indicates which line numbers are printed.
11789 For example, the value@w{ }5 means to emit only line numbers which
11790 are multiples of@w{ }5; this defaults to@w{ }1. @var{space} is the
11791 space to be left between the number and the text; this defaults to
11792 one digit space. The fourth argument is the indentation of the line
11793 numbers, defaulting to zero. Both @var{space} and @var{indent} are
11794 given as multiples of digit spaces; they can be negative also.
11795 Without any arguments, line numbers are turned off.
11797 @code{gtroff} reserves three digit spaces for the line number (which is
11798 printed right-justified) plus the amount given by @var{indent}; the
11799 output lines are concatenated to the line numbers, separated by
11800 @var{space}, and @emph{without} reducing the line length. Depending
11801 on the value of the horizontal page offset (as set with the
11802 @code{po} request), line numbers which are longer than the reserved
11803 space stick out to the left, or the whole line is moved to the right.
11805 Parameters corresponding to missing arguments are not changed; any
11806 non-digit argument (to be more precise, any argument starting with a
11807 character valid as a delimiter for identifiers) is also treated as
11810 If line numbering has been disabled with a call to @code{nm} without
11811 an argument, it can be reactivated with @samp{.nm +0}, using the
11812 previously active line numbering parameters.
11814 The parameters of @code{nm} are associated with the current environment
11815 (@pxref{Environments}). The current output line number is available
11816 in the number register @code{ln}.
11821 This test shows how line numbering works with groff.
11823 This test shows how line numbering works with groff.
11827 This test shows how line numbering works with groff.
11829 This test shows how line numbering works with groff.
11833 And here the result:
11836 This test shows how
11837 line numbering works
11838 999 with groff. This
11839 1000 test shows how line
11840 1001 numbering works with
11842 This test shows how
11845 This test shows how
11846 1005 line numbering
11851 @Defreq {nn, [@Var{skip}]}
11852 Temporarily turn off line numbering. The argument is the number
11853 of lines not to be numbered; this defaults to@w{ }1.
11856 @Defreq {mc, glyph [@Var{dist}]}
11857 @cindex margin glyph (@code{mc})
11858 @cindex glyph, for margins (@code{mc})
11859 Print a @dfn{margin character} to the right of the
11860 text.@footnote{@dfn{Margin character} is a misnomer since it is an
11861 output glyph.} The first argument is the glyph to be
11862 printed. The second argument is the distance away from the right
11863 margin. If missing, the previously set value is used; default is
11864 10@dmn{pt}). For text lines that are too long (that is, longer than
11865 the text length plus @var{dist}), the margin character is directly
11866 appended to the lines.
11868 With no arguments the margin character is turned off.
11869 If this occurs before a break, no margin character is printed.
11871 @cindex @code{tl} request, and @code{mc}
11872 For empty lines and lines produced by the @code{tl} request no margin
11873 character is emitted.
11875 The margin character is associated with the current environment
11876 (@pxref{Environments}).
11880 This is quite useful for indicating text that has changed, and, in fact,
11881 there are programs available for doing this (they are called
11882 @code{nrchbar} and @code{changebar} and can be found in any
11883 @samp{comp.sources.unix} archive.
11888 This paragraph is highlighted with a margin
11891 Note that vertical space isn't marked.
11895 But we can fake it with `\&'.
11901 This paragraph is highlighted |
11902 with a margin character. |
11904 Note that vertical space isn't |
11907 But we can fake it with `\&'. |
11911 @DefreqList {psbb, filename}
11915 @DefregListEnd {ury}
11916 @cindex PostScript, bounding box
11917 @cindex bounding box
11918 Retrieve the bounding box of the PostScript image
11919 found in @var{filename}.
11920 The file must conform to
11921 Adobe's @dfn{Document Structuring Conventions} (DSC);
11922 the command searches for a @code{%%BoundingBox} comment
11923 and extracts the bounding box values into the number registers
11924 @code{llx}, @code{lly}, @code{urx}, and @code{ury}.
11925 If an error occurs (for example, @code{psbb} cannot find
11926 the @code{%%BoundingBox} comment),
11927 it sets the four number registers to zero.
11931 @c =====================================================================
11933 @node Gtroff Internals, Debugging, Miscellaneous, gtroff Reference
11934 @section @code{gtroff} Internals
11936 @cindex input token
11937 @cindex token, input
11938 @cindex output node
11939 @cindex node, output
11940 @code{gtroff} processes input in three steps. One or more input
11941 characters are converted to an @dfn{input token}.@footnote{Except the
11942 escapes @code{\f}, @code{\F}, @code{\H}, @code{\m}, @code{\M}, @code{\R},
11943 @code{\s}, and @code{\S} which are processed immediately if not in
11944 copy-in mode.} Then, one or more input tokens are converted to an
11945 @dfn{output node}. Finally, output nodes are converted to the
11946 intermediate output language understood by all output devices.
11948 Actually, before step one happens, @code{gtroff} converts certain
11949 escape sequences into reserved input characters (not accessible by
11950 the user); such reserved characters are used for other internal
11951 processing also -- this is the very reason why not all characters
11952 are valid input. @xref{Identifiers}, for more on this topic.
11954 For example, the input string @samp{fi\[:u]} is converted into a
11955 character token @samp{f}, a character token @samp{i}, and a special
11956 token @samp{:u} (representing u@w{ }umlaut). Later on, the character
11957 tokens @samp{f} and @samp{i} are merged to a single output node
11958 representing the ligature glyph @samp{fi} (provided the current font
11959 has a glyph for this ligature); the same happens with @samp{:u}. All
11960 output glyph nodes are `processed' which means that they are invariably
11961 associated with a given font, font size, advance width, etc. During
11962 the formatting process, @code{gtroff} itself adds various nodes to
11963 control the data flow.
11965 Macros, diversions, and strings collect elements in two chained lists:
11966 a list of input tokens which have been passed unprocessed, and a list
11967 of output nodes. Consider the following the diversion.
11979 It contains these elements.
11981 @multitable {@i{vertical size node}} {token list} {element number}
11982 @item node list @tab token list @tab element number
11984 @item @i{line start node} @tab --- @tab 1
11985 @item @i{glyph node @code{a}} @tab --- @tab 2
11986 @item @i{word space node} @tab --- @tab 3
11987 @item --- @tab @code{b} @tab 4
11988 @item --- @tab @code{\n} @tab 5
11989 @item @i{glyph node @code{c}} @tab --- @tab 6
11990 @item @i{vertical size node} @tab --- @tab 7
11991 @item @i{vertical size node} @tab --- @tab 8
11992 @item --- @tab @code{\n} @tab 9
11995 @cindex @code{\v}, internal representation
11997 Elements 1, 7, and@w{ }8 are inserted by @code{gtroff}; the latter two
11998 (which are always present) specify the vertical extent of the last
11999 line, possibly modified by @code{\x}. The @code{br} request finishes
12000 the current partial line, inserting a newline input token which is
12001 subsequently converted to a space when the diversion is reread. Note
12002 that the word space node has a fixed width which isn't stretchable
12003 anymore. To convert horizontal space nodes back to input tokens, use
12004 the @code{unformat} request.
12006 Macros only contain elements in the token list (and the node list is
12007 empty); diversions and strings can contain elements in both lists.
12009 Note that the @code{chop} request simply reduces the number of elements in a
12010 macro, string, or diversion by one. Exceptions are @dfn{compatibility save}
12011 and @dfn{compatibility ignore} input tokens which are ignored. The
12012 @code{substring} request also ignores those input tokens.
12014 Some requests like @code{tr} or @code{cflags} work on glyph
12015 identifiers only; this means that the associated glyph can be changed
12016 without destroying this association. This can be very helpful for
12017 substituting glyphs. In the following example, we assume that
12018 glyph @samp{foo} isn't available by default, so we provide a
12019 substitution using the @code{fchar} request and map it to input
12020 character @samp{x}.
12028 Now let us assume that we install an additional special font
12029 @samp{bar} which has glyph @samp{foo}.
12037 Since glyphs defined with @code{fchar} are searched before glyphs
12038 in special fonts, we must call @code{rchar} to remove the definition
12039 of the fallback glyph. Anyway, the translation is still active;
12040 @samp{x} now maps to the real glyph @samp{foo}.
12043 @c =====================================================================
12045 @node Debugging, Implementation Differences, Gtroff Internals, gtroff Reference
12049 @code{gtroff} is not easy to debug, but there are some useful features
12050 and strategies for debugging.
12052 @Defreq {lf, line filename}
12054 @cindex multi-file documents
12055 @cindex documents, multi-file
12056 @cindex setting input line number (@code{lf})
12057 @cindex input line number, setting (@code{lf})
12058 @cindex number, input line, setting (@code{lf})
12059 Change the line number and the file name @code{gtroff} shall use for
12060 error and warning messages. @var{line} is the input line number of the
12063 Without argument, the request is ignored.
12065 This is a debugging aid for documents which are split into many files,
12066 then put together with @code{soelim} and other preprocessors. Usually,
12067 it isn't invoked manually.
12070 @DefreqList {tm, string}
12071 @DefreqItem {tm1, string}
12072 @DefreqListEnd {tmc, string}
12073 @cindex printing to stderr (@code{tm}, @code{tm1}, @code{tmc})
12074 @cindex stderr, printing to (@code{tm}, @code{tm1}, @code{tmc})
12075 Send @var{string} to the standard error output;
12076 this is very useful for printing debugging messages among other things.
12078 @var{string} is read in copy mode.
12080 The @code{tm} request ignores leading spaces of @var{string}; @code{tm1}
12081 handles its argument similar to the @code{ds} request: a leading double
12082 quote in @var{string} is stripped to allow initial blanks.
12084 The @code{tmc} request is similar to @code{tm1} but does
12085 not append a newline (as is done in @code{tm} and @code{tm1}).
12088 @Defreq {ab, [@Var{string}]}
12089 @cindex aborting (@code{ab})
12090 Similar to the @code{tm} request, except that
12091 it causes @code{gtroff} to stop processing. With no argument it
12092 prints @samp{User Abort.} to standard error.
12096 @cindex @code{ex} request, use in debugging
12097 @cindex exiting (@code{ex})
12098 The @code{ex} request also causes @code{gtroff} to stop processing;
12099 see also @ref{I/O}.
12102 When doing something involved it is useful to leave the debugging
12103 statements in the code and have them turned on by a command line flag.
12106 .if \n(DB .tm debugging output
12110 To activate these statements say
12116 If it is known in advance that there will be many errors and no useful
12117 output, @code{gtroff} can be forced to suppress formatted output with
12118 the @option{-z} flag.
12121 @cindex dumping symbol table (@code{pm})
12122 @cindex symbol table, dumping (@code{pm})
12123 Print the entire symbol table on @code{stderr}. Names of all defined
12124 macros, strings, and diversions are print together with their size in
12125 bytes. Since @code{gtroff} sometimes adds nodes by itself, the
12126 returned size can be larger than expected.
12128 This request differs from @acronym{UNIX} @code{troff}: @code{gtroff}
12129 reports the sizes of diversions, ignores an additional argument to
12130 print only the total of the sizes, and the size isn't returned in
12131 blocks of 128 characters.
12135 @cindex dumping number registers (@code{pnr})
12136 @cindex number registers, dumping (@code{pnr})
12137 Print the names and contents of all
12138 currently defined number registers on @code{stderr}.
12142 @cindex dumping traps (@code{ptr})
12143 @cindex traps, dumping (@code{ptr})
12144 Print the names and positions of all traps
12145 (not including input line traps and diversion traps) on @code{stderr}.
12146 Empty slots in the page trap list are printed as well, because they can
12147 affect the priority of subsequently planted traps.
12151 @cindex flush output (@code{fl})
12152 @cindex output, flush (@code{fl})
12153 @cindex interactive use of @code{gtroff}
12154 @cindex @code{gtroff}, interactive use
12155 Instruct @code{gtroff} to flush its output immediately. The intent
12156 is for interactive use, but this behaviour is currently not
12157 implemented in @code{gtroff}. Contrary to @acronym{UNIX} @code{troff},
12158 TTY output is sent to a device driver also (@code{grotty}), making it
12159 non-trivial to communicate interactively.
12161 This request causes a line break.
12164 @Defreq {backtrace, }
12165 @cindex backtrace of input stack (@code{backtrace})
12166 @cindex input stack, backtrace (@code{backtrace})
12167 Print a backtrace of the input stack to the standard error stream.
12169 Consider the following in file @file{test}:
12183 On execution, @code{gtroff} prints the following:
12186 test:2: backtrace: macro `xxx'
12187 test:5: backtrace: macro `yyy'
12188 test:8: backtrace: file `test'
12191 The option @option{-b} of @code{gtroff} internally calls a variant of
12192 this request on each error and warning.
12196 @cindex input stack, setting limit
12197 Use the @code{slimit} number register
12198 to set the maximum number of objects on the input stack.
12199 If @code{slimit} is less than or equal to@w{ }0,
12200 there is no limit set.
12201 With no limit, a buggy recursive macro can exhaust virtual memory.
12203 The default value is 1000; this is a compile-time constant.
12206 @Defreq {warnscale, si}
12207 Set the scaling indicator used in warnings to @var{si}. Valid values for
12208 @var{si} are @samp{u}, @samp{i}, @samp{c}, @samp{p}, and @samp{P}. At
12209 startup, it is set to @samp{i}.
12212 @Defreq {spreadwarn, [@Var{limit}]}
12213 Make @code{gtroff} emit a warning if the additional space inserted for
12214 each space between words in an output line is larger or equal to
12215 @var{limit}. A negative value is changed to zero; no argument toggles the
12216 warning on and off without changing @var{limit}. The default scaling
12217 indicator is @samp{m}. At startup, @code{spreadwarn} is deactivated, and
12218 @var{limit} is set to 3@dmn{m}.
12227 will cause a warning if @code{gtroff} must add 0.2@dmn{m} or more for each
12228 interword space in a line.
12230 This request is active only if text is justified to both margins (using
12235 @code{gtroff} has command line options for printing out more warnings
12236 (@option{-w}) and for printing backtraces (@option{-b}) when a warning
12237 or an error occurs. The most verbose level of warnings is @option{-ww}.
12239 @DefreqList {warn, [@Var{flags}]}
12240 @DefregListEnd {.warn}
12241 @cindex level of warnings (@code{warn})
12242 @cindex warnings, level (@code{warn})
12243 Control the level of warnings checked for. The @var{flags} are the sum
12244 of the numbers associated with each warning that is to be enabled; all
12245 other warnings are disabled. The number associated with each warning is
12246 listed below. For example, @w{@code{.warn 0}} disables all warnings,
12247 and @w{@code{.warn 1}} disables all warnings except that about missing
12248 glyphs. If no argument is given, all warnings are enabled.
12250 The read-only number register @code{.warn} contains the current warning
12258 @c ---------------------------------------------------------------------
12260 @node Warnings, , Debugging, Debugging
12261 @subsection Warnings
12264 The warnings that can be given to @code{gtroff} are divided into the
12265 following categories. The name associated with each warning is used by
12266 the @option{-w} and @option{-W} options; the number is used by the
12267 @code{warn} request and by the @code{.warn} register.
12272 Non-existent glyphs.@footnote{@code{char} is a misnomer since it reports
12273 missing glyphs -- there aren't missing input characters, only invalid
12274 ones.} This is enabled by default.
12278 Invalid numeric expressions. This is enabled by default.
12279 @xref{Expressions}.
12285 In fill mode, lines which could not be broken so that their length was
12286 less than the line length. This is enabled by default.
12290 Missing or mismatched closing delimiters.
12294 @cindex @code{ie} request, and warnings
12295 @cindex @code{el} request, and warnings
12296 Use of the @code{el} request with no matching @code{ie} request.
12301 Meaningless scaling indicators.
12305 Out of range arguments.
12309 Dubious syntax in numeric expressions.
12313 @cindex @code{di} request, and warnings
12314 @cindex @code{da} request, and warnings
12315 Use of @code{di} or @code{da} without an argument when there is no
12320 @cindex @code{de}, @code{de1}, @code{dei} requests, and warnings
12321 @cindex @code{am}, @code{am1}, @code{ami} requests, and warnings
12322 @cindex @code{ds}, @code{ds1} requests, and warnings
12323 @cindex @code{as}, @code{as1} requests, and warnings
12324 @cindex @code{di} request, and warnings
12325 @cindex @code{da} request, and warnings
12326 @cindex @code{box}, @code{boxa} requests, and warnings
12327 @cindex @code{\*}, and warnings
12328 Use of undefined strings, macros and diversions. When an undefined
12329 string, macro, or diversion is used, that string is automatically
12330 defined as empty. So, in most cases, at most one warning is given
12335 @cindex @code{nr} request, and warnings
12336 @cindex @code{\R}, and warnings
12337 @cindex @code{\n}, and warnings
12338 Use of undefined number registers. When an undefined number register is
12339 used, that register is automatically defined to have a value of@w{ }0.
12340 So, in most cases, at most one warning is given for use of a particular
12345 @cindex @code{\t}, and warnings
12346 Use of a tab character where a number was expected.
12350 @cindex @code{\@}}, and warnings
12351 Use of @code{\@}} where a number was expected.
12355 Requests that are missing non-optional arguments.
12359 Invalid input characters.
12363 Unrecognized escape sequences. When an unrecognized escape sequence
12364 @code{\@var{X}} is encountered, the escape character is ignored, and
12365 @var{X} is printed.
12369 @cindex compatibility mode
12370 Missing space between a request or macro and its argument. This warning
12371 is given when an undefined name longer than two characters is
12372 encountered, and the first two characters of the name make a defined
12373 name. The request or macro is not invoked. When this warning is
12374 given, no macro is automatically defined. This is enabled by default.
12375 This warning never occurs in compatibility mode.
12379 Non-existent fonts. This is enabled by default.
12383 Invalid escapes in text ignored with the @code{ig} request. These are
12384 conditions that are errors when they do not occur in ignored text.
12388 Color related warnings.
12391 All warnings except @samp{di}, @samp{mac} and @samp{reg}. It is
12392 intended that this covers all warnings that are useful with traditional
12400 @c =====================================================================
12402 @node Implementation Differences, , Debugging, gtroff Reference
12403 @section Implementation Differences
12404 @cindex implementation differences
12405 @cindex differences in implementation
12406 @cindex incompatibilities with @acronym{AT&T} @code{troff}
12407 @cindex compatibility mode
12408 @cindex mode, compatibility
12410 GNU @code{troff} has a number of features which cause incompatibilities
12411 with documents written with old versions of @code{troff}.
12414 @cindex names, long
12415 Long names cause some incompatibilities. @acronym{UNIX} @code{troff}
12422 @cindex @code{\*}, incompatibilities with @acronym{AT&T} @code{troff}
12423 @cindex @code{\n}, incompatibilities with @acronym{AT&T} @code{troff}
12425 as defining a string @samp{ab} with contents @samp{cd}. Normally, GNU
12426 @code{troff} interprets this as a call of a macro named
12427 @code{dsabcd}. Also @acronym{UNIX} @code{troff} interprets
12428 @code{\*[} or @code{\n[} as references to a string or number register
12429 called @samp{[}. In GNU @code{troff}, however, this is normally
12430 interpreted as the start of a long name. In compatibility mode GNU
12431 @code{troff} interprets long names in the traditional way
12432 (which means that they are not recognized as names).
12434 @DefreqList {cp, [@Var{n}]}
12435 @DefreqItem {do, cmd}
12436 @DefregListEnd {.C}
12437 If @var{n} is missing or non-zero, turn on compatibility mode;
12438 otherwise, turn it off.
12440 The read-only number register @code{.C} is@w{ }1 if compatibility mode is
12441 on, 0@w{ }otherwise.
12443 Compatibility mode can be also turned on with the @option{-C} command line
12446 The @code{do} request turns off compatibility mode
12447 while executing its arguments as a @code{gtroff} command.
12454 executes the @code{fam} request when compatibility mode
12457 @code{gtroff} restores the previous compatibility setting
12458 before interpreting any files sourced by the @var{cmd}.
12461 @cindex input level in delimited arguments
12462 @cindex delimited arguments, incompatibilities with @acronym{AT&T} @code{troff}
12463 Two other features are controlled by @option{-C}. If not in
12464 compatibility mode, GNU @code{troff} preserves the input level in
12465 delimited arguments:
12473 In compatibility mode, the string @samp{72def'} is returned; without
12474 @option{-C} the resulting string is @samp{168} (assuming a TTY output
12477 @cindex @code{\f}, incompatibilities with @acronym{AT&T} @code{troff}
12478 @cindex @code{\H}, incompatibilities with @acronym{AT&T} @code{troff}
12479 @cindex @code{\s}, incompatibilities with @acronym{AT&T} @code{troff}
12480 @cindex @code{\S}, incompatibilities with @acronym{AT&T} @code{troff}
12481 Finally, the escapes @code{\f}, @code{\H}, @code{\m}, @code{\M},
12482 @code{\R}, @code{\s}, and @code{\S} are transparent for recognizing the
12483 beginning of a line only in compatibility mode (this is a rather obscure
12484 feature). For example, the code
12493 prints @samp{Hallo!} in bold face if in compatibility mode, and
12494 @samp{.xx} in bold face otherwise.
12496 @cindex @code{\A}, incompatibilities with @acronym{AT&T} @code{troff}
12497 @cindex @code{\|}, incompatibilities with @acronym{AT&T} @code{troff}
12498 @cindex @code{\^}, incompatibilities with @acronym{AT&T} @code{troff}
12499 @cindex @code{\&}, incompatibilities with @acronym{AT&T} @code{troff}
12500 @cindex @code{\@{}, incompatibilities with @acronym{AT&T} @code{troff}
12501 @cindex @code{\@}}, incompatibilities with @acronym{AT&T} @code{troff}
12502 @cindex @code{\@key{SP}}, incompatibilities with @acronym{AT&T} @code{troff}
12503 @cindex @code{\'}, incompatibilities with @acronym{AT&T} @code{troff}
12504 @cindex @code{\`}, incompatibilities with @acronym{AT&T} @code{troff}
12505 @cindex @code{\-}, incompatibilities with @acronym{AT&T} @code{troff}
12506 @cindex @code{\_}, incompatibilities with @acronym{AT&T} @code{troff}
12507 @cindex @code{\!}, incompatibilities with @acronym{AT&T} @code{troff}
12508 @cindex @code{\%}, incompatibilities with @acronym{AT&T} @code{troff}
12509 @cindex @code{\c}, incompatibilities with @acronym{AT&T} @code{troff}
12510 GNU @code{troff} does not allow the use of the escape sequences
12511 @code{\|}, @code{\^}, @code{\&}, @code{\@{}, @code{\@}},
12512 @code{\@key{SP}}, @code{\'}, @code{\`}, @code{\-}, @code{\_}, @code{\!},
12513 @code{\%}, and @code{\c} in names of strings, macros, diversions, number
12514 registers, fonts or environments; @acronym{UNIX} @code{troff} does. The
12515 @code{\A} escape sequence (@pxref{Identifiers}) may be helpful in
12516 avoiding use of these escape sequences in names.
12518 @cindex fractional point sizes
12519 @cindex fractional type sizes
12520 @cindex point sizes, fractional
12521 @cindex type sizes, fractional
12522 @cindex sizes, fractional
12523 @cindex @code{ps} request, incompatibilities with @acronym{AT&T} @code{troff}
12524 Fractional point sizes cause one noteworthy incompatibility. In
12525 @acronym{UNIX} @code{troff} the @code{ps} request ignores scale
12526 indicators and thus
12533 sets the point size to 10@w{ }points, whereas in GNU @code{troff} it
12534 sets the point size to 10@w{ }scaled points. @xref{Fractional Type
12535 Sizes}, for more information.
12537 @cindex @code{bd} request, incompatibilities with @acronym{AT&T} @code{troff}
12538 @cindex @code{cs} request, incompatibilities with @acronym{AT&T} @code{troff}
12539 @cindex @code{tr} request, incompatibilities with @acronym{AT&T} @code{troff}
12540 @cindex @code{fp} request, incompatibilities with @acronym{AT&T} @code{troff}
12541 @cindex input characters and output glyphs, compatibility with @acronym{AT&T} @code{troff}
12542 @cindex output glyphs, and input characters,compatibility with @acronym{AT&T} @code{troff}
12543 @cindex characters, input, and output glyphs, compatibility with @acronym{AT&T} @code{troff}
12544 @cindex glyphs, output, and input characters, compatibility with @acronym{AT&T} @code{troff}
12545 In GNU @code{troff} there is a fundamental difference between
12546 (unformatted) input characters and (formatted) output glyphs.
12547 Everything that affects how a glyph is output is stored
12548 with the glyph node; once a glyph node has been constructed it is
12549 unaffected by any subsequent requests that are executed, including
12550 @code{bd}, @code{cs}, @code{tkf}, @code{tr}, or @code{fp} requests.
12551 Normally glyphs are constructed from input characters at the
12552 moment immediately before the glyph is added to the current output
12553 line. Macros, diversions and strings are all, in fact, the same type of
12554 object; they contain lists of input characters and glyph nodes in
12555 any combination. A glyph node does not behave like an input
12556 character for the purposes of macro processing; it does not inherit any
12557 of the special properties that the input character from which it was
12558 constructed might have had. For example,
12568 @cindex printing backslash (@code{\\}, @code{\e}, @code{\E}, @code{\[rs]})
12569 @cindex backslash, printing (@code{\\}, @code{\e}, @code{\E}, @code{\[rs]})
12570 @cindex @code{\e}, incompatibilities with @acronym{AT&T} @code{troff}
12571 @cindex @code{\!}, incompatibilities with @acronym{AT&T} @code{troff}
12572 @cindex @code{\?}, incompatibilities with @acronym{AT&T} @code{troff}
12573 @cindex transparent output, incompatibilities with @acronym{AT&T} @code{troff}
12574 @cindex output, transparent, incompatibilities with @acronym{AT&T} @code{troff}
12576 prints @samp{\\} in GNU @code{troff}; each pair of input backslashes
12577 is turned into one output backslash and the resulting output backslashes
12578 are not interpreted as escape characters when they are reread.
12579 @acronym{UNIX} @code{troff} would interpret them as escape characters
12580 when they were reread and would end up printing one @samp{\}. The
12581 correct way to obtain a printable backslash is to use the @code{\e}
12582 escape sequence: This always prints a single instance of the current
12583 escape character, regardless of whether or not it is used in a
12584 diversion; it also works in both GNU @code{troff} and @acronym{UNIX}
12585 @code{troff}.@footnote{To be completely independent of the current
12586 escape character, use @code{\(rs} which represents a reverse solidus
12587 (backslash) glyph.} To store, for some reason, an escape sequence in a
12588 diversion that will be interpreted when the diversion is reread, either
12589 use the traditional @code{\!} transparent output facility, or, if this
12590 is unsuitable, the new @code{\?} escape sequence.
12592 @xref{Diversions}, and @ref{Gtroff Internals}, for more information.
12596 @c =====================================================================
12597 @c =====================================================================
12599 @node Preprocessors, Output Devices, gtroff Reference, Top
12600 @chapter Preprocessors
12601 @cindex preprocessors
12603 This chapter describes all preprocessors that come with @code{groff} or
12604 which are freely available.
12617 @c =====================================================================
12619 @node geqn, gtbl, Preprocessors, Preprocessors
12620 @section @code{geqn}
12621 @cindex @code{eqn}, the program
12622 @cindex @code{geqn}, the program
12630 @c ---------------------------------------------------------------------
12632 @node Invoking geqn, , geqn, geqn
12633 @subsection Invoking @code{geqn}
12634 @cindex invoking @code{geqn}
12635 @cindex @code{geqn}, invoking
12640 @c =====================================================================
12642 @node gtbl, gpic, geqn, Preprocessors
12643 @section @code{gtbl}
12644 @cindex @code{tbl}, the program
12645 @cindex @code{gtbl}, the program
12653 @c ---------------------------------------------------------------------
12655 @node Invoking gtbl, , gtbl, gtbl
12656 @subsection Invoking @code{gtbl}
12657 @cindex invoking @code{gtbl}
12658 @cindex @code{gtbl}, invoking
12663 @c =====================================================================
12665 @node gpic, ggrn, gtbl, Preprocessors
12666 @section @code{gpic}
12667 @cindex @code{pic}, the program
12668 @cindex @code{gpic}, the program
12676 @c ---------------------------------------------------------------------
12678 @node Invoking gpic, , gpic, gpic
12679 @subsection Invoking @code{gpic}
12680 @cindex invoking @code{gpic}
12681 @cindex @code{gpic}, invoking
12686 @c =====================================================================
12688 @node ggrn, grap, gpic, Preprocessors
12689 @section @code{ggrn}
12690 @cindex @code{grn}, the program
12691 @cindex @code{ggrn}, the program
12699 @c ---------------------------------------------------------------------
12701 @node Invoking ggrn, , ggrn, ggrn
12702 @subsection Invoking @code{ggrn}
12703 @cindex invoking @code{ggrn}
12704 @cindex @code{ggrn}, invoking
12709 @c =====================================================================
12711 @node grap, grefer, ggrn, Preprocessors
12712 @section @code{grap}
12713 @cindex @code{grap}, the program
12715 A free implementation of @code{grap}, written by Ted Faber,
12716 is available as an extra package from the following address:
12719 @url{http://www.lunabase.org/~faber/Vault/software/grap/}
12723 @c =====================================================================
12725 @node grefer, gsoelim, grap, Preprocessors
12726 @section @code{grefer}
12727 @cindex @code{refer}, the program
12728 @cindex @code{grefer}, the program
12733 * Invoking grefer::
12736 @c ---------------------------------------------------------------------
12738 @node Invoking grefer, , grefer, grefer
12739 @subsection Invoking @code{grefer}
12740 @cindex invoking @code{grefer}
12741 @cindex @code{grefer}, invoking
12746 @c =====================================================================
12748 @node gsoelim, , grefer, Preprocessors
12749 @section @code{gsoelim}
12750 @cindex @code{soelim}, the program
12751 @cindex @code{gsoelim}, the program
12756 * Invoking gsoelim::
12759 @c ---------------------------------------------------------------------
12761 @node Invoking gsoelim, , gsoelim, gsoelim
12762 @subsection Invoking @code{gsoelim}
12763 @cindex invoking @code{gsoelim}
12764 @cindex @code{gsoelim}, invoking
12770 @c =====================================================================
12771 @c =====================================================================
12773 @node Output Devices, File formats, Preprocessors, Top
12774 @chapter Output Devices
12775 @cindex output devices
12776 @cindex devices for output
12781 * Special Characters::
12792 @c =====================================================================
12794 @node Special Characters, grotty, Output Devices, Output Devices
12795 @section Special Characters
12796 @cindex special characters
12797 @cindex characters, special
12804 @c =====================================================================
12806 @node grotty, grops, Special Characters, Output Devices
12807 @section @code{grotty}
12808 @cindex @code{grotty}, the program
12813 * Invoking grotty::
12816 @c ---------------------------------------------------------------------
12818 @node Invoking grotty, , grotty, grotty
12819 @subsection Invoking @code{grotty}
12820 @cindex invoking @code{grotty}
12821 @cindex @code{grotty}, invoking
12825 @c The following is no longer true; fix and extend it.
12828 @c @cindex Teletype
12829 @c @cindex ISO 6249 SGR
12830 @c @cindex terminal control sequences
12831 @c @cindex control sequences, for terminals
12832 @c For TTY output devices, underlining is done by emitting sequences of
12833 @c @samp{_} and @samp{\b} (the backspace character) before the actual
12834 @c character. Literally, this is printing an underline character, then
12835 @c moving back one character position, and printing the actual character
12836 @c at the same position as the underline character (similar to a
12837 @c typewriter). Usually, a modern terminal can't interpret this (and the
12838 @c original Teletype machines for which this sequence was appropriate are
12839 @c no longer in use). You need a pager program like @code{less} which
12840 @c translates this into ISO 6429 SGR sequences to control terminals.
12843 @c =====================================================================
12845 @node grops, grodvi, grotty, Output Devices
12846 @section @code{grops}
12847 @cindex @code{grops}, the program
12853 * Embedding PostScript::
12856 @c ---------------------------------------------------------------------
12858 @node Invoking grops, Embedding PostScript, grops, grops
12859 @subsection Invoking @code{grops}
12860 @cindex invoking @code{grops}
12861 @cindex @code{grops}, invoking
12865 @c ---------------------------------------------------------------------
12867 @node Embedding PostScript, , Invoking grops, grops
12868 @subsection Embedding @sc{PostScript}
12869 @cindex embedding PostScript
12870 @cindex PostScript, embedding
12875 @c =====================================================================
12877 @node grodvi, grolj4, grops, Output Devices
12878 @section @code{grodvi}
12879 @cindex @code{grodvi}, the program
12884 * Invoking grodvi::
12887 @c ---------------------------------------------------------------------
12889 @node Invoking grodvi, , grodvi, grodvi
12890 @subsection Invoking @code{grodvi}
12891 @cindex invoking @code{grodvi}
12892 @cindex @code{grodvi}, invoking
12897 @c =====================================================================
12899 @node grolj4, grolbp, grodvi, Output Devices
12900 @section @code{grolj4}
12901 @cindex @code{grolj4}, the program
12906 * Invoking grolj4::
12909 @c ---------------------------------------------------------------------
12911 @node Invoking grolj4, , grolj4, grolj4
12912 @subsection Invoking @code{grolj4}
12913 @cindex invoking @code{grolj4}
12914 @cindex @code{grolj4}, invoking
12919 @c =====================================================================
12921 @node grolbp, grohtml, grolj4, Output Devices
12922 @section @code{grolbp}
12923 @cindex @code{grolbp}, the program
12928 * Invoking grolbp::
12931 @c ---------------------------------------------------------------------
12933 @node Invoking grolbp, , grolbp, grolbp
12934 @subsection Invoking @code{grolbp}
12935 @cindex invoking @code{grolbp}
12936 @cindex @code{grolbp}, invoking
12941 @c =====================================================================
12943 @node grohtml, gxditview, grolbp, Output Devices
12944 @section @code{grohtml}
12945 @cindex @code{grohtml}, the program
12950 * Invoking grohtml::
12951 * grohtml specific registers and strings::
12954 @c ---------------------------------------------------------------------
12956 @node Invoking grohtml, grohtml specific registers and strings, grohtml, grohtml
12957 @subsection Invoking @code{grohtml}
12958 @cindex invoking @code{grohtml}
12959 @cindex @code{grohtml}, invoking
12963 @c ---------------------------------------------------------------------
12965 @node grohtml specific registers and strings, , Invoking grohtml, grohtml
12966 @subsection @code{grohtml} specific registers and strings
12967 @cindex registers specific to @code{grohtml}
12968 @cindex strings specific to @code{grohtml}
12969 @cindex @code{grohtml}, registers and strings
12971 @DefmpregList {ps4html, grohtml}
12972 @DefstrListEnd {www-image-template, grohtml}
12973 The registers @code{ps4html} and @code{www-image-template} are defined
12974 by the @code{pre-grohtml} preprocessor. @code{pre-grohtml} reads in
12975 the @code{troff} input, marks up the inline equations and passes the
12979 troff -Tps -rps4html=1 -dwww-image-template=@var{template}
12989 The PostScript device is used to create all the image files, and the
12990 register @code{ps4html} enables the macro sets to ignore floating
12991 keeps, footers, and headings.
12993 The register @code{www-image-template} is set to the user specified
12994 template name or the default name.
12998 @c =====================================================================
13000 @node gxditview, , grohtml, Output Devices
13001 @section @code{gxditview}
13002 @cindex @code{gxditview}, the program
13007 * Invoking gxditview::
13010 @c ---------------------------------------------------------------------
13012 @node Invoking gxditview, , gxditview, gxditview
13013 @subsection Invoking @code{gxditview}
13014 @cindex invoking @code{gxditview}
13015 @cindex @code{gxditview}, invoking
13022 @c =====================================================================
13023 @c =====================================================================
13025 @node File formats, Installation, Output Devices, Top
13026 @chapter File formats
13027 @cindex file formats
13028 @cindex formats, file
13030 All files read and written by @code{gtroff} are text files. The
13031 following two sections describe their format.
13039 @c =====================================================================
13041 @node gtroff Output, Font Files, File formats, File formats
13042 @section @code{gtroff} Output
13043 @cindex @code{gtroff}, output
13044 @cindex output, @code{gtroff}
13046 This section describes the intermediate output format of GNU
13047 @code{troff}. This output is produced by a run of @code{gtroff}
13048 before it is fed into a device postprocessor program.
13050 As @code{groff} is a wrapper program around @code{gtroff} that
13051 automatically calls a postprocessor, this output does not show up
13052 normally. This is why it is called @dfn{intermediate}.
13053 @code{groff} provides the option @option{-Z} to inhibit postprocessing,
13054 such that the produced intermediate output is sent to standard output
13055 just like calling @code{gtroff} manually.
13057 @cindex troff output
13058 @cindex output, troff
13059 @cindex intermediate output
13060 @cindex output, intermediate
13061 Here, the term @dfn{troff output} describes what is output by
13062 @code{gtroff}, while @dfn{intermediate output} refers to the language
13063 that is accepted by the parser that prepares this output for the
13064 postprocessors. This parser is smarter on whitespace and implements
13065 obsolete elements for compatibility, otherwise both formats are the
13066 same.@footnote{The parser and postprocessor for intermediate output
13067 can be found in the file@*
13068 @file{@var{groff-source-dir}/src/libs/libdriver/input.cc}.}
13070 The main purpose of the intermediate output concept is to facilitate
13071 the development of postprocessors by providing a common programming
13072 interface for all devices. It has a language of its own that is
13073 completely different from the @code{gtroff} language. While the
13074 @code{gtroff} language is a high-level programming language for text
13075 processing, the intermediate output language is a kind of low-level
13076 assembler language by specifying all positions on the page for writing
13079 The intermediate output produced by @code{gtroff} is fairly readable,
13080 while output from @acronym{AT&T} @code{troff} is rather hard to
13081 understand because of strange habits that are still supported, but not
13082 used any longer by @code{gtroff}.
13085 * Language Concepts::
13086 * Command Reference::
13087 * Intermediate Output Examples::
13088 * Output Language Compatibility::
13091 @c ---------------------------------------------------------------------
13093 @node Language Concepts, Command Reference, gtroff Output, gtroff Output
13094 @subsection Language Concepts
13096 During the run of @code{gtroff}, the input data is cracked down to the
13097 information on what has to be printed at what position on the intended
13098 device. So the language of the intermediate output format can be quite
13099 small. Its only elements are commands with and without arguments.
13100 In this section, the term @dfn{command} always refers to the intermediate
13101 output language, and never to the @code{gtroff} language used for document
13102 formatting. There are commands for positioning and text writing, for drawing, and
13103 for device controlling.
13111 @node Separation, Argument Units, Language Concepts, Language Concepts
13112 @subsubsection Separation
13114 @acronym{AT&T} @code{troff} output has strange requirements on whitespace.
13115 The @code{gtroff} output parser, however, is smart about whitespace by
13116 making it maximally optional. The whitespace characters, i.e., the
13117 tab, space, and newline characters, always have a syntactical meaning.
13118 They are never printable because spacing within the output is always
13119 done by positioning commands.
13121 Any sequence of space or tab characters is treated as a single
13122 @dfn{syntactical space}. It separates commands and arguments, but is
13123 only required when there would occur a clashing between the command code
13124 and the arguments without the space. Most often, this happens when
13125 variable-length command names, arguments, argument lists, or command
13126 clusters meet. Commands and arguments with a known, fixed length need
13127 not be separated by syntactical space.
13129 A line break is a syntactical element, too. Every command argument can be
13130 followed by whitespace, a comment, or a newline character. Thus a
13131 @dfn{syntactical line break} is defined to consist of optional
13132 syntactical space that is optionally followed by a comment, and a
13135 The normal commands, those for positioning and text, consist of a
13136 single letter taking a fixed number of arguments. For historical reasons,
13137 the parser allows to stack such commands on the same line, but
13138 fortunately, in @code{gtroff}'s intermediate output, every command with
13139 at least one argument is followed by a line break, thus providing
13140 excellent readability.
13142 The other commands -- those for drawing and device controlling --
13143 have a more complicated structure; some recognize long command names,
13144 and some take a variable number of arguments. So all @samp{D} and
13145 @samp{x} commands were designed to request a syntactical line break
13146 after their last argument. Only one command, @w{@samp{x X}},
13147 has an argument that can stretch over several lines; all other
13148 commands must have all of their arguments on the same line as the
13149 command, i.e., the arguments may not be splitted by a line break.
13151 Empty lines (these are lines containing only space and/or a comment), can
13152 occur everywhere. They are just ignored.
13154 @node Argument Units, Document Parts, Separation, Language Concepts
13155 @subsubsection Argument Units
13157 Some commands take integer arguments that are assumed to represent
13158 values in a measurement unit, but the letter for the corresponding
13159 scale indicator is not written with the output command arguments.
13160 Most commands assume the scale indicator @samp{u}, the basic unit of
13161 the device, some use @samp{z}, the scaled point unit of the device,
13162 while others, such as the color commands, expect plain integers.
13164 Note that single characters can have the eighth bit set, as can the
13165 names of fonts and special characters. The names of characters and
13166 fonts can be of arbitrary length. A character that is to be printed
13167 will always be in the current font.
13169 A string argument is always terminated by the next whitespace
13170 character (space, tab, or newline); an embedded @samp{#} character is
13171 regarded as part of the argument, not as the beginning of a comment
13172 command. An integer argument is already terminated by the next
13173 non-digit character, which then is regarded as the first character of
13174 the next argument or command.
13176 @node Document Parts, , Argument Units, Language Concepts
13177 @subsubsection Document Parts
13179 A correct intermediate output document consists of two parts, the
13180 @dfn{prologue} and the @dfn{body}.
13182 The task of the prologue is to set the general device parameters
13183 using three exactly specified commands. @code{gtroff}'s prologue
13184 is guaranteed to consist of the following three lines (in that order):
13188 x res @var{n} @var{h} @var{v}
13193 with the arguments set as outlined in @ref{Device Control Commands}.
13194 Note that the parser for the intermediate output format is able to
13195 swallow additional whitespace and comments as well even in the
13198 The body is the main section for processing the document data.
13199 Syntactically, it is a sequence of any commands different from the
13200 ones used in the prologue. Processing is terminated as soon as the
13201 first @w{@samp{x stop}} command is encountered; the last line of any
13202 @code{gtroff} intermediate output always contains such a command.
13204 Semantically, the body is page oriented. A new page is started by a
13205 @samp{p} command. Positioning, writing, and drawing commands are
13206 always done within the current page, so they cannot occur before the
13207 first @samp{p} command. Absolute positioning (by the @samp{H} and
13208 @samp{V} commands) is done relative to the current page; all other
13209 positioning is done relative to the current location within this page.
13211 @c ---------------------------------------------------------------------
13213 @node Command Reference, Intermediate Output Examples, Language Concepts, gtroff Output
13214 @subsection Command Reference
13216 This section describes all intermediate output commands, both from
13217 @acronym{AT&T} @code{troff} as well as the @code{gtroff} extensions.
13220 * Comment Command::
13221 * Simple Commands::
13222 * Graphics Commands::
13223 * Device Control Commands::
13224 * Obsolete Command::
13227 @node Comment Command, Simple Commands, Command Reference, Command Reference
13228 @subsubsection Comment Command
13231 @item #@var{anything}@angles{end of line}
13232 A comment. Ignore any characters from the @samp{#} character up to
13233 the next newline character.
13235 This command is the only possibility for commenting in the intermediate
13236 output. Each comment can be preceded by arbitrary syntactical space;
13237 every command can be terminated by a comment.
13240 @node Simple Commands, Graphics Commands, Comment Command, Command Reference
13241 @subsubsection Simple Commands
13243 The commands in this subsection have a command code consisting of a
13244 single character, taking a fixed number of arguments. Most of them
13245 are commands for positioning and text writing. These commands are
13246 smart about whitespace. Optionally, syntactical space can be inserted
13247 before, after, and between the command letter and its arguments.
13248 All of these commands are stackable, i.e., they can be preceded by
13249 other simple commands or followed by arbitrary other commands on the
13250 same line. A separating syntactical space is only necessary when two
13251 integer arguments would clash or if the preceding argument ends with a
13256 .if (\n[@USE_ENV_STACK] == 1) \{\
13258 Open a new environment by copying the actual device configuration data
13259 to the environment stack.
13261 The current environment is setup by the device specification and
13262 manipulated by the setting commands.
13266 Close the actual environment (opened by a preceding
13268 and restore the previous environment from the environment
13269 stack as the actual device configuration data.
13271 \} \" endif @USE_ENV_STACK
13274 @item C @var{xxx}@angles{whitespace}
13275 Print a special character named @var{xxx}. The trailing
13276 syntactical space or line break is necessary to allow glyph names
13277 of arbitrary length. The glyph is printed at the current print
13278 position; the glyph's size is read from the font file. The print
13279 position is not changed.
13282 Print glyph@w{ }@var{g} at the current print position;@footnote{@samp{c}
13283 is actually a misnomer since it outputs a glyph.} the glyph's size is
13284 read from the font file. The print position is not changed.
13287 Set font to font number@w{ }@var{n} (a non-negative integer).
13290 Move right to the absolute vertical position@w{ }@var{n} (a
13291 non-negative integer in basic units @samp{u} relative to left edge
13295 Move @var{n} (a non-negative integer) basic units @samp{u} horizontally
13296 to the right. The original @acronym{UNIX} troff manual allows negative
13297 values for @var{n} also, but @code{gtroff} doesn't use this.
13299 @item m @var{color-scheme} @r{[}@var{component} @dots{}@r{]}
13300 Set the color for text (glyphs), line drawing, and the outline of
13301 graphic objects using different color schemes; the analoguous command
13302 for the filling color of graphic objects is @samp{DF}. The color
13303 components are specified as integer arguments between 0 and 65536.
13304 The number of color components and their meaning vary for the
13305 different color schemes. These commands are generated by
13306 @code{gtroff}'s escape sequence @code{\m}. No position changing.
13307 These commands are a @code{gtroff} extension.
13310 @item mc @var{cyan} @var{magenta} @var{yellow}
13311 Set color using the CMY color scheme, having the 3@w{ }color components
13312 @var{cyan}, @var{magenta}, and @var{yellow}.
13315 Set color to the default color value (black in most cases).
13316 No component arguments.
13318 @item mg @var{gray}
13319 Set color to the shade of gray given by the argument, an integer
13320 between 0 (black) and 65536 (white).
13322 @item mk @var{cyan} @var{magenta} @var{yellow} @var{black}
13323 Set color using the CMYK color scheme, having the 4@w{ }color components
13324 @var{cyan}, @var{magenta}, @var{yellow}, and @var{black}.
13326 @item mr @var{red} @var{green} @var{blue}
13327 Set color using the RGB color scheme, having the 3@w{ }color components
13328 @var{red}, @var{green}, and @var{blue}.
13333 Print glyph with index@w{ }@var{n} (a non-negative integer) of the
13334 current font. This command is a @code{gtroff} extension.
13336 @item n @var{b} @var{a}
13337 Inform the device about a line break, but no positioning is done by
13338 this command. In @acronym{AT&T} @code{troff}, the integer arguments
13339 @var{b} and@w{ }@var{a} informed about the space before and after the
13340 current line to make the intermediate output more human readable
13341 without performing any action. In @code{groff}, they are just ignored, but
13342 they must be provided for compatibility reasons.
13345 Begin a new page in the outprint. The page number is set
13346 to@w{ }@var{n}. This page is completely independent of pages formerly
13347 processed even if those have the same page number. The vertical
13348 position on the outprint is automatically set to@w{ }0. All
13349 positioning, writing, and drawing is always done relative to a page,
13350 so a @samp{p} command must be issued before any of these commands.
13353 Set point size to @var{n}@w{ }scaled points (this is unit @samp{z}).
13354 @acronym{AT&T} @code{troff} used the unit points (@samp{p}) instead.
13355 @xref{Output Language Compatibility}.
13357 @item t @var{xxx}@angles{whitespace}
13358 @itemx t @var{xxx} @var{dummy-arg}@angles{whitespace}
13359 Print a word, i.e., a sequence of characters @var{xxx} representing
13360 output glyphs which names are single characters, terminated by
13361 a space character or a line break; an optional second integer argument
13362 is ignored (this allows the formatter to generate an even number of
13363 arguments). The first glyph should be printed at the current
13364 position, the current horizontal position should then be increased by
13365 the width of the first glyph, and so on for each glyph.
13366 The widths of the glyphs are read from the font file, scaled for the
13367 current point size, and rounded to a multiple of the horizontal
13368 resolution. Special characters cannot be printed using this command
13369 (use the @samp{C} command for special characters). This command is a
13370 @code{gtroff} extension; it is only used for devices whose @file{DESC}
13371 file contains the @code{tcommand} keyword (@pxref{DESC File Format}).
13373 @item u @var{n} @var{xxx}@angles{whitespace}
13374 Print word with track kerning. This is the same as the @samp{t}
13375 command except that after printing each glyph, the current
13376 horizontal position is increased by the sum of the width of that
13377 glyph and@w{ }@var{n} (an integer in basic units @samp{u}).
13378 This command is a @code{gtroff} extension; it is only used for devices
13379 whose @file{DESC} file contains the @code{tcommand} keyword
13380 (@pxref{DESC File Format}).
13383 Move down to the absolute vertical position@w{ }@var{n} (a
13384 non-negative integer in basic units @samp{u}) relative to upper edge
13388 Move @var{n}@w{ }basic units @samp{u} down (@var{n} is a non-negative
13389 integer). The original @acronym{UNIX} troff manual allows negative
13390 values for @var{n} also, but @code{gtroff} doesn't use this.
13393 Informs about a paddable white space to increase readability.
13394 The spacing itself must be performed explicitly by a move command.
13398 @node Graphics Commands, Device Control Commands, Simple Commands, Command Reference
13399 @subsubsection Graphics Commands
13401 Each graphics or drawing command in the intermediate output starts
13402 with the letter @samp{D}, followed by one or two characters that
13403 specify a subcommand; this is followed by a fixed or variable number
13404 of integer arguments that are separated by a single space character.
13405 A @samp{D} command may not be followed by another command on the same line
13406 (apart from a comment), so each @samp{D} command is terminated by a
13407 syntactical line break.
13409 @code{gtroff} output follows the classical spacing rules (no space
13410 between command and subcommand, all arguments are preceded by a
13411 single space character), but the parser allows optional space between
13412 the command letters and makes the space before the first argument
13413 optional. As usual, each space can be any sequence of tab and space
13416 Some graphics commands can take a variable number of arguments.
13417 In this case, they are integers representing a size measured in basic
13418 units @samp{u}. The arguments called @var{h1}, @var{h2}, @dots{},
13419 @var{hn} stand for horizontal distances where positive means right,
13420 negative left. The arguments called @var{v1}, @var{v2}, @dots{},
13421 @var{vn} stand for vertical distances where positive means down,
13422 negative up. All these distances are offsets relative to the current
13425 Unless indicated otherwise, each graphics command directly corresponds
13426 to a similar @code{gtroff} @code{\D} escape sequence. @xref{Drawing
13429 Unknown @samp{D} commands are assumed to be device-specific.
13430 Its arguments are parsed as strings; the whole information is then
13431 sent to the postprocessor.
13433 In the following command reference, the syntax element
13434 @angles{line break} means a syntactical line break as defined above.
13437 @item D~ @var{h1} @var{v1} @var{h2} @var{v2} @dots{} @var{hn} @var{vn}@angles{line break}
13438 Draw B-spline from current position to offset (@var{h1},@var{v1}),
13439 then to offset (@var{h2},@var{v2}), if given, etc.@: up to
13440 (@var{hn},@var{vn}). This command takes a variable number of argument
13441 pairs; the current position is moved to the terminal point of the drawn
13444 @item Da @var{h1} @var{v1} @var{h2} @var{v2}@angles{line break}
13445 Draw arc from current position to
13446 (@var{h1},@var{v1})@math{+}(@var{h2},@var{v2}) with center at
13447 (@var{h1},@var{v1}); then move the current position to the final point
13450 @item DC @var{d}@angles{line break}
13451 @itemx DC @var{d} @var{dummy-arg}@angles{line break}
13452 Draw a solid circle using the current fill color with
13453 diameter@w{ }@var{d} (integer in basic units @samp{u}) with leftmost
13454 point at the current position; then move the current position to the
13455 rightmost point of the circle. An optional second integer argument is
13456 ignored (this allows the formatter to generate an even number of
13457 arguments). This command is a @code{gtroff} extension.
13459 @item Dc @var{d}@angles{line break}
13460 Draw circle line with diameter@w{ }@var{d} (integer in basic units
13461 @samp{u}) with leftmost point at the current position; then move the
13462 current position to the rightmost point of the circle.
13464 @item DE @var{h} @var{v}@angles{line break}
13465 Draw a solid ellipse in the current fill color with a horizontal
13466 diameter of@w{ }@var{h} and a vertical diameter of@w{ }@var{v} (both
13467 integers in basic units @samp{u}) with the leftmost point at the
13468 current position; then move to the rightmost point of the ellipse.
13469 This command is a @code{gtroff} extension.
13471 @item De @var{h} @var{v}@angles{line break}
13472 Draw an outlined ellipse with a horizontal diameter of@w{ }@var{h}
13473 and a vertical diameter of@w{ }@var{v} (both integers in basic units
13474 @samp{u}) with the leftmost point at current position; then move to
13475 the rightmost point of the ellipse.
13477 @item DF @var{color-scheme} @r{[}@var{component} @dots{}@r{]}@angles{line break}
13478 Set fill color for solid drawing objects using different color
13479 schemes; the analoguous command for setting the color of text, line
13480 graphics, and the outline of graphic objects is @samp{m}.
13481 The color components are specified as integer arguments between 0 and
13482 65536. The number of color components and their meaning vary for the
13483 different color schemes. These commands are generated by @code{gtroff}'s
13484 escape sequences @w{@code{\D'F @dots{}'}} and @code{\M} (with no other
13485 corresponding graphics commands). No position changing. This command
13486 is a @code{gtroff} extension.
13489 @item DFc @var{cyan} @var{magenta} @var{yellow}@angles{line break}
13490 Set fill color for solid drawing objects using the CMY color scheme,
13491 having the 3@w{ }color components @var{cyan}, @var{magenta}, and
13494 @item DFd@angles{line break}
13495 Set fill color for solid drawing objects to the default fill color value
13496 (black in most cases). No component arguments.
13498 @item DFg @var{gray}@angles{line break}
13499 Set fill color for solid drawing objects to the shade of gray given by
13500 the argument, an integer between 0 (black) and 65536 (white).
13502 @item DFk @var{cyan} @var{magenta} @var{yellow} @var{black}@angles{line break}
13503 Set fill color for solid drawing objects using the CMYK color scheme,
13504 having the 4@w{ }color components @var{cyan}, @var{magenta}, @var{yellow},
13507 @item DFr @var{red} @var{green} @var{blue}@angles{line break}
13508 Set fill color for solid drawing objects using the RGB color scheme,
13509 having the 3@w{ }color components @var{red}, @var{green}, and @var{blue}.
13513 @item Df @var{n}@angles{line break}
13514 The argument@w{ }@var{n} must be an integer in the range @math{-32767}
13518 @item @math{0 @LE @var{n} @LE 1000}
13519 Set the color for filling solid drawing objects to a shade of gray,
13520 where 0 corresponds to solid white, 1000 (the default) to solid black,
13521 and values in between to intermediate shades of gray; this is
13522 obsoleted by command @samp{DFg}.
13524 @item @math{@var{n} @LT 0} or @math{@var{n} @LT 1000}
13525 Set the filling color to the color that is currently being used for
13526 the text and the outline, see command @samp{m}. For example, the
13535 sets all colors to blue.
13540 No position changing. This command is a @code{gtroff} extension.
13542 @item Dl @var{h} @var{v}@angles{line break}
13543 Draw line from current position to offset (@var{h},@var{v}) (integers
13544 in basic units @samp{u}); then set current position to the end of the
13547 @item Dp @var{h1} @var{v1} @var{h2} @var{v2} @dots{} @var{hn} @var{vn}@angles{line break}
13548 Draw a polygon line from current position to offset (@var{h1},@var{v1}),
13549 from there to offset (@var{h2},@var{v2}), etc.@: up to offset
13550 (@var{hn},@var{vn}), and from there back to the starting position.
13551 For historical reasons, the position is changed by adding the sum of
13552 all arguments with odd index to the actual horizontal position and the
13553 even ones to the vertical position. Although this doesn't make sense
13554 it is kept for compatibility.
13556 As the polygon is closed, the end of drawing is the starting point, so
13557 the position doesn't change.
13559 This command is a @code{gtroff} extension.
13561 @item Dp @var{h1} @var{v1} @var{h2} @var{v2} @dots{} @var{hn} @var{vn}@angles{line break}
13562 Draw a solid polygon in the current fill color rather than an outlined
13563 polygon, using the same arguments and positioning as the corresponding
13566 No position changing.
13568 This command is a @code{gtroff} extension.
13570 @item Dt @var{n}@angles{line break}
13571 Set the current line thickness to@w{ }@var{n} (an integer in basic
13572 units @samp{u}) if @math{@var{n}>0}; if @math{@var{n}=0} select the
13573 smallest available line thickness; if @math{@var{n}<0} set the line
13574 thickness proportional to the point size (this is the default before
13575 the first @samp{Dt} command was specified). For historical reasons,
13576 the horizontal position is changed by adding the argument to the actual
13577 horizontal position, while the vertical position is not changed.
13578 Although this doesn't make sense it is kept for compatibility.
13580 No position changing.
13582 This command is a @code{gtroff} extension.
13586 @node Device Control Commands, Obsolete Command, Graphics Commands, Command Reference
13587 @subsubsection Device Control Commands
13589 Each device control command starts with the letter @samp{x},
13590 followed by a space character (optional or arbitrary space or tab in
13591 @code{gtroff}) and a subcommand letter or word; each argument (if any)
13592 must be preceded by a syntactical space. All @samp{x} commands are
13593 terminated by a syntactical line break; no device control command can
13594 be followed by another command on the same line (except a comment).
13596 The subcommand is basically a single letter, but to increase
13597 readability, it can be written as a word, i.e., an arbitrary sequence
13598 of characters terminated by the next tab, space, or newline character.
13599 All characters of the subcommand word but the first are simply ignored.
13600 For example, @code{gtroff} outputs the initialization command
13601 @w{@samp{x i}} as @w{@samp{x init}} and the resolution command
13602 @w{@samp{x r}} as @w{@samp{x res}}.
13604 In the following, the syntax element @angles{line break} means a
13605 syntactical line break (@pxref{Separation}).
13608 @item xF @var{name}@angles{line break}
13609 The @samp{F} stands for @var{Filename}.
13611 Use @var{name} as the intended name for the current file in error
13612 reports. This is useful for remembering the original file name when
13613 @code{gtroff} uses an internal piping mechanism. The input file is
13614 not changed by this command. This command is a @code{gtroff} extension.
13616 @item xf @var{n} @var{s}@angles{line break}
13617 The @samp{f} stands for @var{font}.
13619 Mount font position@w{ }@var{n} (a non-negative integer) with font
13620 named@w{ }@var{s} (a text word). @xref{Font Positions}.
13622 @item xH @var{n}@angles{line break}
13623 The @samp{H} stands for @var{Height}.
13625 Set glyph height to@w{ }@var{n} (a positive integer in scaled
13626 points @samp{z}). @acronym{AT&T} @code{troff} uses the unit points
13627 (@samp{p}) instead. @xref{Output Language Compatibility}.
13629 @item xi@angles{line break}
13630 The @samp{i} stands for @var{init}.
13632 Initialize device. This is the third command of the prologue.
13634 @item xp@angles{line break}
13635 The @samp{p} stands for @var{pause}.
13637 Parsed but ignored. The original @acronym{UNIX} troff manual writes
13640 pause device, can be restarted
13643 @item xr @var{n} @var{h} @var{v}@angles{line break}
13644 The @samp{r} stands for @var{resolution}.
13646 Resolution is@w{ }@var{n}, while @var{h} is the minimal horizontal
13647 motion, and @var{v} the minimal vertical motion possible with this
13648 device; all arguments are positive integers in basic units @samp{u}
13649 per inch. This is the second command of the prologue.
13651 @item xS @var{n}@angles{line break}
13652 The @samp{S} stands for @var{Slant}.
13654 Set slant to@w{ }@var{n} (an integer in basic units @samp{u}).
13656 @item xs@angles{line break}
13657 The @samp{s} stands for @var{stop}.
13659 Terminates the processing of the current file; issued as the last
13660 command of any intermediate troff output.
13662 @item xt@angles{line break}
13663 The @samp{t} stands for @var{trailer}.
13665 Generate trailer information, if any. In @var{gtroff}, this is
13666 actually just ignored.
13668 @item xT @var{xxx}@angles{line break}
13669 The @samp{T} stands for @var{Typesetter}.
13671 Set name of device to word @var{xxx}, a sequence of characters ended
13672 by the next white space character. The possible device names coincide
13673 with those from the @code{groff} @option{-T} option. This is the first
13674 command of the prologue.
13676 @item xu @var{n}@angles{line break}
13677 The @samp{u} stands for @var{underline}.
13679 Configure underlining of spaces. If @var{n} is@w{ }1, start
13680 underlining of spaces; if @var{n} is@w{ }0, stop underlining of spaces.
13681 This is needed for the @code{cu} request in nroff mode and is ignored
13682 otherwise. This command is a @code{gtroff} extension.
13684 @item xX @var{anything}@angles{line break}
13685 The @samp{x} stands for @var{X-escape}.
13687 Send string @var{anything} uninterpreted to the device. If the line
13688 following this command starts with a @samp{+} character this line is
13689 interpreted as a continuation line in the following sense. The
13690 @samp{+} is ignored, but a newline character is sent instead to the
13691 device, the rest of the line is sent uninterpreted. The same applies
13692 to all following lines until the first character of a line is not a
13693 @samp{+} character. This command is generated by the @code{gtroff}
13694 escape sequence @code{\X}. The line-continuing feature is a
13695 @code{gtroff} extension.
13699 @node Obsolete Command, , Device Control Commands, Command Reference
13700 @subsubsection Obsolete Command
13701 In @acronym{AT&T} @code{troff} output, the writing of a single
13702 glyph is mostly done by a very strange command that combines a
13703 horizontal move and a single character giving the glyph name. It
13704 doesn't have a command code, but is represented by a 3-character
13705 argument consisting of exactly 2@w{ }digits and a character.
13708 @item @var{dd}@var{g}
13709 Move right @var{dd} (exactly two decimal digits) basic units @samp{u},
13710 then print glyph@w{ }@var{g} (represented as a single character).
13712 In @code{gtroff}, arbitrary syntactical space around and within this
13713 command is allowed to be added. Only when a preceding command on the
13714 same line ends with an argument of variable length a separating space
13715 is obligatory. In @acronym{AT&T} @code{troff}, large clusters of these
13716 and other commands are used, mostly without spaces; this made such output
13721 For modern high-resolution devices, this command does not make sense
13722 because the width of the glyphs can become much larger than two
13723 decimal digits. In @code{gtroff}, this is only used for the devices
13724 @code{X75}, @code{X75-12}, @code{X100}, and @code{X100-12}. For other
13725 devices, the commands @samp{t} and @samp{u} provide a better
13728 @c ---------------------------------------------------------------------
13730 @node Intermediate Output Examples, Output Language Compatibility, Command Reference, gtroff Output
13731 @subsection Intermediate Output Examples
13733 This section presents the intermediate output generated from the same
13734 input for three different devices. The input is the sentence
13735 @samp{hell world} fed into @code{gtroff} on the command line.
13738 @item High-resolution device @code{ps}
13740 This is the standard output of @code{gtroff} if no @option{-T} option
13745 shell> echo "hell world" | groff -Z -T ps
13771 This output can be fed into @code{grops} to get its representation as
13774 @item Low-resolution device @code{latin1}
13776 This is similar to the high-resolution device except that the
13777 positioning is done at a minor scale. Some comments (lines starting
13778 with @samp{#}) were added for clarification; they were not generated
13783 shell> echo "hell world" | groff -Z -T latin1
13796 # initial positioning on the page
13799 # write text `hell'
13801 # inform about space, and issue a horizontal jump
13803 # write text `world'
13805 # announce line break, but do nothing because ...
13808 # ... the end of the document has been reached
13816 This output can be fed into @code{grotty} to get a formatted text
13819 @item @acronym{AT&T} @code{troff} output
13820 Since a computer monitor has a very low resolution compared to modern
13821 printers the intermediate output for the X@w{ }Window devices can use
13822 the jump-and-write command with its 2-digit displacements.
13826 shell> echo "hell world" | groff -Z -T X100
13838 # write text with jump-and-write commands
13839 ch07e07l03lw06w11o07r05l03dh7
13849 This output can be fed into @code{xditview} or @code{gxditview}
13850 for displaying in@w{ }X.
13852 Due to the obsolete jump-and-write command, the text clusters in the
13853 @acronym{AT&T} @code{troff} output are almost unreadable.
13857 @c ---------------------------------------------------------------------
13859 @node Output Language Compatibility, , Intermediate Output Examples, gtroff Output
13860 @subsection Output Language Compatibility
13862 The intermediate output language of @acronym{AT&T} @code{troff}
13863 was first documented in the @acronym{UNIX} troff manual, with later
13864 additions documented in @cite{A Typesetter-indenpendent TROFF},
13865 written by Brian Kernighan.
13867 The @code{gtroff} intermediate output format is compatible with this
13868 specification except for the following features.
13872 The classical quasi device independence is not yet implemented.
13875 The old hardware was very different from what we use today. So the
13876 @code{groff} devices are also fundamentally different from the ones in
13877 @acronym{AT&T} @code{troff}. For example, the @acronym{AT&T}
13878 PostScript device is called @code{post} and has a resolution of only
13879 720 units per inch, suitable for printers 20 years ago, while
13880 @code{groff}'s @code{ps} device has a resolution of
13881 72000 units per inch. Maybe, by implementing some rescaling
13882 mechanism similar to the classical quasi device independence,
13883 @code{groff} could emulate @acronym{AT&T}'s @code{post} device.
13886 The B-spline command @samp{D~} is correctly handled by the
13887 intermediate output parser, but the drawing routines aren't
13888 implemented in some of the postprocessor programs.
13891 The argument of the commands @samp{s} and @w{@samp{x H}} has the
13892 implicit unit scaled point @samp{z} in @code{gtroff}, while
13893 @acronym{AT&T} @code{troff} has point (@samp{p}). This isn't an
13894 incompatibility but a compatible extension, for both units coincide
13895 for all devices without a @code{sizescale} parameter in the @file{DESC}
13896 file, including all postprocessors from @acronym{AT&T} and
13897 @code{groff}'s text devices. The few @code{groff} devices with
13898 a @code{sizescale} parameter either do not exist for @acronym{AT&T}
13899 @code{troff}, have a different name, or seem to have a different
13900 resolution. So conflicts are very unlikely.
13903 The position changing after the commands @samp{Dp}, @samp{DP}, and
13904 @samp{Dt} is illogical, but as old versions of @code{gtroff} used this
13905 feature it is kept for compatibility reasons.
13908 Temporarily, there existed some confusion on the positioning after the
13909 @samp{D} commands that are groff extensions. This has been clarified
13910 by establishing the classical rule for all @code{groff} drawing commands:
13914 The position after a graphic object has been drawn is at its end;
13915 for circles and ellipses, the `end' is at the right side.
13918 From this, the positionings specified for the drawing commands above
13919 follow quite naturally.
13926 @c =====================================================================
13928 @node Font Files, , gtroff Output, File formats
13929 @section Font Files
13931 @cindex files, font
13933 The @code{gtroff} font format is roughly a superset of the
13934 @code{ditroff} font format (as used in later versions of @acronym{AT&T}
13935 @code{troff} and its descendants). Unlike the @code{ditroff} font
13936 format, there is no associated binary format; all files are text
13937 files.@footnote{Plan@w{ }9 @code{troff} has also abandoned the binary
13938 format.} The font files for device @var{name} are stored in a directory
13939 @file{dev@var{name}}. There are two types of file: a device description
13940 file called @file{DESC} and for each font@w{ }@var{f} a font file
13941 called@w{ }@file{@var{f}}.
13944 * DESC File Format::
13945 * Font File Format::
13948 @c ---------------------------------------------------------------------
13950 @node DESC File Format, Font File Format, Font Files, Font Files
13951 @subsection @file{DESC} File Format
13952 @cindex @file{DESC} file, format
13953 @cindex font description file, format
13954 @cindex format of font description file
13955 @pindex DESC@r{ file format}
13957 The @file{DESC} file can contain the following types of line. Except
13958 for the @code{charset} keyword which must comes last (if at all), the
13959 order of the lines is not important.
13964 There are @var{n}@w{ }machine units per inch.
13968 The horizontal resolution is @var{n}@w{ }machine units.
13972 The vertical resolution is @var{n}@w{ }machine units.
13974 @item sizescale @var{n}
13976 The scale factor for point sizes. By default this has a value of@w{ }1.
13977 One scaled point is equal to one point/@var{n}. The arguments to the
13978 @code{unitwidth} and @code{sizes} commands are given in scaled points.
13979 @xref{Fractional Type Sizes}, for more information.
13981 @item unitwidth @var{n}
13983 Quantities in the font files are given in machine units for fonts whose
13984 point size is @var{n}@w{ }scaled points.
13986 @item prepro @var{program}
13988 Call @var{program} as a preprocessor. Currently, this keyword is used
13989 by @code{groff} with option @option{-Thtml} only.
13991 @item postpro @var{program}
13993 Call @var{program} as a postprocessor. For example, the line
14000 in the file @file{devdvi/DESC} makes @code{groff} call @code{grodvi}
14001 if option @option{-Tdvi} is given (and @option{-Z} isn't used).
14005 This means that the postprocessor can handle the @samp{t} and @samp{u}
14006 intermediate output commands.
14008 @item sizes @var{s1} @var{s2} @dots{} @var{sn} 0
14010 This means that the device has fonts at @var{s1}, @var{s2}, @dots{}
14011 @var{sn} scaled points. The list of sizes must be terminated by@w{ }0
14012 (this is digit zero). Each @var{si} can also be a range of sizes
14013 @var{m}-@var{n}. The list can extend over more than one line.
14015 @item styles @var{S1} @var{S2} @dots{} @var{Sm}
14017 The first @var{m}@w{ }font positions are associated with styles
14018 @var{S1} @dots{} @var{Sm}.
14020 @item fonts @var{n} @var{F1} @var{F2} @var{F3} @dots{} @var{Fn}
14022 Fonts @var{F1} @dots{} @var{Fn} are mounted in the font positions
14023 @var{m}+1, @dots{}, @var{m}+@var{n} where @var{m} is the number of
14024 styles. This command may extend over more than one line. A font name
14025 of@w{ }0 means no font is mounted on the corresponding font position.
14027 @item family @var{fam}
14029 The default font family is @var{fam}.
14031 @item use_charnames_in_special
14032 @kindex use_charnames_in_special
14033 This command indicates that @code{gtroff} should encode special
14034 characters inside special commands. Currently, this is only used
14035 by the @acronym{HTML} output device. @xref{Postprocessor Access}.
14037 @item papersize @var{string} @dots{}
14039 Select a paper size. Valid values for @var{string} are the ISO paper
14040 types @code{A0}-@code{A7}, @code{B0}-@code{B7}, @code{C0}-@code{C7},
14041 @code{D0}-@code{D7}, @code{DL}, and the US paper types @code{letter},
14042 @code{legal}, @code{tabloid}, @code{ledger}, @code{statement},
14043 @code{executive}, @code{com10}, and @code{monarch}. Case is not significant
14044 for @var{string} if it holds predefined paper types. Alternatively,
14045 @var{string} can be a file name (e.g.@: @file{/etc/papersize}); if the file
14046 can be opened, @code{groff} reads the first line and tests for the above
14047 paper sizes. Finally, @var{string} can be a custom paper size in the format
14048 @code{@var{length},@var{width}} (no spaces before and after the comma).
14049 Both @var{length} and @var{width} must have a unit appended; valid values
14050 are @samp{i} for inches, @samp{C} for centimeters, @samp{p} for points, and
14051 @samp{P} for picas. Example: @code{12c,235p}. An argument which starts
14052 with a digit is always treated as a custom paper format. @code{papersize}
14053 sets both the vertical and horizontal dimension of the output medium.
14055 More than one argument can be specified; @code{groff} scans from left to
14056 right and uses the first valid paper specification.
14058 @item pass_filenames
14059 @kindex pass_filenames
14060 Tell @code{gtroff} to emit the name of the source file currently
14061 being processed. This is achieved by the intermediate output command
14062 @samp{F}. Currently, this is only used by the @acronym{HTML} output
14065 @item print @var{program}
14067 Use @var{program} as a spooler program for printing. If omitted,
14068 the @option{-l} and @option{-L} options of @code{groff} are ignored.
14072 This line and everything following in the file are ignored. It is
14073 allowed for the sake of backwards compatibility.
14076 The @code{res}, @code{unitwidth}, @code{fonts}, and @code{sizes} lines
14077 are mandatory. Other commands are ignored by @code{gtroff} but may be
14078 used by postprocessors to store arbitrary information about the device
14079 in the @file{DESC} file.
14083 @kindex biggestfont
14084 Here a list of obsolete keywords which are recognized by @code{groff}
14085 but completely ignored: @code{spare1}, @code{spare2},
14086 @code{biggestfont}.
14089 @c ---------------------------------------------------------------------
14091 @node Font File Format, , DESC File Format, Font Files
14092 @subsection Font File Format
14093 @cindex font file, format
14094 @cindex font description file, format
14095 @cindex format of font files
14096 @cindex format of font description files
14098 A @dfn{font file}, also (and probably better) called a @dfn{font
14099 description file}, has two sections. The first section is a sequence
14100 of lines each containing a sequence of blank delimited words; the first
14101 word in the line is a key, and subsequent words give a value for that
14107 The name of the font is@w{ }@var{f}.
14109 @item spacewidth @var{n}
14111 The normal width of a space is@w{ }@var{n}.
14113 @item slant @var{n}
14115 The glyphs of the font have a slant of @var{n}@w{ }degrees.
14116 (Positive means forward.)
14118 @item ligatures @var{lig1} @var{lig2} @dots{} @var{lign} [0]
14120 Glyphs @var{lig1}, @var{lig2}, @dots{}, @var{lign} are ligatures;
14121 possible ligatures are @samp{ff}, @samp{fi}, @samp{fl}, @samp{ffi} and
14122 @samp{ffl}. For backwards compatibility, the list of ligatures may be
14123 terminated with a@w{ }0. The list of ligatures may not extend over more
14127 @cindex special fonts
14129 The font is @dfn{special}; this means that when a glyph is requested
14130 that is not present in the current font, it is searched for in any
14131 special fonts that are mounted.
14134 Other commands are ignored by @code{gtroff} but may be used by
14135 postprocessors to store arbitrary information about the font in the font
14138 @cindex comments in font files
14139 @cindex font files, comments
14141 The first section can contain comments which start with the @samp{#}
14142 character and extend to the end of a line.
14144 The second section contains one or two subsections. It must contain a
14145 @code{charset} subsection and it may also contain a @code{kernpairs}
14146 subsection. These subsections can appear in any order. Each
14147 subsection starts with a word on a line by itself.
14150 The word @code{charset} starts the character set
14151 subsection.@footnote{This keyword is misnamed since it starts a list
14152 of ordered glyphs, not characters.} The @code{charset} line is
14153 followed by a sequence of lines. Each line gives information for one
14154 glyph. A line comprises a number of fields separated by blanks or
14155 tabs. The format is
14158 @var{name} @var{metrics} @var{type} @var{code}
14159 [@var{entity-name}] [@code{--} @var{comment}]
14162 @cindex 8-bit input
14163 @cindex input, 8-bit
14164 @cindex accessing unnamed glyphs with @code{\N}
14165 @cindex unnamed glyphs, accessing with @code{\N}
14166 @cindex characters, unnamed, accessing with @code{\N}
14167 @cindex glyphs, unnamed, accessing with @code{\N}
14170 @var{name} identifies the glyph name@footnote{The distinction between
14171 input, characters, and output, glyphs, is not clearly separated in the
14172 terminology of @code{groff}; for example, the @code{char} request
14173 should be called @code{glyph} since it defines an output entity.}:
14174 If @var{name} is a single character@w{ }@var{c} then it corresponds
14175 to the @code{gtroff} input character@w{ }@var{c}; if it is of the form
14176 @samp{\@var{c}} where @var{c} is a single character, then it
14177 corresponds to the special character @code{\[@var{c}]}; otherwise it
14178 corresponds to the special character @samp{\[@var{name}]}. If it
14179 is exactly two characters @var{xx} it can be entered as
14180 @samp{\(@var{xx}}. Note that single-letter special characters can't
14181 be accessed as @samp{\@var{c}}; the only exception is @samp{\-} which
14182 is identical to @code{\[-]}.
14184 @code{gtroff} supports 8-bit input characters; however some utilities
14185 have difficulties with eight-bit characters. For this reason, there is
14186 a convention that the entity name @samp{char@var{n}} is equivalent to
14187 the single input character whose code is@w{ }@var{n}. For example,
14188 @samp{char163} would be equivalent to the character with code@w{ }163
14189 which is the pounds sterling sign in the @w{ISO Latin-1} character set.
14190 You shouldn't use @samp{char@var{n}} entities in font description files
14191 since they are related to input, not output. Otherwise, you get
14192 hard-coded connections between input and output encoding which
14193 prevents use of different (input) character sets.
14195 The name @samp{---} is special and indicates that the glyph is
14196 unnamed; such glyphs can only be used by means of the @code{\N}
14197 escape sequence in @code{gtroff}.
14199 The @var{type} field gives the glyph type:
14203 the glyph has a descender, for example, @samp{p};
14206 the glyph has an ascender, for example, @samp{b};
14209 the glyph has both an ascender and a descender, for example, @samp{(}.
14212 The @var{code} field gives the code which the postprocessor uses to
14213 print the glyph. The glyph can also be input to @code{gtroff}
14214 using this code by means of the @code{\N} escape sequence. @var{code}
14215 can be any integer. If it starts with @samp{0} it is interpreted as
14216 octal; if it starts with @samp{0x} or @samp{0X} it is interpreted as
14217 hexadecimal. Note, however, that the @code{\N} escape sequence only
14218 accepts a decimal integer.
14220 The @var{entity-name} field gives an @acronym{ASCII} string
14221 identifying the glyph which the postprocessor uses to print the
14222 @code{gtroff} glyph @var{name}. This field is optional and has been
14223 introduced so that the @acronym{HTML} device driver can encode its
14224 character set. For example, the glyph @samp{\[Po]} is
14225 represented as @samp{£} in @acronym{HTML} 4.0.
14227 Anything on the line after the @var{entity-name} field resp.@: after
14228 @samp{--} will be ignored.
14230 The @var{metrics} field has the form:
14234 @var{width}[@code{,}@var{height}[@code{,}@var{depth}[@code{,}@var{italic-correction}
14235 [@code{,}@var{left-italic-correction}[@code{,}@var{subscript-correction}]]]]]
14240 There must not be any spaces between these subfields (it has been split
14241 here into two lines for better legibility only). Missing subfields are
14242 assumed to be@w{ }0. The subfields are all decimal integers. Since
14243 there is no associated binary format, these values are not required to
14244 fit into a variable of type @samp{char} as they are in @code{ditroff}.
14245 The @var{width} subfield gives the width of the glyph. The @var{height}
14246 subfield gives the height of the glyph (upwards is positive); if a
14247 glyph does not extend above the baseline, it should be given a zero
14248 height, rather than a negative height. The @var{depth} subfield gives
14249 the depth of the glyph, that is, the distance from the baseline to the
14250 lowest point below the baseline to which the glyph extends (downwards is
14251 positive); if a glyph does not extend below the baseline, it should be
14252 given a zero depth, rather than a negative depth. The
14253 @var{italic-correction} subfield gives the amount of space that should
14254 be added after the glyph when it is immediately to be followed by a
14255 glyph from a roman font. The @var{left-italic-correction} subfield
14256 gives the amount of space that should be added before the glyph when it
14257 is immediately to be preceded by a glyph from a roman font. The
14258 @var{subscript-correction} gives the amount of space that should be
14259 added after a glyph before adding a subscript. This should be less
14260 than the italic correction.
14262 A line in the @code{charset} section can also have the format
14269 This indicates that @var{name} is just another name for the glyph
14270 mentioned in the preceding line.
14273 The word @code{kernpairs} starts the kernpairs section. This contains a
14274 sequence of lines of the form:
14277 @var{c1} @var{c2} @var{n}
14281 This means that when glyph @var{c1} appears next to glyph @var{c2}
14282 the space between them should be increased by@w{ }@var{n}. Most
14283 entries in the kernpairs section have a negative value for@w{ }@var{n}.
14287 @c =====================================================================
14288 @c =====================================================================
14290 @node Installation, Copying This Manual, File formats, Top
14291 @chapter Installation
14292 @cindex installation
14298 @c =====================================================================
14299 @c =====================================================================
14301 @node Copying This Manual, Request Index, Installation, Top
14302 @appendix Copying This Manual
14305 * GNU Free Documentation License:: License for copying this manual.
14312 @c =====================================================================
14313 @c =====================================================================
14315 @node Request Index, Escape Index, Copying This Manual, Top
14316 @appendix Request Index
14318 Requests appear without the leading control character (normally either
14319 @samp{.} or @samp{'}).
14325 @c =====================================================================
14326 @c =====================================================================
14328 @node Escape Index, Operator Index, Request Index, Top
14329 @appendix Escape Index
14331 Any escape sequence @code{\@var{X}} with @var{X} not in the list below
14332 emits a warning, printing glyph @var{X}.
14338 @c =====================================================================
14339 @c =====================================================================
14341 @node Operator Index, Register Index, Escape Index, Top
14342 @appendix Operator Index
14348 @c =====================================================================
14349 @c =====================================================================
14351 @node Register Index, Macro Index, Operator Index, Top
14352 @appendix Register Index
14354 The macro package or program a specific register belongs to is appended in
14357 A register name@w{ }@code{x} consisting of exactly one character can be
14358 accessed as @samp{\nx}. A register name @code{xx} consisting of exactly
14359 two characters can be accessed as @samp{\n(xx}. Register names @code{xxx}
14360 of any length can be accessed as @samp{\n[xxx]}.
14366 @c =====================================================================
14367 @c =====================================================================
14369 @node Macro Index, String Index, Register Index, Top
14370 @appendix Macro Index
14372 The macro package a specific macro belongs to is appended in brackets.
14373 They appear without the leading control character (normally @samp{.}).
14379 @c =====================================================================
14380 @c =====================================================================
14382 @node String Index, Glyph Name Index, Macro Index, Top
14383 @appendix String Index
14385 The macro package or program a specific string belongs to is appended in
14388 A string name@w{ }@code{x} consisting of exactly one character can be
14389 accessed as @samp{\*x}. A string name @code{xx} consisting of exactly
14390 two characters can be accessed as @samp{\*(xx}. String names @code{xxx}
14391 of any length can be accessed as @samp{\*[xxx]}.
14398 @c =====================================================================
14399 @c =====================================================================
14401 @node Glyph Name Index, Font File Keyword Index, String Index, Top
14402 @appendix Glyph Name Index
14404 A glyph name @code{xx} consisting of exactly two characters can be
14405 accessed as @samp{\(xx}. Glyph names @code{xxx} of any length can be
14406 accessed as @samp{\[xxx]}.
14412 @c =====================================================================
14413 @c =====================================================================
14415 @node Font File Keyword Index, Program and File Index, Glyph Name Index, Top
14416 @appendix Font File Keyword Index
14422 @c =====================================================================
14423 @c =====================================================================
14425 @node Program and File Index, Concept Index, Font File Keyword Index, Top
14426 @appendix Program and File Index
14432 @c =====================================================================
14433 @c =====================================================================
14435 @node Concept Index, , Program and File Index, Top
14436 @appendix Concept Index