If a macro is called as a string, inherit value of \n[.br] from the
[s-roff.git] / doc / groff.texinfo
blobb5912abb7e9ae2ef9fd448e86b42fea4445f22a7
1 \input texinfo   @c -*-texinfo-*-
3 @c
4 @c Please convert this manual with `texi2dvi -e groff.texinfo' due to
5 @c problems in texinfo regarding expansion of user-defined macros.
6 @c
7 @c You need texinfo 4.8 or newer to format this document!
8 @c
10 @c %**start of header (This is for running Texinfo on a region.)
11 @setfilename groff.info
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.)
17 @documentlanguage en
18 @documentencoding ISO-8859-1
21 @smallbook
23 @finalout
26 @copying
27 This manual documents GNU @code{troff} version 1.19.3.
29 Copyright @copyright{} 1994-2000, 2001, 2002, 2003, 2004, 2005, 2006,
30 2007, 2008
31 Free Software Foundation, Inc.
33 @quotation
34 Permission is granted to copy, distribute and/or modify this document
35 under the terms of the GNU Free Documentation License, Version 1.1 or
36 any later version published by the Free Software Foundation; with no
37 Invariant Sections, with the Front-Cover texts being `A GNU Manual,''
38 and with the Back-Cover Texts as in (a) below.  A copy of the license is
39 included in the section entitled `GNU Free Documentation License.''
41 (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
42 modify this GNU manual.  Buying copies from the FSF supports it in
43 developing GNU and promoting software freedom.''
44 @end quotation
45 @end copying
48 @c We use the following indices:
50 @c   cindex: concepts
51 @c   rqindex: requests
52 @c   esindex: escapes
53 @c   vindex: registers
54 @c   kindex: commands in font files
55 @c   pindex: programs and files
56 @c   tindex: environment variables
57 @c   maindex: macros
58 @c   stindex: strings
59 @c   opindex: operators
61 @c tindex and cindex are merged.
63 @defcodeindex rq
64 @defcodeindex es
65 @defcodeindex ma
66 @defcodeindex st
67 @defcodeindex op
68 @syncodeindex tp cp
71 @c To avoid uppercasing in @deffn while converting to info, we define
72 @c our special @Var{}.
74 @macro Var{arg}
75 @r{@slanted{\arg\}}
76 @end macro
79 @c To assure correct HTML translation, some ugly hacks are necessary.
80 @c While processing a @def... request, the HTML translator looks at the
81 @c next line to decide whether to start indentation, and if the line
82 @c starts with @def... (e.g. @deffnx), indentation is started.  We must
83 @c therefore ensure that a @def... is seen, during macro expansion.
85 @c The following macros have to be used:
87 @c One item:
89 @c   @Def...
91 @c Two items:
93 @c   @Def...List
94 @c   @Def...ListEnd
96 @c More than two:
98 @c   @Def...List
99 @c   @Def...Item
100 @c   @Def...Item
101 @c   ...
102 @c   @Def...ListEnd
104 @c The definition block must end with
106 @c   @endDef...
108 @c The above is valid for texinfo 4.0f and above.
111 @c a dummy macro to assure the `@def...'
113 @macro defdummy
115 @end macro
118 @c definition of requests
120 @macro Defreq{name, arg}
121 @deffn Request @t{.\name\} \arg\
122 @rqindex \name\
124 @end macro
126 @macro DefreqList{name, arg}
127 @deffn Request @t{.\name\} \arg\
128 @defdummy
129 @rqindex \name\
131 @end macro
133 @macro DefreqItem{name, arg}
134 @deffnx Request @t{.\name\} \arg\
135 @defdummy
136 @rqindex \name\
138 @end macro
140 @macro DefreqListEnd{name, arg}
141 @deffnx Request @t{.\name\} \arg\
142 @rqindex \name\
144 @end macro
146 @macro endDefreq
147 @end deffn
148 @end macro
151 @c definition of escapes
153 @macro Defesc{name, delimI, arg, delimII}
154 @deffn Escape @t{\name\\delimI\}@Var{\arg\}@t{\delimII\}
155 @esindex \name\
157 @end macro
159 @macro DefescList{name, delimI, arg, delimII}
160 @deffn Escape @t{\name\\delimI\}@Var{\arg\}@t{\delimII\}
161 @defdummy
162 @esindex \name\
164 @end macro
166 @macro DefescItem{name, delimI, arg, delimII}
167 @deffnx Escape @t{\name\\delimI\}@Var{\arg\}@t{\delimII\}
168 @defdummy
169 @esindex \name\
171 @end macro
173 @macro DefescListEnd{name, delimI, arg, delimII}
174 @deffnx Escape @t{\name\\delimI\}@Var{\arg\}@t{\delimII\}
175 @esindex \name\
177 @end macro
179 @macro endDefesc
180 @end deffn
181 @end macro
184 @c definition of registers
186 @macro Defreg{name}
187 @deffn Register @t{\\n[\name\]}
188 @vindex \name\
190 @end macro
192 @macro DefregList{name}
193 @deffn Register @t{\\n[\name\]}
194 @defdummy
195 @vindex \name\
197 @end macro
199 @macro DefregItem{name}
200 @deffnx Register @t{\\n[\name\]}
201 @defdummy
202 @vindex \name\
204 @end macro
206 @macro DefregListEnd{name}
207 @deffnx Register @t{\\n[\name\]}
208 @vindex \name\
210 @end macro
212 @macro endDefreg
213 @end deffn
214 @end macro
217 @c definition of registers specific to macro packages, preprocessors, etc.
219 @macro Defmpreg{name, package}
220 @deffn Register @t{\\n[\name\]}
221 @vindex \name\ @r{[}\package\@r{]}
223 @end macro
225 @macro DefmpregList{name, package}
226 @deffn Register @t{\\n[\name\]}
227 @defdummy
228 @vindex \name\ @r{[}\package\@r{]}
230 @end macro
232 @macro DefmpregItem{name, package}
233 @deffnx Register @t{\\n[\name\]}
234 @defdummy
235 @vindex \name\ @r{[}\package\@r{]}
237 @end macro
239 @macro DefmpregListEnd{name, package}
240 @deffnx Register @t{\\n[\name\]}
241 @vindex \name\ @r{[}\package\@r{]}
243 @end macro
245 @macro endDefmpreg
246 @end deffn
247 @end macro
250 @c definition of macros
252 @macro Defmac{name, arg, package}
253 @defmac @t{.\name\} \arg\
254 @maindex \name\ @r{[}\package\@r{]}
256 @end macro
258 @macro DefmacList{name, arg, package}
259 @defmac @t{.\name\} \arg\
260 @defdummy
261 @maindex \name\ @r{[}\package\@r{]}
263 @end macro
265 @macro DefmacItem{name, arg, package}
266 @defmacx @t{.\name\} \arg\
267 @defdummy
268 @maindex \name\ @r{[}\package\@r{]}
270 @end macro
272 @macro DefmacListEnd{name, arg, package}
273 @defmacx @t{.\name\} \arg\
274 @maindex \name\ @r{[}\package\@r{]}
276 @end macro
278 @macro endDefmac
279 @end defmac
280 @end macro
283 @c definition of strings
285 @macro Defstr{name, package}
286 @deffn String @t{\\*[\name\]}
287 @stindex \name\ @r{[}\package\@r{]}
289 @end macro
291 @macro DefstrList{name, package}
292 @deffn String @t{\\*[\name\]}
293 @defdummy
294 @stindex \name\ @r{[}\package\@r{]}
296 @end macro
298 @macro DefstrItem{name, package}
299 @deffnx String @t{\\*[\name\]}
300 @defdummy
301 @stindex \name\ @r{[}\package\@r{]}
303 @end macro
305 @macro DefstrListEnd{name, package}
306 @deffnx String @t{\\*[\name\]}
307 @stindex \name\ @r{[}\package\@r{]}
309 @end macro
311 @macro endDefstr
312 @end deffn
313 @end macro
316 @c our example macro
318 @macro Example
319 @example
320 @group
321 @end macro
323 @macro endExample
324 @end group
325 @end example
326 @end macro
329 @c <text>
331 @tex
332 \gdef\Langlemacro{\angleleft}
333 \gdef\Ranglemacro{\angleright}
334 @end tex
336 @iftex
337 @set Langlemacro @Langlemacro
338 @set Ranglemacro @Ranglemacro
339 @end iftex
341 @ifnottex
342 @set Langlemacro <
343 @set Ranglemacro >
344 @end ifnottex
346 @macro angles{text}
347 @value{Langlemacro}@r{\text\}@value{Ranglemacro}
348 @end macro
351 @c a <= sign
353 @c A value defined with @set is embedded into three group levels if
354 @c called with @value, so we need seven \aftergroup to put \le outside
355 @c of the groups -- this is necessary to get proper mathematical
356 @c spacing.
358 @tex
359 \gdef\LEmacro{\aftergroup\aftergroup\aftergroup\aftergroup
360               \aftergroup\aftergroup\aftergroup\le}
361 @end tex
363 @iftex
364 @set LEmacro @LEmacro
365 @end iftex
367 @ifnottex
368 @set LEmacro <=
369 @end ifnottex
371 @macro LE
372 @value{LEmacro}
373 @end macro
376 @c Special care is required with parentheses, brackets, and braces:
378 @c . Real parentheses in @deffn produce an error while compiling with
379 @c   TeX.
380 @c . Real brackets use the wrong font in @deffn, overriding @t{}.
382 @c . @{ and @} fail with info if used in a macro.
384 @c Since macros aren't expanded in @deffn during -E, the following
385 @c definitions are for non-TeX only.
387 @c This is true for texinfo 4.0 and above.
389 @iftex
390 @set Lparenmacro @lparen
391 @set Rparenmacro @rparen
392 @set Lbrackmacro @lbrack
393 @set Rbrackmacro @rbrack
394 @set Lbracemacro @{
395 @set Rbracemacro @}
396 @end iftex
398 @ifnottex
399 @set Lparenmacro (
400 @set Rparenmacro )
401 @set Lbrackmacro [
402 @set Rbrackmacro ]
403 @set Lbracemacro @{
404 @set Rbracemacro @}
405 @end ifnottex
407 @macro Lparen{}
408 @value{Lparenmacro}
409 @end macro
410 @macro Rparen{}
411 @value{Rparenmacro}
412 @end macro
413 @macro Lbrack{}
414 @value{Lbrackmacro}
415 @end macro
416 @macro Rbrack{}
417 @value{Rbrackmacro}
418 @end macro
419 @macro Lbrace{}
420 @value{Lbracemacro}
421 @end macro
422 @macro Rbrace{}
423 @value{Rbracemacro}
424 @end macro
427 @c This suppresses the word `Appendix' in the appendix headers.
429 @tex
430 \gdef\gobblefirst#1#2{#2}
431 \gdef\putwordAppendix{\gobblefirst}
432 @end tex
435 @c We map some latin-1 characters to corresponding texinfo macros.
436 @c Newer versions of texinfo.tex have similar code included already.
438 @tex
439 \global\catcode`^^e4\active % Ã¤
440 \gdef^^e4{\"a}
441 \global\catcode`^^c4\active % Ã„
442 \gdef^^c4{\"A}
443 \global\catcode`^^e9\active % Ã©
444 \gdef^^e9{\'e}
445 \global\catcode`^^c9\active % Ã‰
446 \gdef^^c9{\'E}
447 \global\catcode`^^f6\active % Ã¶
448 \gdef^^f6{\"o}
449 \global\catcode`^^d6\active % Ã–
450 \gdef^^d6{\"O}
451 \global\catcode`^^fc\active % Ã¼
452 \gdef^^fc{\"u}
453 \global\catcode`^^dc\active % Ãœ
454 \gdef^^dc{\"U}
455 \global\catcode`^^e6\active % Ã¦
456 \gdef^^e6{\ae}
457 \global\catcode`^^c6\active % Ã†
458 \gdef^^c6{\AE}
459 \global\catcode`^^df\active % ÃŸ
460 \gdef^^df{\ss}
461 @end tex
464 @c Note: We say `Roman numerals' but `roman font'.
467 @dircategory Typesetting
468 @direntry
469 * Groff: (groff).               The GNU troff document formatting system.
470 @end direntry
473 @titlepage
474 @title groff
475 @subtitle The GNU implementation of @code{troff}
476 @subtitle Edition 1.19.3
477 @subtitle Autumn 2008
478 @author by Trent A.@tie{}Fisher
479 @author and Werner Lemberg (@email{bug-groff@@gnu.org})
481 @page
482 @vskip 0pt plus 1filll
483 @insertcopying
484 @end titlepage
486 @contents
488 @ifnottex
489 @node Top, Introduction, (dir), (dir)
490 @top GNU troff
491 @end ifnottex
493 @menu
494 * Introduction::
495 * Invoking groff::
496 * Tutorial for Macro Users::
497 * Macro Packages::
498 * gtroff Reference::
499 * Preprocessors::
500 * Output Devices::
501 * File formats::
502 * Installation::
503 * Copying This Manual::
504 * Request Index::
505 * Escape Index::
506 * Operator Index::
507 * Register Index::
508 * Macro Index::
509 * String Index::
510 * Glyph Name Index::
511 * Font File Keyword Index::
512 * Program and File Index::
513 * Concept Index::
514 @end menu
516 @ifnottex
517 @insertcopying
518 @end ifnottex
522 @c =====================================================================
523 @c =====================================================================
525 @node Introduction, Invoking groff, Top, Top
526 @chapter Introduction
527 @cindex introduction
529 GNU @code{troff} (or @code{groff}) is a system for typesetting
530 documents.  @code{troff} is very flexible and has been used extensively
531 for some thirty years.  It is well entrenched in the @acronym{UNIX}
532 community.
534 @menu
535 * What Is groff?::
536 * History::
537 * groff Capabilities::
538 * Macro Package Intro::
539 * Preprocessor Intro::
540 * Output device intro::
541 * Credits::
542 @end menu
545 @c =====================================================================
547 @node What Is groff?, History, Introduction, Introduction
548 @section What Is @code{groff}?
549 @cindex what is @code{groff}?
550 @cindex @code{groff} -- what is it?
552 @code{groff} belongs to an older generation of document preparation
553 systems, which operate more like compilers than the more recent
554 interactive @acronym{WYSIWYG}@footnote{What You See Is What You Get}
555 systems.  @code{groff} and its contemporary counterpart, @TeX{}, both
556 work using a @dfn{batch} paradigm: The input (or @dfn{source}) files are
557 normal text files with embedded formatting commands.  These files can
558 then be processed by @code{groff} to produce a typeset document on a
559 variety of devices.
561 @code{groff} should not be confused with a @dfn{word processor}, an
562 integrated system of editor and text formatter.  Also, many word
563 processors follow the @acronym{WYSIWYG} paradigm discussed earlier.
565 Although @acronym{WYSIWYG} systems may be easier to use, they have a
566 number of disadvantages compared to @code{troff}:
568 @itemize @bullet
569 @item
570 They must be used on a graphics display to work on a document.
572 @item
573 Most of the @acronym{WYSIWYG} systems are either non-free or are not
574 very portable.
576 @item
577 @code{troff} is firmly entrenched in all @acronym{UNIX} systems.
579 @item
580 It is difficult to have a wide range of capabilities within the confines
581 of a GUI/window system.
583 @item
584 It is more difficult to make global changes to a document.
585 @end itemize
587 @quotation
588 ``GUIs normally make it simple to accomplish simple actions and
589 impossible to accomplish complex actions.''  --Doug Gwyn (22/Jun/91 in
590 @code{comp.unix.wizards})
591 @end quotation
594 @c =====================================================================
596 @node History, groff Capabilities, What Is groff?, Introduction
597 @section History
598 @cindex history
600 @cindex @code{RUNOFF}, the program
601 @cindex @code{rf}, the program
602 @code{troff} can trace its origins back to a formatting program called
603 @code{RUNOFF}, written by Jerry E.@: Saltzer, which ran on MIT's
604 @acronym{CTSS} (@emph{Compatible Time Sharing System}) operating system
605 in the mid-sixties.  The name came from the use of the phrase ``run off
606 a document'', meaning to print it out.  Bob Morris ported it to the 635
607 architecture and called the program @code{roff} (an abbreviation of
608 @code{runoff}).  It was rewritten as @code{rf} for the @w{PDP-7} (before
609 having @acronym{UNIX}), and at the same time (1969), Doug McIllroy
610 rewrote an extended and simplified version of @code{roff} in the
611 @acronym{BCPL} programming language.
613 @cindex @code{roff}, the program
614 The first version of @acronym{UNIX} was developed on a @w{PDP-7} which
615 was sitting around Bell Labs.  In 1971, the developers wanted to get a
616 @w{PDP-11} for further work on the operating system, and to justify the
617 cost, proposed the development of a document formatting system for the
618 @acronym{AT&T} patents division.  This first formatting program was a
619 reimplementation of McIllroy's @code{roff}, written by
620 J.@tie{}F.@tie{}Ossanna.
622 @cindex @code{nroff}, the program
623 When they needed a more flexible language, a new version of @code{roff}
624 called @code{nroff} (``Newer @code{roff}'') was written.  It had a much
625 more complicated syntax, but provided the basis for all future versions.
626 When they got a Graphic Systems CAT Phototypesetter, Ossanna wrote a
627 version of @code{nroff} that would drive it.  It was dubbed
628 @code{troff}, for ``typesetter @code{roff}'', although many people have
629 speculated that it actually means ``Times @code{roff}'' because of the
630 use of the Times font family in @code{troff} by default.  As such, the
631 name @code{troff} is pronounced `@w{t-roff}' rather than `trough'.
633 With @code{troff} came @code{nroff} (they were actually the same program
634 except for some @samp{#ifdef}s), which was for producing output for line
635 printers and character terminals.  It understood everything @code{troff}
636 did, and ignored the commands which were not applicable (e.g.@: font
637 changes).
639 Since there are several things which cannot be done easily in
640 @code{troff}, work on several preprocessors began.  These programs would
641 transform certain parts of a document into @code{troff}, which made a
642 very natural use of pipes in @acronym{UNIX}.
644 The @code{eqn} preprocessor allowed mathematical formulæ to be specified
645 in a much simpler and more intuitive manner.  @code{tbl} is a
646 preprocessor for formatting tables.  The @code{refer} preprocessor (and
647 the similar program, @code{bib}) processes citations in a document
648 according to a bibliographic database.
650 Unfortunately, Ossanna's @code{troff} was written in @w{PDP-11} assembly
651 language and produced output specifically for the CAT phototypesetter.
652 He rewrote it in C, although it was now 7000@tie{}lines of uncommented
653 code and still dependent on the CAT.  As the CAT became less common, and
654 was no longer supported by the manufacturer, the need to make it support
655 other devices became a priority.  However, before this could be done,
656 Ossanna died by a severe heart attack in a hospital while recovering
657 from a previous one.
659 @pindex ditroff
660 @cindex @code{ditroff}, the program
661 So, Brian Kernighan took on the task of rewriting @code{troff}.  The
662 newly rewritten version produced device independent code which was very
663 easy for postprocessors to read and translate to the appropriate printer
664 codes.  Also, this new version of @code{troff} (called @code{ditroff}
665 for ``device independent @code{troff}'') had several extensions, which
666 included drawing functions.
668 Due to the additional abilities of the new version of @code{troff},
669 several new preprocessors appeared.  The @code{pic} preprocessor
670 provides a wide range of drawing functions.  Likewise the @code{ideal}
671 preprocessor did the same, although via a much different paradigm.  The
672 @code{grap} preprocessor took specifications for graphs, but, unlike
673 other preprocessors, produced @code{pic} code.
675 James Clark began work on a GNU implementation of @code{ditroff} in
676 early@tie{}1989.  The first version, @code{groff}@tie{}0.3.1, was
677 released June@tie{}1990.  @code{groff} included:
679 @itemize @bullet
680 @item
681 A replacement for @code{ditroff} with many extensions.
683 @item
684 The @code{soelim}, @code{pic}, @code{tbl}, and @code{eqn} preprocessors.
686 @item
687 Postprocessors for character devices, @sc{PostScript}, @TeX{} DVI, and
688 X@tie{}Windows.  GNU @code{troff} also eliminated the need for a
689 separate @code{nroff} program with a postprocessor which would produce
690 @acronym{ASCII} output.
692 @item
693 A version of the @file{me} macros and an implementation of the
694 @file{man} macros.
695 @end itemize
697 Also, a front-end was included which could construct the, sometimes
698 painfully long, pipelines required for all the post- and preprocessors.
700 Development of GNU @code{troff} progressed rapidly, and saw the
701 additions of a replacement for @code{refer}, an implementation of the
702 @file{ms} and @file{mm} macros, and a program to deduce how to format a
703 document (@code{grog}).
705 It was declared a stable (i.e.@: non-beta) package with the release of
706 version@tie{}1.04 around November@tie{}1991.
708 Beginning in@tie{}1999, @code{groff} has new maintainers (the package
709 was an orphan for a few years).  As a result, new features and programs
710 like @code{grn}, a preprocessor for gremlin images, and an output device
711 to produce @acronym{HTML} and @acronym{XHTML} have been added.
714 @c =====================================================================
716 @node groff Capabilities, Macro Package Intro, History, Introduction
717 @section @code{groff} Capabilities
718 @cindex @code{groff} capabilities
719 @cindex capabilities of @code{groff}
721 So what exactly is @code{groff} capable of doing?  @code{groff} provides
722 a wide range of low-level text formatting operations.  Using these, it
723 is possible to perform a wide range of formatting tasks, such as
724 footnotes, table of contents, multiple columns, etc.  Here's a list of
725 the most important operations supported by @code{groff}:
727 @itemize @bullet
728 @item
729 text filling, adjusting, and centering
731 @item
732 hyphenation
734 @item
735 page control
737 @item
738 font and glyph size control
740 @item
741 vertical spacing (e.g.@: double-spacing)
743 @item
744 line length and indenting
746 @item
747 macros, strings, diversions, and traps
749 @item
750 number registers
752 @item
753 tabs, leaders, and fields
755 @item
756 input and output conventions and character translation
758 @item
759 overstrike, bracket, line drawing, and zero-width functions
761 @item
762 local horizontal and vertical motions and the width function
764 @item
765 three-part titles
767 @item
768 output line numbering
770 @item
771 conditional acceptance of input
773 @item
774 environment switching
776 @item
777 insertions from the standard input
779 @item
780 input/output file switching
782 @item
783 output and error messages
784 @end itemize
787 @c =====================================================================
789 @node Macro Package Intro, Preprocessor Intro, groff Capabilities, Introduction
790 @section Macro Packages
791 @cindex macro packages
793 Since @code{groff} provides such low-level facilities, it can be quite
794 difficult to use by itself.  However, @code{groff} provides a
795 @dfn{macro} facility to specify how certain routine operations
796 (e.g.@tie{}starting paragraphs, printing headers and footers, etc.)@:
797 should be done.  These macros can be collected together into a
798 @dfn{macro package}.  There are a number of macro packages available;
799 the most common (and the ones described in this manual) are @file{man},
800 @file{mdoc}, @file{me}, @file{ms}, and @file{mm}.
803 @c =====================================================================
805 @node Preprocessor Intro, Output device intro, Macro Package Intro, Introduction
806 @section Preprocessors
807 @cindex preprocessors
809 Although @code{groff} provides most functions needed to format a
810 document, some operations would be unwieldy (e.g.@: to draw pictures).
811 Therefore, programs called @dfn{preprocessors} were written which
812 understand their own language and produce the necessary @code{groff}
813 operations.  These preprocessors are able to differentiate their own
814 input from the rest of the document via markers.
816 To use a preprocessor, @acronym{UNIX} pipes are used to feed the output
817 from the preprocessor into @code{groff}.  Any number of preprocessors
818 may be used on a given document; in this case, the preprocessors are
819 linked together into one pipeline.  However, with @code{groff}, the user
820 does not need to construct the pipe, but only tell @code{groff} what
821 preprocessors to use.
823 @code{groff} currently has preprocessors for producing tables
824 (@code{tbl}), typesetting equations (@code{eqn}), drawing pictures
825 (@code{pic} and @code{grn}), and for processing bibliographies
826 (@code{refer}).  An associated program which is useful when dealing with
827 preprocessors is @code{soelim}.
829 A free implementation of @code{grap}, a preprocessor for drawing graphs,
830 can be obtained as an extra package; @code{groff} can use @code{grap}
831 also.
833 There are other preprocessors in existence, but, unfortunately, no free
834 implementations are available.  Among them are preprocessors for drawing
835 mathematical pictures (@code{ideal}) and chemical structures
836 (@code{chem}).
839 @c =====================================================================
841 @node Output device intro, Credits, Preprocessor Intro, Introduction
842 @section Output Devices
843 @cindex postprocessors
844 @cindex output devices
845 @cindex devices for output
847 @code{groff} actually produces device independent code which may be fed
848 into a postprocessor to produce output for a particular device.
849 Currently, @code{groff} has postprocessors for @sc{PostScript} devices,
850 character terminals, X@tie{}Windows (for previewing), @TeX{} DVI format,
851 HP LaserJet@tie{}4 and Canon LBP printers (which use @acronym{CAPSL}),
852 @acronym{HTML}, and @acronym{XHTML}.
855 @c =====================================================================
857 @node Credits,  , Output device intro, Introduction
858 @section Credits
859 @cindex credits
861 Large portions of this manual were taken from existing documents, most
862 notably, the manual pages for the @code{groff} package by James Clark,
863 and Eric Allman's papers on the @file{me} macro package.
865 The section on the @file{man} macro package is partly based on
866 Susan@tie{}G.@: Kleinmann's @file{groff_man} manual page written for the
867 Debian GNU/Linux system.
869 Larry Kollar contributed the section in the @file{ms} macro package.
873 @c =====================================================================
874 @c =====================================================================
876 @node Invoking groff, Tutorial for Macro Users, Introduction, Top
877 @chapter Invoking @code{groff}
878 @cindex invoking @code{groff}
879 @cindex @code{groff} invocation
881 This section focuses on how to invoke the @code{groff} front end.  This
882 front end takes care of the details of constructing the pipeline among
883 the preprocessors, @code{gtroff} and the postprocessor.
885 It has become a tradition that GNU programs get the prefix @samp{g} to
886 distinguish it from its original counterparts provided by the host (see
887 @ref{Environment}, for more details).  Thus, for example, @code{geqn} is
888 GNU @code{eqn}.  On operating systems like GNU/Linux or the Hurd, which
889 don't contain proprietary versions of @code{troff}, and on
890 MS-DOS/MS-Windows, where @code{troff} and associated programs are not
891 available at all, this prefix is omitted since GNU @code{troff} is the
892 only used incarnation of @code{troff}.  Exception: @samp{groff} is never
893 replaced by @samp{roff}.
895 In this document, we consequently say @samp{gtroff} when talking about
896 the GNU @code{troff} program.  All other implementations of @code{troff}
897 are called @acronym{AT&T} @code{troff} which is the common origin of all
898 @code{troff} derivates (with more or less compatible changes).
899 Similarly, we say @samp{gpic}, @samp{geqn}, etc.
901 @menu
902 * Groff Options::
903 * Environment::
904 * Macro Directories::
905 * Font Directories::
906 * Paper Size::
907 * Invocation Examples::
908 @end menu
911 @c =====================================================================
913 @node Groff Options, Environment, Invoking groff, Invoking groff
914 @section Options
915 @cindex options
917 @pindex groff
918 @pindex gtroff
919 @pindex gpic
920 @pindex geqn
921 @pindex ggrn
922 @pindex grap
923 @pindex gtbl
924 @pindex grefer
925 @pindex gsoelim
926 @code{groff} normally runs the @code{gtroff} program and a postprocessor
927 appropriate for the selected device.  The default device is @samp{ps}
928 (but it can be changed when @code{groff} is configured and built).  It
929 can optionally preprocess with any of @code{gpic}, @code{geqn},
930 @code{gtbl}, @code{ggrn}, @code{grap}, @code{grefer}, or @code{gsoelim}.
932 This section only documents options to the @code{groff} front end.  Many
933 of the arguments to @code{groff} are passed on to @code{gtroff},
934 therefore those are also included.  Arguments to pre- or postprocessors
935 can be found in @ref{Invoking gpic}, @ref{Invoking geqn}, @ref{Invoking
936 gtbl}, @ref{Invoking ggrn}, @ref{Invoking grefer}, @ref{Invoking
937 gsoelim}, @ref{Invoking grotty}, @ref{Invoking grops}, @ref{Invoking
938 grohtml}, @ref{Invoking grodvi}, @ref{Invoking grolj4}, @ref{Invoking
939 grolbp}, and @ref{Invoking gxditview}.
941 The command line format for @code{groff} is:
943 @Example
944 groff [ -abceghilpstvzCEGNRSUVXZ ] [ -F@var{dir} ] [ -m@var{name} ]
945       [ -T@var{def} ] [ -f@var{fam} ] [ -w@var{name} ] [ -W@var{name} ]
946       [ -M@var{dir} ] [ -d@var{cs} ] [ -r@var{cn} ] [ -n@var{num} ]
947       [ -o@var{list} ] [ -P@var{arg} ] [ -L@var{arg} ] [ -I@var{dir} ]
948       [ @var{files}@dots{} ]
949 @endExample
951 The command line format for @code{gtroff} is as follows.
953 @Example
954 gtroff [ -abcivzCERU ] [ -w@var{name} ] [ -W@var{name} ] [ -d@var{cs} ]
955        [ -f@var{fam} ] [ -m@var{name} ] [ -n@var{num} ]
956        [ -o@var{list} ] [ -r@var{cn} ] [ -T@var{name} ]
957        [ -F@var{dir} ] [ -M@var{dir} ] [ @var{files}@dots{} ]
958 @endExample
960 @noindent
961 Obviously, many of the options to @code{groff} are actually passed on to
962 @code{gtroff}.
964 Options without an argument can be grouped behind a
965 single@tie{}@option{-}.  A filename of@tie{}@file{-} denotes the
966 standard input.  It is possible to have whitespace between an option and
967 its parameter.
969 The @code{grog} command can be used to guess the correct @code{groff}
970 command to format a file.
972 Here's the description of the command-line options:
974 @cindex command-line options
975 @table @samp
976 @item -h
977 Print a help message.
979 @item -e
980 Preprocess with @code{geqn}.
982 @item -t
983 Preprocess with @code{gtbl}.
985 @item -g
986 Preprocess with @code{ggrn}.
988 @item -G
989 Preprocess with @code{grap}.
991 @item -p
992 Preprocess with @code{gpic}.
994 @item -s
995 Preprocess with @code{gsoelim}.
997 @item -c
998 Suppress color output.
1000 @item -R
1001 Preprocess with @code{grefer}.  No mechanism is provided for passing
1002 arguments to @code{grefer} because most @code{grefer} options have
1003 equivalent commands which can be included in the file.  @xref{grefer},
1004 for more details.
1006 @pindex troffrc
1007 @pindex troffrc-end
1008 Note that @code{gtroff} also accepts a @option{-R} option, which is not
1009 accessible via @code{groff}.  This option prevents the loading of the
1010 @file{troffrc} and @file{troffrc-end} files.
1012 @item -v
1013 Make programs run by @code{groff} print out their version number.
1015 @item -V
1016 Print the pipeline on @code{stdout} instead of executing it.  If
1017 specified more than once, print the pipeline on @code{stderr} and
1018 execute it.
1020 @item -z
1021 Suppress output from @code{gtroff}.  Only error messages are printed.
1023 @item -Z
1024 Do not postprocess the output of @code{gtroff}.  Normally @code{groff}
1025 automatically runs the appropriate postprocessor.
1027 @item -P@var{arg}
1028 Pass @var{arg} to the postprocessor.  Each argument should be passed
1029 with a separate @option{-P} option.  Note that @code{groff} does not
1030 prepend @samp{-} to @var{arg} before passing it to the postprocessor.
1032 @item -l
1033 Send the output to a spooler for printing.  The command used for this is
1034 specified by the @code{print} command in the device description file
1035 (see @ref{Font Files}, for more info).  If not present, @option{-l} is
1036 ignored.
1038 @item -L@var{arg}
1039 Pass @var{arg} to the spooler.  Each argument should be passed with a
1040 separate @option{-L} option.  Note that @code{groff} does not prepend a
1041 @samp{-} to @var{arg} before passing it to the postprocessor.  If the
1042 @code{print} keyword in the device description file is missing,
1043 @option{-L} is ignored.
1045 @item -T@var{dev}
1046 Prepare output for device @var{dev}.  The default device is @samp{ps},
1047 unless changed when @code{groff} was configured and built.  The
1048 following are the output devices currently available:
1050 @table @code
1051 @item ps
1052 For @sc{PostScript} printers and previewers.
1054 @item dvi
1055 For @TeX{} DVI format.
1057 @item X75
1058 For a 75@dmn{dpi} X11 previewer.
1060 @item X75-12
1061 For a 75@dmn{dpi} X11 previewer with a 12@dmn{pt} base font in the
1062 document.
1064 @item X100
1065 For a 100@dmn{dpi} X11 previewer.
1067 @item X100-12
1068 For a 100@dmn{dpi} X11 previewer with a 12@dmn{pt} base font in the
1069 document.
1071 @item ascii
1072 @cindex encoding, output, @acronym{ASCII}
1073 @cindex @acronym{ASCII}, output encoding
1074 @cindex output encoding, @acronym{ASCII}
1075 For typewriter-like devices using the (7-bit) @acronym{ASCII}
1076 character set.
1078 @item latin1
1079 @cindex encoding, output, @w{latin-1} (ISO @w{8859-1})
1080 @cindex @w{latin-1} (ISO @w{8859-1}), output encoding
1081 @cindex ISO @w{8859-1} (@w{latin-1}), output encoding
1082 @cindex output encoding, @w{latin-1} (ISO @w{8859-1})
1083 For typewriter-like devices that support the @w{Latin-1}
1084 (ISO@tie{}@w{8859-1}) character set.
1086 @item utf8
1087 @cindex encoding, output, @w{utf-8}
1088 @cindex @w{utf-8}, output encoding
1089 @cindex output encoding, @w{utf-8}
1090 For typewriter-like devices which use the Unicode (ISO@tie{}10646)
1091 character set with @w{UTF-8} encoding.
1093 @item cp1047
1094 @cindex encoding, output, @acronym{EBCDIC}
1095 @cindex @acronym{EBCDIC}, output encoding
1096 @cindex output encoding, @acronym{EBCDIC}
1097 @cindex encoding, output, cp1047
1098 @cindex cp1047, output encoding
1099 @cindex output encoding, cp1047
1100 @cindex IBM cp1047 output encoding
1101 For typewriter-like devices which use the @acronym{EBCDIC} encoding IBM
1102 cp1047.
1104 @item lj4
1105 For HP LaserJet4-compatible (or other PCL5-compatible) printers.
1107 @item lbp
1108 For Canon @acronym{CAPSL} printers (@w{LBP-4} and @w{LBP-8} series laser
1109 printers).
1111 @pindex pre-grohtml
1112 @pindex post-grohtml
1113 @cindex @code{grohtml}, the program
1114 @item html
1115 @itemx xhtml
1116 To produce @acronym{HTML} and @acronym{XHTML} output, respectively.
1117 Note that this driver consists of two parts, a preprocessor
1118 (@code{pre-grohtml}) and a postprocessor (@code{post-grohtml}).
1119 @end table
1121 @cindex output device name string register (@code{.T})
1122 @cindex output device usage number register (@code{.T})
1123 The predefined @code{gtroff} string register @code{.T} contains the
1124 current output device; the read-only number register @code{.T} is set
1125 to@tie{}1 if this option is used (which is always true if @code{groff}
1126 is used to call @code{gtroff}).  @xref{Built-in Registers}.
1128 The postprocessor to be used for a device is specified by the
1129 @code{postpro} command in the device description file.  (@xref{Font
1130 Files}, for more info.)  This can be overridden with the @option{-X}
1131 option.
1133 @item -X
1134 Preview with @code{gxditview} instead of using the usual postprocessor.
1135 This is unlikely to produce good results except with @option{-Tps}.
1137 Note that this is not the same as using @option{-TX75} or
1138 @option{-TX100} to view a document with @code{gxditview}: The former
1139 uses the metrics of the specified device, whereas the latter uses
1140 X-specific fonts and metrics.
1142 @item -N
1143 Don't allow newlines with @code{eqn} delimiters.  This is the same as
1144 the @option{-N} option in @code{geqn}.
1146 @item -S
1147 @cindex @code{open} request, and safer mode
1148 @cindex @code{opena} request, and safer mode
1149 @cindex @code{pso} request, and safer mode
1150 @cindex @code{sy} request, and safer mode
1151 @cindex @code{pi} request, and safer mode
1152 @cindex safer mode
1153 @cindex mode, safer
1154 Safer mode.  Pass the @option{-S} option to @code{gpic} and disable the
1155 @code{open}, @code{opena}, @code{pso}, @code{sy}, and @code{pi}
1156 requests.  For security reasons, this is enabled by default.
1158 @item -U
1159 @cindex mode, unsafe
1160 @cindex unsafe mode
1161 Unsafe mode.  This enables the @code{open}, @code{opena}, @code{pso},
1162 @code{sy}, and @code{pi} requests.
1164 @item -a
1165 @cindex @acronym{ASCII} approximation output register (@code{.A})
1166 Generate an @acronym{ASCII} approximation of the typeset output.  The
1167 read-only register @code{.A} is then set to@tie{}1.  @xref{Built-in
1168 Registers}.  A typical example is
1170 @Example
1171 groff -a -man -Tdvi troff.man | less
1172 @endExample
1174 @noindent
1175 which shows how lines are broken for the DVI device.  Note that this
1176 option is rather useless today since graphic output devices are
1177 available virtually everywhere.
1179 @item -b
1180 Print a backtrace with each warning or error message.  This backtrace
1181 should help track down the cause of the error.  The line numbers given
1182 in the backtrace may not always be correct: @code{gtroff} can get
1183 confused by @code{as} or @code{am} requests while counting line numbers.
1185 @item -i
1186 Read the standard input after all the named input files have been
1187 processed.
1189 @item -w@var{name}
1190 Enable warning @var{name}.  Available warnings are described in
1191 @ref{Debugging}.  Multiple @option{-w} options are allowed.
1193 @item -W@var{name}
1194 Inhibit warning @var{name}.  Multiple @option{-W} options are allowed.
1196 @item -E
1197 Inhibit all error messages.
1199 @item -C
1200 Enable compatibility mode.  @xref{Implementation Differences}, for the
1201 list of incompatibilities between @code{groff} and @acronym{AT&T}
1202 @code{troff}.
1204 @item -d@var{c}@var{s}
1205 @itemx -d@var{name}=@var{s}
1206 Define @var{c} or @var{name} to be a string@tie{}@var{s}.
1207 @var{c}@tie{}must be a one-letter name; @var{name} can be of arbitrary
1208 length.  All string assignments happen before loading any macro file
1209 (including the start-up file).
1211 @item -f@var{fam}
1212 Use @var{fam} as the default font family.  @xref{Font Families}.
1214 @item -m@var{name}
1215 Read in the file @file{@var{name}.tmac}.  Normally @code{groff} searches
1216 for this in its macro directories.  If it isn't found, it tries
1217 @file{tmac.@var{name}} (searching in the same directories).
1219 @item -n@var{num}
1220 Number the first page @var{num}.
1222 @item -o@var{list}
1223 @cindex print current page register (@code{.P})
1224 Output only pages in @var{list}, which is a comma-separated list of page
1225 ranges; @samp{@var{n}} means print page@tie{}@var{n},
1226 @samp{@var{m}-@var{n}} means print every page between @var{m}
1227 and@tie{}@var{n}, @samp{-@var{n}} means print every page up
1228 to@tie{}@var{n}, @samp{@var{n}-} means print every page beginning
1229 with@tie{}@var{n}.  @code{gtroff} exits after printing the last page in
1230 the list.  All the ranges are inclusive on both ends.
1232 Within @code{gtroff}, this information can be extracted with the
1233 @samp{.P} register.  @xref{Built-in Registers}.
1235 If your document restarts page numbering at the beginning of each
1236 chapter, then @code{gtroff} prints the specified page range for each
1237 chapter.
1239 @item -r@var{c}@var{n}
1240 @itemx -r@var{name}=@var{n}
1241 Set number register@tie{}@var{c} or @var{name} to the
1242 value@tie{}@var{n}.  @var{c}@tie{}must be a one-letter name; @var{name}
1243 can be of arbitrary length.  @var{n}@tie{}can be any @code{gtroff}
1244 numeric expression.  All register assignments happen before loading any
1245 macro file (including the start-up file).
1247 @item -F@var{dir}
1248 Search @file{@var{dir}} for subdirectories @file{dev@var{name}}
1249 (@var{name} is the name of the device), for the @file{DESC} file, and
1250 for font files before looking in the standard directories (@pxref{Font
1251 Directories}).  This option is passed to all pre- and postprocessors
1252 using the @env{GROFF_FONT_PATH} environment variable.
1254 @item -M@var{dir}
1255 Search directory @file{@var{dir}} for macro files before the standard
1256 directories (@pxref{Macro Directories}).
1258 @item -I@var{dir}
1259 This option may be used to specify a directory to search for files.
1260 It is passed to the following programs:
1262 @itemize
1263 @item
1264 @code{gsoelim} (see @ref{gsoelim} for more details);
1265 it also implies @code{groff}'s @option{-s} option.
1267 @item
1268 @code{gtroff}; it is used to search files named in the @code{psbb} and
1269 @code{so} requests.
1271 @item
1272 @code{grops}; it is used to search files named in the
1273 @w{@code{\X'ps: import}} and @w{@code{\X'ps: file}} escapes.
1274 @end itemize
1276 The current directory is always searched first.  This option may be
1277 specified more than once; the directories are searched in the order
1278 specified.  No directory search is performed for files specified using
1279 an absolute path.
1280 @end table
1283 @c =====================================================================
1285 @node Environment, Macro Directories, Groff Options, Invoking groff
1286 @section Environment
1287 @cindex environment variables
1288 @cindex variables in environment
1290 There are also several environment variables (of the operating system,
1291 not within @code{gtroff}) which can modify the behavior of @code{groff}.
1293 @table @code
1294 @item GROFF_COMMAND_PREFIX
1295 @tindex GROFF_COMMAND_PREFIX@r{, environment variable}
1296 @cindex command prefix
1297 @cindex prefix, for commands
1298 If this is set to@tie{}@var{X}, then @code{groff} runs
1299 @code{@var{X}troff} instead of @code{gtroff}.  This also applies to
1300 @code{tbl}, @code{pic}, @code{eqn}, @code{grn}, @code{refer}, and
1301 @code{soelim}.  It does not apply to @code{grops}, @code{grodvi},
1302 @code{grotty}, @code{pre-grohtml}, @code{post-grohtml}, @code{grolj4},
1303 and @code{gxditview}.
1305 The default command prefix is determined during the installation
1306 process.  If a non-GNU troff system is found, prefix @samp{g} is used,
1307 none otherwise.
1309 @item GROFF_TMAC_PATH
1310 @tindex GROFF_TMAC_PATH@r{, environment variable}
1311 A colon-separated list of directories in which to search for macro files
1312 (before the default directories are tried).  @xref{Macro Directories}.
1314 @item GROFF_TYPESETTER
1315 @tindex GROFF_TYPESETTER@r{, environment variable}
1316 The default output device.
1318 @item GROFF_FONT_PATH
1319 @tindex GROFF_FONT_PATH@r{, environment variable}
1320 A colon-separated list of directories in which to search for the
1321 @code{dev}@var{name} directory (before the default directories are
1322 tried).  @xref{Font Directories}.
1324 @item GROFF_BIN_PATH
1325 @tindex GROFF_BIN_PATH@r{, environment variable}
1326 This search path, followed by @code{PATH}, is used for commands executed
1327 by @code{groff}.
1329 @item GROFF_TMPDIR
1330 @tindex GROFF_TMPDIR@r{, environment variable}
1331 @tindex TMPDIR@r{, environment variable}
1332 The directory in which @code{groff} creates temporary files.  If this is
1333 not set and @env{TMPDIR} is set, temporary files are created in that
1334 directory.  Otherwise temporary files are created in a system-dependent
1335 default directory (on Unix and GNU/Linux systems, this is usually
1336 @file{/tmp}).  @code{grops}, @code{grefer}, @code{pre-grohtml}, and
1337 @code{post-grohtml} can create temporary files in this directory.
1338 @end table
1340 Note that MS-DOS and MS-Windows ports of @code{groff} use semi-colons,
1341 rather than colons, to separate the directories in the lists described
1342 above.
1345 @c =====================================================================
1347 @node Macro Directories, Font Directories, Environment, Invoking groff
1348 @section Macro Directories
1349 @cindex macro directories
1350 @cindex directories for macros
1351 @cindex searching macros
1352 @cindex macros, searching
1354 All macro file names must be named @code{@var{name}.tmac} or
1355 @code{tmac.@var{name}} to make the @option{-m@var{name}} command line
1356 option work.  The @code{mso} request doesn't have this restriction; any
1357 file name can be used, and @code{gtroff} won't try to append or prepend
1358 the @samp{tmac} string.
1360 @cindex tmac, directory
1361 @cindex directory, for tmac files
1362 @cindex tmac, path
1363 @cindex path, for tmac files
1364 @cindex searching macro files
1365 @cindex macro files, searching
1366 @cindex files, macro, searching
1367 Macro files are kept in the @dfn{tmac directories}, all of which
1368 constitute the @dfn{tmac path}.  The elements of the search path for
1369 macro files are (in that order):
1371 @itemize @bullet
1372 @item
1373 The directories specified with @code{gtroff}'s or @code{groff}'s
1374 @option{-M} command line option.
1376 @item
1377 @tindex GROFF_TMAC_PATH@r{, environment variable}
1378 The directories given in the @env{GROFF_TMAC_PATH} environment variable.
1380 @item
1381 @cindex safer mode
1382 @cindex mode, safer
1383 @cindex unsafe mode
1384 @cindex mode, unsafe
1385 @cindex current directory
1386 @cindex directory, current
1387 The current directory (only if in unsafe mode using the @option{-U}
1388 command line switch).
1390 @item
1391 @cindex home directory
1392 @cindex directory, home
1393 The home directory.
1395 @item
1396 @cindex site-specific directory
1397 @cindex directory, site-specific
1398 @cindex platform-specific directory
1399 @cindex directory, platform-specific
1400 A platform-dependent directory, a site-specific (platform-independent)
1401 directory, and the main tmac directory; the default locations are
1403 @Example
1404 /usr/local/lib/groff/site-tmac
1405 /usr/local/share/groff/site-tmac
1406 /usr/local/share/groff/1.18.2/tmac
1407 @endExample
1409 @noindent
1410 assuming that the version of @code{groff} is 1.18.2, and the
1411 installation prefix was @file{/usr/local}.  It is possible to fine-tune
1412 those directories during the installation process.
1413 @end itemize
1416 @c =====================================================================
1418 @node Font Directories, Paper Size, Macro Directories, Invoking groff
1419 @section Font Directories
1420 @cindex font directories
1421 @cindex directories for fonts
1422 @cindex searching fonts
1423 @cindex fonts, searching
1425 Basically, there is no restriction how font files for @code{groff} are
1426 named and how long font names are; however, to make the font family
1427 mechanism work (@pxref{Font Families}), fonts within a family should
1428 start with the family name, followed by the shape.  For example, the
1429 Times family uses @samp{T} for the family name and @samp{R}, @samp{B},
1430 @samp{I}, and @samp{BI} to indicate the shapes `roman', `bold',
1431 `italic', and `bold italic', respectively.  Thus the final font names
1432 are @samp{TR}, @samp{TB}, @samp{TI}, and @samp{TBI}.
1434 @cindex font path
1435 @cindex path, for font files
1436 All font files are kept in the @dfn{font directories} which constitute
1437 the @dfn{font path}.  The file search functions always append the
1438 directory @code{dev}@var{name}, where @var{name} is the name of the
1439 output device.  Assuming, say, DVI output, and @file{/foo/bar} as a font
1440 directory, the font files for @code{grodvi} must be in
1441 @file{/foo/bar/devdvi}.
1443 The elements of the search path for font files are (in that order):
1445 @itemize @bullet
1446 @item
1447 The directories specified with @code{gtroff}'s or @code{groff}'s
1448 @option{-F} command line option.  All device drivers and some
1449 preprocessors also have this option.
1451 @item
1452 @tindex GROFF_FONT_PATH@r{, environment variable}
1453 The directories given in the @env{GROFF_FONT_PATH} environment variable.
1455 @item
1456 @cindex site-specific directory
1457 @cindex directory, site-specific
1458 A site-specific directory and the main font directory; the default
1459 locations are
1461 @Example
1462 /usr/local/share/groff/site-font
1463 /usr/local/share/groff/1.18.2/font
1464 @endExample
1466 @noindent
1467 assuming that the version of @code{groff} is 1.18.2, and the
1468 installation prefix was @file{/usr/local}.  It is possible to fine-tune
1469 those directories during the installation process.
1470 @end itemize
1473 @c =====================================================================
1475 @node Paper Size, Invocation Examples, Font Directories, Invoking groff
1476 @section Paper Size
1477 @cindex paper size
1478 @cindex size, paper
1479 @cindex landscape page orientation
1480 @cindex orientation, landscape
1481 @cindex page orientation, landscape
1483 In groff, the page size for @code{gtroff} and for output devices are
1484 handled separately.  @xref{Page Layout}, for vertical manipulation of
1485 the page size.  @xref{Line Layout}, for horizontal changes.
1487 A default paper size can be set in the device's @file{DESC} file.  Most
1488 output devices also have a command line option @option{-p} to override
1489 the default paper size and option @option{-l} to use landscape
1490 orientation.  @xref{DESC File Format}, for a description of the
1491 @code{papersize} keyword which takes the same argument as @option{-p}.
1493 @pindex papersize.tmac
1494 @pindex troffrc
1495 A convenient shorthand to set a particular paper size for @code{gtroff}
1496 is command line option @option{-dpaper=@var{size}}.  This defines string
1497 @code{paper} which is processed in file @file{papersize.tmac} (loaded in
1498 the start-up file @file{troffrc} by default).  Possible values for
1499 @var{size} are the same as the predefined values for the
1500 @code{papersize} keyword (but only in lowercase) except
1501 @code{a7}-@code{d7}.  An appended @samp{l} (ell) character denotes
1502 landscape orientation.
1504 For example, use the following for PS output on A4 paper in landscape
1505 orientation:
1507 @Example
1508 groff -Tps -dpaper=a4l -P-pa4 -P-l -ms foo.ms > foo.ps
1509 @endExample
1511 Note that it is up to the particular macro package to respect default
1512 page dimensions set in this way (most do).
1515 @c =====================================================================
1517 @node Invocation Examples,  , Paper Size, Invoking groff
1518 @section Invocation Examples
1519 @cindex invocation examples
1520 @cindex examples of invocation
1522 This section lists several common uses of @code{groff} and the
1523 corresponding command lines.
1525 @Example
1526 groff file
1527 @endExample
1529 @noindent
1530 This command processes @file{file} without a macro package or a
1531 preprocessor.  The output device is the default, @samp{ps}, and the
1532 output is sent to @code{stdout}.
1534 @Example
1535 groff -t -mandoc -Tascii file | less
1536 @endExample
1538 @noindent
1539 This is basically what a call to the @code{man} program does.
1540 @code{gtroff} processes the manual page @file{file} with the
1541 @file{mandoc} macro file (which in turn either calls the @file{man} or
1542 the @file{mdoc} macro package), using the @code{tbl} preprocessor and
1543 the @acronym{ASCII} output device.  Finally, the @code{less} pager
1544 displays the result.
1546 @Example
1547 groff -X -m me file
1548 @endExample
1550 @noindent
1551 Preview @file{file} with @code{gxditview}, using the @file{me} macro
1552 package.  Since no @option{-T} option is specified, use the default
1553 device (@samp{ps}).  Note that you can either say @w{@samp{-m me}} or
1554 @w{@samp{-me}}; the latter is an anachronism from the early days of
1555 @acronym{UNIX}.@footnote{The same is true for the other main macro
1556 packages that come with @code{groff}: @file{man}, @file{mdoc},
1557 @file{ms}, @file{mm}, and @file{mandoc}.  This won't work in general;
1558 for example, to load @file{trace.tmac}, either @samp{-mtrace} or
1559 @w{@samp{-m trace}} must be used.}
1561 @Example
1562 groff -man -rD1 -z file
1563 @endExample
1565 @noindent
1566 Check @file{file} with the @file{man} macro package, forcing
1567 double-sided printing -- don't produce any output.
1569 @menu
1570 * grog::
1571 @end menu
1573 @c ---------------------------------------------------------------------
1575 @node grog,  , Invocation Examples, Invocation Examples
1576 @subsection @code{grog}
1578 @pindex grog
1579 @code{grog} reads files, guesses which of the @code{groff} preprocessors
1580 and/or macro packages are required for formatting them, and prints the
1581 @code{groff} command including those options on the standard output.  It
1582 generates one or more of the options @option{-e}, @option{-man},
1583 @option{-me}, @option{-mm}, @option{-mom}, @option{-ms}, @option{-mdoc},
1584 @option{-mdoc-old}, @option{-p}, @option{-R}, @option{-g}, @option{-G},
1585 @option{-s}, and @option{-t}.
1587 A special file name@tie{}@file{-} refers to the standard input.
1588 Specifying no files also means to read the standard input.  Any
1589 specified options are included in the printed command.  No space is
1590 allowed between options and their arguments.  The only options
1591 recognized are @option{-C} (which is also passed on) to enable
1592 compatibility mode, and @option{-v} to print the version number and
1593 exit.
1595 For example,
1597 @Example
1598 grog -Tdvi paper.ms
1599 @endExample
1601 @noindent
1602 guesses the appropriate command to print @file{paper.ms} and then prints
1603 it to the command line after adding the @option{-Tdvi} option.  For
1604 direct execution, enclose the call to @code{grog} in backquotes at the
1605 @acronym{UNIX} shell prompt:
1607 @Example
1608 `grog -Tdvi paper.ms` > paper.dvi
1609 @endExample
1611 @noindent
1612 As seen in the example, it is still necessary to redirect the output to
1613 something meaningful (i.e.@: either a file or a pager program like
1614 @code{less}).
1618 @c =====================================================================
1619 @c =====================================================================
1621 @node Tutorial for Macro Users, Macro Packages, Invoking groff, Top
1622 @chapter Tutorial for Macro Users
1623 @cindex tutorial for macro users
1624 @cindex macros, tutorial for users
1625 @cindex user's tutorial for macros
1626 @cindex user's macro tutorial
1628 Most users tend to use a macro package to format their papers.  This
1629 means that the whole breadth of @code{groff} is not necessary for most
1630 people.  This chapter covers the material needed to efficiently use a
1631 macro package.
1633 @menu
1634 * Basics::
1635 * Common Features::
1636 @end menu
1639 @c =====================================================================
1641 @node Basics, Common Features, Tutorial for Macro Users, Tutorial for Macro Users
1642 @section Basics
1643 @cindex basics of macros
1644 @cindex macro basics
1646 This section covers some of the basic concepts necessary to understand
1647 how to use a macro package.@footnote{This section is derived from
1648 @cite{Writing Papers with nroff using -me} by Eric P.@tie{}Allman.}
1649 References are made throughout to more detailed information, if desired.
1651 @code{gtroff} reads an input file prepared by the user and outputs a
1652 formatted document suitable for publication or framing.  The input
1653 consists of text, or words to be printed, and embedded commands
1654 (@dfn{requests} and @dfn{escapes}), which tell @code{gtroff} how to
1655 format the output.  For more detail on this, see @ref{Embedded
1656 Commands}.
1658 The word @dfn{argument} is used in this chapter to mean a word or number
1659 which appears on the same line as a request, and which modifies the
1660 meaning of that request.  For example, the request
1662 @Example
1664 @endExample
1666 @noindent
1667 spaces one line, but
1669 @Example
1670 .sp 4
1671 @endExample
1673 @noindent
1674 spaces four lines.  The number@tie{}4 is an argument to the @code{sp}
1675 request which says to space four lines instead of one.  Arguments are
1676 separated from the request and from each other by spaces (@emph{no}
1677 tabs).  More details on this can be found in @ref{Request and Macro
1678 Arguments}.
1680 The primary function of @code{gtroff} is to collect words from input
1681 lines, fill output lines with those words, justify the right-hand margin
1682 by inserting extra spaces in the line, and output the result.  For
1683 example, the input:
1685 @Example
1686 Now is the time
1687 for all good men
1688 to come to the aid
1689 of their party.
1690 Four score and seven
1691 years ago, etc.
1692 @endExample
1694 @noindent
1695 is read, packed onto output lines, and justified to produce:
1697 @quotation
1698 Now is the time for all good men to come to the aid of their party.
1699 Four score and seven years ago, etc.
1700 @end quotation
1702 @cindex break
1703 @cindex line break
1704 Sometimes a new output line should be started even though the current
1705 line is not yet full; for example, at the end of a paragraph.  To do
1706 this it is possible to cause a @dfn{break}, which starts a new output
1707 line.  Some requests cause a break automatically, as normally do blank
1708 input lines and input lines beginning with a space.
1710 Not all input lines are text to be formatted.  Some input lines are
1711 requests which describe how to format the text.  Requests always have a
1712 period (@samp{.}) or an apostrophe (@samp{'}) as the first character of
1713 the input line.
1715 The text formatter also does more complex things, such as automatically
1716 numbering pages, skipping over page boundaries, putting footnotes in the
1717 correct place, and so forth.
1719 Here are a few hints for preparing text for input to @code{gtroff}.
1721 @itemize @bullet
1722 @item
1723 First, keep the input lines short.  Short input lines are easier to
1724 edit, and @code{gtroff} packs words onto longer lines anyhow.
1726 @item
1727 In keeping with this, it is helpful to begin a new line after every
1728 comma or phrase, since common corrections are to add or delete sentences
1729 or phrases.
1731 @item
1732 End each sentence with two spaces -- or better, start each sentence on a
1733 new line.  @code{gtroff} recognizes characters that usually end a
1734 sentence, and inserts sentence space accordingly.
1736 @item
1737 Do not hyphenate words at the end of lines -- @code{gtroff} is smart
1738 enough to hyphenate words as needed, but is not smart enough to take
1739 hyphens out and join a word back together.  Also, words such as
1740 ``mother-in-law'' should not be broken over a line, since then a space
1741 can occur where not wanted, such as ``@w{mother- in}-law''.
1742 @end itemize
1744 @cindex double-spacing (@code{ls})
1745 @cindex spacing
1746 @code{gtroff} double-spaces output text automatically if you use the
1747 request @w{@samp{.ls 2}}.  Reactivate single-spaced mode by typing
1748 @w{@samp{.ls 1}}.@footnote{If you need finer granularity of the vertical
1749 space, use the @code{pvs} request (@pxref{Changing Type Sizes}).}
1751 A number of requests allow to change the way the output looks, sometimes
1752 called the @dfn{layout} of the output page.  Most of these requests
1753 adjust the placing of @dfn{whitespace} (blank lines or spaces).
1755 @cindex new page (@code{bp})
1756 The @code{bp} request starts a new page, causing a line break.
1758 @cindex blank line (@code{sp})
1759 @cindex empty line (@code{sp})
1760 @cindex line, empty (@code{sp})
1761 The request @w{@samp{.sp @var{N}}} leaves @var{N}@tie{}lines of blank
1762 space.  @var{N}@tie{}can be omitted (meaning skip a single line) or can
1763 be of the form @var{N}i (for @var{N}@tie{}inches) or @var{N}c (for
1764 @var{N}@tie{}centimeters).  For example, the input:
1766 @Example
1767 .sp 1.5i
1768 My thoughts on the subject
1770 @endExample
1772 @noindent
1773 leaves one and a half inches of space, followed by the line ``My
1774 thoughts on the subject'', followed by a single blank line (more
1775 measurement units are available, see @ref{Measurements}).
1777 @cindex centering lines (@code{ce})
1778 @cindex lines, centering (@code{ce})
1779 Text lines can be centered by using the @code{ce} request.  The line
1780 after @code{ce} is centered (horizontally) on the page.  To center more
1781 than one line, use @w{@samp{.ce @var{N}}} (where @var{N} is the number
1782 of lines to center), followed by the @var{N}@tie{}lines.  To center many
1783 lines without counting them, type:
1785 @Example
1786 .ce 1000
1787 lines to center
1788 .ce 0
1789 @endExample
1791 @noindent
1792 The @w{@samp{.ce 0}} request tells @code{groff} to center zero more
1793 lines, in other words, stop centering.
1795 @cindex line break (@code{br})
1796 @cindex break (@code{br})
1797 All of these requests cause a break; that is, they always start a new
1798 line.  To start a new line without performing any other action, use
1799 @code{br}.
1802 @c =====================================================================
1804 @node Common Features,  , Basics, Tutorial for Macro Users
1805 @section Common Features
1806 @cindex common features
1807 @cindex features, common
1809 @code{gtroff} provides very low-level operations for formatting a
1810 document.  There are many common routine operations which are done in
1811 all documents.  These common operations are written into @dfn{macros}
1812 and collected into a @dfn{macro package}.
1814 All macro packages provide certain common capabilities which fall into
1815 the following categories.
1817 @menu
1818 * Paragraphs::
1819 * Sections and Chapters::
1820 * Headers and Footers::
1821 * Page Layout Adjustment::
1822 * Displays::
1823 * Footnotes and Annotations::
1824 * Table of Contents::
1825 * Indices::
1826 * Paper Formats::
1827 * Multiple Columns::
1828 * Font and Size Changes::
1829 * Predefined Strings::
1830 * Preprocessor Support::
1831 * Configuration and Customization::
1832 @end menu
1834 @c ---------------------------------------------------------------------
1836 @node Paragraphs, Sections and Chapters, Common Features, Common Features
1837 @subsection Paragraphs
1838 @cindex paragraphs
1840 One of the most common and most used capability is starting a paragraph.
1841 There are a number of different types of paragraphs, any of which can be
1842 initiated with macros supplied by the macro package.  Normally,
1843 paragraphs start with a blank line and the first line indented, like the
1844 text in this manual.  There are also block style paragraphs, which omit
1845 the indentation:
1847 @Example
1848 Some   men  look   at  constitutions   with  sanctimonious
1849 reverence, and deem them like the ark of the covenant, too
1850 sacred to be touched.
1851 @endExample
1853 @noindent
1854 And there are also indented paragraphs which begin with a tag or label
1855 at the margin and the remaining text indented.
1857 @Example
1858 one   This is  the first paragraph.  Notice  how the first
1859       line of  the resulting  paragraph lines up  with the
1860       other lines in the paragraph.
1861 @endExample
1862 @Example
1863 longlabel
1864       This  paragraph   had  a  long   label.   The  first
1865       character of text on the first line does not line up
1866       with  the  text  on  second  and  subsequent  lines,
1867       although they line up with each other.
1868 @endExample
1870 A variation of this is a bulleted list.
1872 @Example
1873 .     Bulleted lists start with a bullet.   It is possible
1874       to use other glyphs instead of the bullet.  In nroff
1875       mode using the ASCII character set for output, a dot
1876       is used instead of a real bullet.
1877 @endExample
1879 @c ---------------------------------------------------------------------
1881 @node Sections and Chapters, Headers and Footers, Paragraphs, Common Features
1882 @subsection Sections and Chapters
1884 Most macro packages supply some form of section headers.  The simplest
1885 kind is simply the heading on a line by itself in bold type.  Others
1886 supply automatically numbered section heading or different heading
1887 styles at different levels.  Some, more sophisticated, macro packages
1888 supply macros for starting chapters and appendices.
1890 @c ---------------------------------------------------------------------
1892 @node Headers and Footers, Page Layout Adjustment, Sections and Chapters, Common Features
1893 @subsection Headers and Footers
1895 Every macro package gives some way to manipulate the @dfn{headers} and
1896 @dfn{footers} (also called @dfn{titles}) on each page.  This is text put
1897 at the top and bottom of each page, respectively, which contain data
1898 like the current page number, the current chapter title, and so on.  Its
1899 appearance is not affected by the running text.  Some packages allow for
1900 different ones on the even and odd pages (for material printed in a book
1901 form).
1903 The titles are called @dfn{three-part titles}, that is, there is a
1904 left-justified part, a centered part, and a right-justified part.  An
1905 automatically generated page number may be put in any of these fields
1906 with the @samp{%} character (see @ref{Page Layout}, for more details).
1908 @c ---------------------------------------------------------------------
1910 @node Page Layout Adjustment, Displays, Headers and Footers, Common Features
1911 @subsection Page Layout
1913 Most macro packages let the user specify top and bottom margins and
1914 other details about the appearance of the printed pages.
1916 @c ---------------------------------------------------------------------
1918 @node Displays, Footnotes and Annotations, Page Layout Adjustment, Common Features
1919 @subsection Displays
1920 @cindex displays
1922 @dfn{Displays} are sections of text to be set off from the body of the
1923 paper.  Major quotes, tables, and figures are types of displays, as are
1924 all the examples used in this document.
1926 @cindex quotes, major
1927 @cindex major quotes
1928 @dfn{Major quotes} are quotes which are several lines long, and hence
1929 are set in from the rest of the text without quote marks around them.
1931 @cindex list
1932 A @dfn{list} is an indented, single-spaced, unfilled display.  Lists
1933 should be used when the material to be printed should not be filled and
1934 justified like normal text, such as columns of figures or the examples
1935 used in this paper.
1937 @cindex keep
1938 A @dfn{keep} is a display of lines which are kept on a single page if
1939 possible.  An example for a keep might be a diagram.  Keeps differ from
1940 lists in that lists may be broken over a page boundary whereas keeps are
1941 not.
1943 @cindex keep, floating
1944 @cindex floating keep
1945 @dfn{Floating keeps} move relative to the text.  Hence, they are good
1946 for things which are referred to by name, such as ``See figure@tie{}3''.
1947 A floating keep appears at the bottom of the current page if it fits;
1948 otherwise, it appears at the top of the next page.  Meanwhile, the
1949 surrounding text `flows' around the keep, thus leaving no blank areas.
1951 @c ---------------------------------------------------------------------
1953 @node Footnotes and Annotations, Table of Contents, Displays, Common Features
1954 @subsection Footnotes and Annotations
1955 @cindex footnotes
1956 @cindex annotations
1958 There are a number of requests to save text for later printing.
1960 @dfn{Footnotes} are printed at the bottom of the current page.
1962 @cindex delayed text
1963 @dfn{Delayed text} is very similar to a footnote except that it is
1964 printed when called for explicitly.  This allows a list of references to
1965 appear (for example) at the end of each chapter, as is the convention in
1966 some disciplines.
1968 Most macro packages which supply this functionality also supply a means
1969 of automatically numbering either type of annotation.
1971 @c ---------------------------------------------------------------------
1973 @node Table of Contents, Indices, Footnotes and Annotations, Common Features
1974 @subsection Table of Contents
1975 @cindex table of contents
1976 @cindex contents, table of
1978 @dfn{Tables of contents} are a type of delayed text having a tag
1979 (usually the page number) attached to each entry after a row of dots.
1980 The table accumulates throughout the paper until printed, usually after
1981 the paper has ended.  Many macro packages provide the ability to have
1982 several tables of contents (e.g.@: a standard table of contents, a list
1983 of tables, etc).
1985 @c ---------------------------------------------------------------------
1987 @node Indices, Paper Formats, Table of Contents, Common Features
1988 @subsection Indices
1989 @cindex index, in macro package
1991 While some macro packages use the term @dfn{index}, none actually
1992 provide that functionality.  The facilities they call indices are
1993 actually more appropriate for tables of contents.
1995 @pindex makeindex
1996 To produce a real index in a document, external tools like the
1997 @code{makeindex} program are necessary.
1999 @c ---------------------------------------------------------------------
2001 @node Paper Formats, Multiple Columns, Indices, Common Features
2002 @subsection Paper Formats
2003 @cindex paper formats
2005 Some macro packages provide stock formats for various kinds of
2006 documents.  Many of them provide a common format for the title and
2007 opening pages of a technical paper.  The @file{mm} macros in particular
2008 provide formats for letters and memoranda.
2010 @c ---------------------------------------------------------------------
2012 @node Multiple Columns, Font and Size Changes, Paper Formats, Common Features
2013 @subsection Multiple Columns
2015 Some macro packages (but not @file{man}) provide the ability to have two
2016 or more columns on a page.
2018 @c ---------------------------------------------------------------------
2020 @node Font and Size Changes, Predefined Strings, Multiple Columns, Common Features
2021 @subsection Font and Size Changes
2023 The built-in font and size functions are not always intuitive, so all
2024 macro packages provide macros to make these operations simpler.
2026 @c ---------------------------------------------------------------------
2028 @node Predefined Strings, Preprocessor Support, Font and Size Changes, Common Features
2029 @subsection Predefined Strings
2031 Most macro packages provide various predefined strings for a variety of
2032 uses; examples are sub- and superscripts, printable dates, quotes and
2033 various special characters.
2035 @c ---------------------------------------------------------------------
2037 @node Preprocessor Support, Configuration and Customization, Predefined Strings, Common Features
2038 @subsection Preprocessor Support
2040 All macro packages provide support for various preprocessors and may
2041 extend their functionality.
2043 For example, all macro packages mark tables (which are processed with
2044 @code{gtbl}) by placing them between @code{TS} and @code{TE} macros.
2045 The @file{ms} macro package has an option, @samp{.TS@tie{}H}, that
2046 prints a caption at the top of a new page (when the table is too long to
2047 fit on a single page).
2049 @c ---------------------------------------------------------------------
2051 @node Configuration and Customization,  , Preprocessor Support, Common Features
2052 @subsection Configuration and Customization
2054 Some macro packages provide means of customizing many of the details of
2055 how the package behaves.  This ranges from setting the default type size
2056 to changing the appearance of section headers.
2060 @c =====================================================================
2061 @c =====================================================================
2063 @node Macro Packages, gtroff Reference, Tutorial for Macro Users, Top
2064 @chapter Macro Packages
2065 @cindex macro packages
2066 @cindex packages, macros
2068 This chapter documents the main macro packages that come with
2069 @code{groff}.
2071 Different main macro packages can't be used at the same time; for
2072 example
2074 @Example
2075 groff -m man foo.man -m ms bar.doc
2076 @endExample
2078 @noindent
2079 doesn't work.  Note that option arguments are processed before
2080 non-option arguments; the above (failing) sample is thus reordered to
2082 @Example
2083 groff -m man -m ms foo.man bar.doc
2084 @endExample
2086 @menu
2087 * man::
2088 * mdoc::
2089 * ms::
2090 * me::
2091 * mm::
2092 @end menu
2095 @c =====================================================================
2097 @node man, mdoc, Macro Packages, Macro Packages
2098 @section @file{man}
2099 @cindex manual pages
2100 @cindex man pages
2101 @pindex an.tmac
2102 @pindex man.tmac
2103 @pindex man-old.tmac
2105 This is the most popular and probably the most important macro package
2106 of @code{groff}.  It is easy to use, and a vast majority of manual pages
2107 are based on it.
2109 @menu
2110 * Man options::
2111 * Man usage::
2112 * Man font macros::
2113 * Miscellaneous man macros::
2114 * Predefined man strings::
2115 * Preprocessors in man pages::
2116 * Optional man extensions::
2117 @end menu
2119 @c ---------------------------------------------------------------------
2121 @node Man options, Man usage, man, man
2122 @subsection Options
2124 The command line format for using the @file{man} macros with
2125 @code{groff} is:
2127 @Example
2128 groff -m man [ -rLL=@var{length} ] [ -rLT=@var{length} ] [ -rFT=@var{dist} ]
2129       [ -rcR=1 ] [ -rC1 ] [ -rD1 ] [-rHY=@var{flags} ]
2130       [ -rP@var{nnn} ] [ -rS@var{xx} ] [ -rX@var{nnn} ]
2131       [ -rIN=@var{length} ] [ -rSN=@var{length} ] [ @var{files}@dots{} ]
2132 @endExample
2134 @noindent
2135 It is possible to use @samp{-man} instead of @w{@samp{-m man}}.
2137 @table @code
2138 @item -rcR=1
2139 This option (the default if a TTY output device is used) creates a
2140 single, very long page instead of multiple pages.  Use @code{-rcR=0} to
2141 disable it.
2143 @item -rC1
2144 If more than one manual page is given on the command line, number the
2145 pages continuously, rather than starting each at@tie{}1.
2147 @item -rD1
2148 Double-sided printing.  Footers for even and odd pages are formatted
2149 differently.
2151 @item -rFT=@var{dist}
2152 Set the position of the footer text to @var{dist}.  If positive, the
2153 distance is measured relative to the top of the page, otherwise it is
2154 relative to the bottom.  The default is @minus{}0.5@dmn{i}.
2156 @item -rHY=@var{flags}
2157 Set hyphenation flags.  Possible values are 1@tie{}to hyphenate without
2158 restrictions, 2@tie{}to not hyphenate the last word on a page, 4@tie{}to
2159 not hyphenate the last two characters of a word, and 8@tie{}to not
2160 hyphenate the first two characters of a word.  These values are
2161 additive; the default is@tie{}14.
2163 @item -rIN=@var{length}
2164 Set the body text indentation to @var{length}.  If not specified, the
2165 indentation defaults to 7@dmn{n} (7@tie{}characters) in nroff mode and
2166 7.2@dmn{n} otherwise.  For nroff, this value should always be an integer
2167 multiple of unit @samp{n} to get consistent indentation.
2169 @item -rLL=@var{length}
2170 Set line length to @var{length}.  If not specified, the line length is
2171 set to respect any value set by a prior @samp{ll} request (which
2172 @emph{must} be in effect when the @samp{TH} macro is invoked), if this
2173 differs from the built-in default for the formatter; otherwise it
2174 defaults to 78@dmn{n} in nroff mode (this is 78 characters per line) and
2175 6.5@dmn{i} in troff mode.@footnote{Note that the use of a @samp{.ll
2176 @var{length}} request to initialize the line length, prior to use of the
2177 @samp{TH} macro, is supported for backward compatibility with some
2178 versions of the @code{man} program.  @emph{Always} use the
2179 @option{-rLL=@var{length}} option, or an equivalent @samp{.nr LL
2180 @var{length}} request, in preference to such a @samp{.ll @var{length}}
2181 request.  In particular, note that in nroff mode, the request @samp{.ll
2182 65n}, (with any @var{length} expression which evaluates equal to
2183 65@dmn{n}, i.e., the formatter's default line length in nroff mode),
2184 does @emph{not} set the line length to 65@dmn{n} (it is adjusted to the
2185 @code{man} macro package's default setting of 78@dmn{n}), whereas the
2186 use of the @option{-rLL=65n} option, or the @samp{.nr LL 65n} request
2187 @emph{does} establish a line length of 65@dmn{n}.}
2189 @item -rLT=@var{length}
2190 Set title length to @var{length}.  If not specified, the title length
2191 defaults to the line length.
2193 @item -rP@var{nnn}
2194 Page numbering starts with @var{nnn} rather than with@tie{}1.
2196 @item -rS@var{xx}
2197 Use @var{xx} (which can be 10, 11, or@tie{}12@dmn{pt}) as the base
2198 document font size instead of the default value of@tie{}10@dmn{pt}.
2200 @item -rSN=@var{length}
2201 Set the indentation for sub-subheadings to @var{length}.  If not
2202 specified, the indentation defaults to 3@dmn{n}.
2204 @item -rX@var{nnn}
2205 After page @var{nnn}, number pages as @var{nnn}a, @var{nnn}b,
2206 @var{nnn}c, etc.  For example, the option @option{-rX2} produces the
2207 following page numbers: 1, 2, 2a, 2b, 2c, etc.
2208 @end table
2210 @c ---------------------------------------------------------------------
2212 @node Man usage, Man font macros, Man options, man
2213 @subsection Usage
2214 @cindex @code{man} macros
2215 @cindex macros for manual pages [@code{man}]
2217 @pindex man.local
2218 This section describes the available macros for manual pages.  For
2219 further customization, put additional macros and requests into the file
2220 @file{man.local} which is loaded immediately after the @file{man}
2221 package.
2223 @Defmac {TH, title section [@Var{extra1} [@Var{extra2} [@Var{extra3}]]], man}
2224 Set the title of the man page to @var{title} and the section to
2225 @var{section}, which must have a value between 1 and@tie{}8.  The value
2226 of @var{section} may also have a string appended, e.g.@: @samp{.pm}, to
2227 indicate a specific subsection of the man pages.
2229 Both @var{title} and @var{section} are positioned at the left and right
2230 in the header line (with @var{section} in parentheses immediately
2231 appended to @var{title}.  @var{extra1} is positioned in the middle of
2232 the footer line.  @var{extra2} is positioned at the left in the footer
2233 line (or at the left on even pages and at the right on odd pages if
2234 double-sided printing is active).  @var{extra3} is centered in the
2235 header line.
2237 For @acronym{HTML} and @acronym{XHTML} output, headers and footers are
2238 completely suppressed.
2240 Additionally, this macro starts a new page; the new line number
2241 is@tie{}1 again (except if the @option{-rC1} option is given on the
2242 command line) -- this feature is intended only for formatting multiple
2243 man pages; a single man page should contain exactly one @code{TH} macro
2244 at the beginning of the file.
2245 @endDefmac
2247 @Defmac {SH, [@Var{heading}], man}
2248 Set up an unnumbered section heading sticking out to the left.  Prints
2249 out all the text following @code{SH} up to the end of the line (or the
2250 text in the next line if there is no argument to @code{SH}) in bold face
2251 (or the font specified by the string @code{HF}), one size larger than
2252 the base document size.  Additionally, the left margin and the
2253 indentation for the following text is reset to its default value.
2254 @endDefmac
2256 @Defmac {SS, [@Var{heading}], man}
2257 Set up an unnumbered (sub)section heading.  Prints out all the text
2258 following @code{SS} up to the end of the line (or the text in the next
2259 line if there is no argument to @code{SS}) in bold face (or the font
2260 specified by the string @code{HF}), at the same size as the base
2261 document size.  Additionally, the left margin and the indentation for
2262 the following text is reset to its default value.
2263 @endDefmac
2265 @Defmac {TP, [@Var{nnn}], man}
2266 Set up an indented paragraph with label.  The indentation is set to
2267 @var{nnn} if that argument is supplied (the default unit is @samp{n} if
2268 omitted), otherwise it is set to the previous indentation value
2269 specified with @code{TP}, @code{IP}, or @code{HP} (or to the default
2270 value if none of them have been used yet).
2272 The first line of text following this macro is interpreted as a string
2273 to be printed flush-left, as it is appropriate for a label.  It is not
2274 interpreted as part of a paragraph, so there is no attempt to fill the
2275 first line with text from the following input lines.  Nevertheless, if
2276 the label is not as wide as the indentation the paragraph starts at the
2277 same line (but indented), continuing on the following lines.  If the
2278 label is wider than the indentation the descriptive part of the
2279 paragraph begins on the line following the label, entirely indented.
2280 Note that neither font shape nor font size of the label is set to a
2281 default value; on the other hand, the rest of the text has default font
2282 settings.
2283 @endDefmac
2285 @DefmacList {LP, , man}
2286 @DefmacItem {PP, , man}
2287 @DefmacListEnd {P, , man}
2288 These macros are mutual aliases.  Any of them causes a line break at the
2289 current position, followed by a vertical space downwards by the amount
2290 specified by the @code{PD} macro.  The font size and shape are reset to
2291 the default value (10@dmn{pt} roman if no @option{-rS} option is given
2292 on the command line).  Finally, the current left margin and the
2293 indentation is restored.
2294 @endDefmac
2296 @Defmac {IP, [@Var{designator} [@Var{nnn}]], man}
2297 Set up an indented paragraph, using @var{designator} as a tag to mark
2298 its beginning.  The indentation is set to @var{nnn} if that argument is
2299 supplied (default unit is @samp{n}), otherwise it is set to the previous
2300 indentation value specified with @code{TP}, @code{IP}, or @code{HP} (or
2301 the default value if none of them have been used yet).  Font size and
2302 face of the paragraph (but not the designator) are reset to their
2303 default values.
2305 To start an indented paragraph with a particular indentation but without
2306 a designator, use @samp{""} (two double quotes) as the first argument of
2307 @code{IP}.
2309 For example, to start a paragraph with bullets as the designator and
2310 4@tie{}en indentation, write
2312 @Example
2313 .IP \(bu 4
2314 @endExample
2315 @endDefmac
2317 @Defmac {HP, [@Var{nnn}], man}
2318 @cindex hanging indentation [@code{man}]
2319 @cindex @code{man} macros, hanging indentation
2320 Set up a paragraph with hanging left indentation.  The indentation is
2321 set to @var{nnn} if that argument is supplied (default unit is
2322 @samp{n}), otherwise it is set to the previous indentation value
2323 specified with @code{TP}, @code{IP}, or @code{HP} (or the default value
2324 if non of them have been used yet).  Font size and face are reset to
2325 their default values.
2326 @endDefmac
2328 @Defmac {RS, [@Var{nnn}], man}
2329 @cindex left margin, how to move [@code{man}]
2330 @cindex @code{man} macros, moving left margin
2331 Move the left margin to the right by the value @var{nnn} if specified
2332 (default unit is @samp{n}); otherwise it is set to the previous
2333 indentation value specified with @code{TP}, @code{IP}, or @code{HP} (or
2334 to the default value if none of them have been used yet).  The
2335 indentation value is then set to the default.
2337 Calls to the @code{RS} macro can be nested.
2338 @endDefmac
2340 @Defmac {RE, [@Var{nnn}], man}
2341 Move the left margin back to level @var{nnn}, restoring the previous
2342 left margin.  If no argument is given, it moves one level back.  The
2343 first level (i.e., no call to @code{RS} yet) has number@tie{}1, and each
2344 call to @code{RS} increases the level by@tie{}1.
2345 @endDefmac
2347 @cindex line breaks, with vertical space [@code{man}]
2348 @cindex @code{man} macros, line breaks with vertical space
2349 To summarize, the following macros cause a line break with the insertion
2350 of vertical space (which amount can be changed with the @code{PD}
2351 macro): @code{SH}, @code{SS}, @code{TP}, @code{LP} (@code{PP},
2352 @code{P}), @code{IP}, and @code{HP}.
2354 @cindex line breaks, without vertical space [@code{man}]
2355 @cindex @code{man} macros, line breaks without vertical space
2356 The macros @code{RS} and @code{RE} also cause a break but do not insert
2357 vertical space.
2359 @cindex default indentation, resetting [@code{man}]
2360 @cindex indentaion, resetting to default [@code{man}]
2361 @cindex @code{man} macros, resetting default indentation
2362 Finally, the macros @code{SH}, @code{SS}, @code{LP} (@code{PP},
2363 @code{P}), and @code{RS} reset the indentation to its default value.
2365 @c ---------------------------------------------------------------------
2367 @node Man font macros, Miscellaneous man macros, Man usage, man
2368 @subsection Macros to set fonts
2369 @cindex font selection [@code{man}]
2370 @cindex @code{man} macros, how to set fonts
2372 The standard font is roman; the default text size is 10@tie{}point.  If
2373 command line option @option{-rS=@var{n}} is given, use @var{n}@dmn{pt}
2374 as the default text size.
2376 @Defmac {SM, [@Var{text}], man}
2377 Set the text on the same line or the text on the next line in a font
2378 that is one point size smaller than the default font.
2379 @endDefmac
2381 @Defmac {SB, [@Var{text}], man}
2382 @cindex bold face [@code{man}]
2383 @cindex @code{man} macros, bold face
2384 Set the text on the same line or the text on the next line in bold face
2385 font, one point size smaller than the default font.
2386 @endDefmac
2388 @Defmac {BI, text, man}
2389 Set its arguments alternately in bold face and italic, without a space
2390 between the arguments.  Thus,
2392 @Example
2393 .BI this "word and" that
2394 @endExample
2396 @noindent
2397 produces ``thisword andthat'' with ``this'' and ``that'' in bold face,
2398 and ``word and'' in italics.
2399 @endDefmac
2401 @Defmac {IB, text, man}
2402 Set its arguments alternately in italic and bold face, without a space
2403 between the arguments.
2404 @endDefmac
2406 @Defmac {RI, text, man}
2407 Set its arguments alternately in roman and italic, without a space
2408 between the arguments.
2409 @endDefmac
2411 @Defmac {IR, text, man}
2412 Set its arguments alternately in italic and roman, without a space
2413 between the arguments.
2414 @endDefmac
2416 @Defmac {BR, text, man}
2417 Set its arguments alternately in bold face and roman, without a space
2418 between the arguments.
2419 @endDefmac
2421 @Defmac {RB, text, man}
2422 Set its arguments alternately in roman and bold face, without a space
2423 between the arguments.
2424 @endDefmac
2426 @Defmac {B, [@Var{text}], man}
2427 Set @var{text} in bold face.  If no text is present on the line where
2428 the macro is called, then the text of the next line appears in bold
2429 face.
2430 @endDefmac
2432 @Defmac {I, [@Var{text}], man}
2433 @cindex italic fonts [@code{man}]
2434 @cindex @code{man} macros, italic fonts
2435 Set @var{text} in italic.  If no text is present on the line where the
2436 macro is called, then the text of the next line appears in italic.
2437 @endDefmac
2439 @c ---------------------------------------------------------------------
2441 @node Miscellaneous man macros, Predefined man strings, Man font macros, man
2442 @subsection Miscellaneous macros
2444 @pindex grohtml
2445 @cindex @code{man} macros, default indentation
2446 @cindex default indentation [@code{man}]
2447 The default indentation is 7.2@dmn{n} in troff mode and 7@dmn{n} in
2448 nroff mode except for @code{grohtml} which ignores indentation.
2450 @Defmac {DT, , man}
2451 @cindex tab stops [@code{man}]
2452 @cindex @code{man} macros, tab stops
2453 Set tabs every 0.5@tie{}inches.  Since this macro is always executed
2454 during a call to the @code{TH} macro, it makes sense to call it only if
2455 the tab positions have been changed.
2456 @endDefmac
2458 @Defmac {PD, [@Var{nnn}], man}
2459 @cindex empty space before a paragraph [@code{man}]
2460 @cindex @code{man} macros, empty space before a paragraph
2461 Adjust the empty space before a new paragraph (or section).  The
2462 optional argument gives the amount of space (default unit is @samp{v});
2463 without parameter, the value is reset to its default value (1@tie{}line
2464 in nroff mode, 0.4@dmn{v}@tie{}otherwise).
2466 This affects the macros @code{SH}, @code{SS}, @code{TP}, @code{LP} (as
2467 well as @code{PP} and @code{P}), @code{IP}, and @code{HP}.
2468 @endDefmac
2470 The following two macros are included for BSD compatibility.
2472 @Defmac {AT, [@Var{system} [@Var{release}]], man}
2473 @cindex @code{man}macros, BSD compatibility
2474 Alter the footer for use with @acronym{AT&T} manpages.  This command
2475 exists only for compatibility; don't use it.  The first argument
2476 @var{system} can be:
2478 @table @code
2479 @item 3
2480 7th Edition (the default)
2482 @item 4
2483 System III
2485 @item 5
2486 System V
2487 @end table
2489 An optional second argument @var{release} to @code{AT} specifies the
2490 release number (such as ``System V Release 3'').
2491 @endDefmac
2493 @Defmac {UC, [@Var{version}], man}
2494 @cindex @code{man}macros, BSD compatibility
2495 Alters the footer for use with @acronym{BSD} manpages.  This command
2496 exists only for compatibility; don't use it.  The argument can be:
2498 @table @code
2499 @item 3
2500 3rd Berkeley Distribution (the default)
2502 @item 4
2503 4th Berkeley Distribution
2505 @item 5
2506 4.2 Berkeley Distribution
2508 @item 6
2509 4.3 Berkeley Distribution
2511 @item 7
2512 4.4 Berkeley Distribution
2513 @end table
2514 @endDefmac
2516 @c ---------------------------------------------------------------------
2518 @node Predefined man strings, Preprocessors in man pages, Miscellaneous man macros, man
2519 @subsection Predefined strings
2521 The following strings are defined:
2523 @Defstr {S, man}
2524 Switch back to the default font size.
2525 @endDefstr
2527 @Defstr {HF, man}
2528 The typeface used for headings.
2529 The default is @samp{B}.
2530 @endDefstr
2532 @Defstr {R, man}
2533 The `registered' sign.
2534 @endDefstr
2536 @Defstr {Tm, man}
2537 The `trademark' sign.
2538 @endDefstr
2540 @DefstrList {lq, man}
2541 @DefstrListEnd {rq, man}
2542 @cindex @code{lq} glyph, and @code{lq} string [@code{man}]
2543 @cindex @code{rq} glyph, and @code{rq} string [@code{man}]
2544 Left and right quote.  This is equal to @code{\(lq} and @code{\(rq},
2545 respectively.
2546 @endDefstr
2548 @c ---------------------------------------------------------------------
2550 @node Preprocessors in man pages, Optional man extensions, Predefined man strings, man
2551 @subsection Preprocessors in @file{man} pages
2553 @cindex preprocessor, calling convention
2554 @cindex calling convention of preprocessors
2555 If a preprocessor like @code{gtbl} or @code{geqn} is needed, it has
2556 become common usage to make the first line of the man page look like
2557 this:
2559 @Example
2560 '\" @var{word}
2561 @endExample
2563 @pindex geqn@r{, invocation in manual pages}
2564 @pindex grefer@r{, invocation in manual pages}
2565 @pindex gtbl@r{, invocation in manual pages}
2566 @pindex man@r{, invocation of preprocessors}
2567 @noindent
2568 Note the single space character after the double quote.  @var{word}
2569 consists of letters for the needed preprocessors: @samp{e} for
2570 @code{geqn}, @samp{r} for @code{grefer}, @samp{t} for @code{gtbl}.
2571 Modern implementations of the @code{man} program read this first line
2572 and automatically call the right preprocessor(s).
2574 @c ---------------------------------------------------------------------
2576 @node Optional man extensions,  , Preprocessors in man pages, man
2577 @subsection Optional @file{man} extensions
2579 @pindex man.local
2580 Use the file @file{man.local} for local extensions to the @code{man}
2581 macros or for style changes.
2583 @unnumberedsubsubsec Custom headers and footers
2584 @cindex @code{man} macros, custom headers and footers
2586 In groff versions 1.18.2 and later, you can specify custom headers and
2587 footers by redefining the following macros in @file{man.local}.
2589 @Defmac {PT, , man}
2590 Control the content of the headers.  Normally, the header prints the
2591 command name and section number on either side, and the optional fifth
2592 argument to @code{TH} in the center.
2593 @endDefmac
2595 @Defmac {BT, , man}
2596 Control the content of the footers.  Normally, the footer prints the
2597 page number and the third and fourth arguments to @code{TH}.
2599 Use the @code{FT} number register to specify the footer position.  The
2600 default is @minus{}0.5@dmn{i}.
2601 @endDefmac
2603 @unnumberedsubsubsec Ultrix-specific man macros
2604 @cindex Ultrix-specific @code{man} macros
2605 @cindex @code{man} macros, Ultrix-specific
2607 @pindex man.ultrix
2608 The @code{groff} source distribution includes a file named
2609 @file{man.ultrix}, containing macros compatible with the Ultrix variant
2610 of @code{man}.  Copy this file into @file{man.local} (or use the
2611 @code{mso} request to load it) to enable the following macros.
2613 @Defmac {CT, @Var{key}, man}
2614 Print @samp{<CTRL/@var{key}>}.
2615 @endDefmac
2617 @Defmac {CW, , man}
2618 Print subsequent text using the constant width (Courier) typeface.
2619 @endDefmac
2621 @Defmac {Ds, , man}
2622 Begin a non-filled display.
2623 @endDefmac
2625 @Defmac {De, , man}
2626 End a non-filled display started with @code{Ds}.
2627 @endDefmac
2629 @Defmac {EX, [@Var{indent}], man}
2630 Begin a non-filled display using the constant width (Courier) typeface.
2631 Use the optional @var{indent} argument to indent the display.
2632 @endDefmac
2634 @Defmac {EE, , man}
2635 End a non-filled display started with @code{EX}.
2636 @endDefmac
2638 @Defmac {G, [@Var{text}], man}
2639 Set @var{text} in Helvetica.  If no text is present on the line where
2640 the macro is called, then the text of the next line appears in
2641 Helvetica.
2642 @endDefmac
2644 @Defmac {GL, [@Var{text}], man}
2645 Set @var{text} in Helvetica Oblique.  If no text is present on the line
2646 where the macro is called, then the text of the next line appears in
2647 Helvetica Oblique.
2648 @endDefmac
2650 @Defmac {HB, [@Var{text}], man}
2651 Set @var{text} in Helvetica Bold.  If no text is present on the line
2652 where the macro is called, then all text up to the next @code{HB}
2653 appears in Helvetica Bold.
2654 @endDefmac
2656 @Defmac {TB, [@Var{text}], man}
2657 Identical to @code{HB}.
2658 @endDefmac
2660 @Defmac {MS, @Var{title} @Var{sect} [@Var{punct}], man}
2661 Set a manpage reference in Ultrix format.  The @var{title} is in Courier
2662 instead of italic.  Optional punctuation follows the section number
2663 without an intervening space.
2664 @endDefmac
2666 @Defmac {NT, [@code{C}] [@Var{title}], man}
2667 Begin a note.  Print the optional @Var{title}, or the word ``Note'',
2668 centered on the page.  Text following the macro makes up the body of the
2669 note, and is indented on both sides.  If the first argument is @code{C},
2670 the body of the note is printed centered (the second argument replaces
2671 the word ``Note'' if specified).
2672 @endDefmac
2674 @Defmac {NE, , man}
2675 End a note begun with @code{NT}.
2676 @endDefmac
2678 @Defmac {PN, @Var{path} [@Var{punct}], man}
2679 Set the path name in constant width (Courier), followed by optional
2680 punctuation.
2681 @endDefmac
2683 @Defmac {Pn, [@Var{punct}] @Var{path} [@Var{punct}], man}
2684 If called with two arguments, identical to @code{PN}.  If called with
2685 three arguments, set the second argument in constant width (Courier),
2686 bracketed by the first and third arguments in the current font.
2687 @endDefmac
2689 @Defmac {R, , man}
2690 Switch to roman font and turn off any underlining in effect.
2691 @endDefmac
2693 @Defmac {RN, , man}
2694 Print the string @samp{<RETURN>}.
2695 @endDefmac
2697 @Defmac {VS, [@code{4}], man}
2698 Start printing a change bar in the margin if the number@tie{}@code{4} is
2699 specified.  Otherwise, this macro does nothing.
2700 @endDefmac
2702 @Defmac {VE, , man}
2703 End printing the change bar begun by @code{VS}.
2704 @endDefmac
2706 @unnumberedsubsubsec Simple example
2708 The following example @file{man.local} file alters the @code{SH} macro
2709 to add some extra vertical space before printing the heading.  Headings
2710 are printed in Helvetica Bold.
2712 @Example
2713 .\" Make the heading fonts Helvetica
2714 .ds HF HB
2716 .\" Put more whitespace in front of headings.
2717 .rn SH SH-orig
2718 .de SH
2719 .  if t .sp (u;\\n[PD]*2)
2720 .  SH-orig \\$*
2722 @endExample
2725 @c =====================================================================
2727 @node mdoc, ms, man, Macro Packages
2728 @section @file{mdoc}
2729 @cindex @code{mdoc} macros
2731 @c XXX documentation
2732 @c XXX this is a placeholder until we get stuff knocked into shape
2733 See the @cite{groff_mdoc(7)} man page (type @command{man groff_mdoc}
2734 at the command line).
2737 @c =====================================================================
2739 @node ms, me, mdoc, Macro Packages
2740 @section @file{ms}
2741 @cindex @code{ms} macros
2743 The @file{-ms} macros are suitable for reports, letters, books, user
2744 manuals, and so forth.  The package provides macros for cover pages,
2745 section headings, paragraphs, lists, footnotes, pagination, and a table
2746 of contents.
2748 @menu
2749 * ms Intro::
2750 * General ms Structure::
2751 * ms Document Control Registers::
2752 * ms Cover Page Macros::
2753 * ms Body Text::
2754 * ms Page Layout::
2755 * Differences from AT&T ms::
2756 * Naming Conventions::
2757 @end menu
2759 @c ---------------------------------------------------------------------
2761 @node ms Intro, General ms Structure, ms, ms
2762 @subsection Introduction to @file{ms}
2764 The original @file{-ms} macros were included with @acronym{AT&T}
2765 @code{troff} as well as the @file{man} macros.  While the @file{man}
2766 package is intended for brief documents that can be read on-line as well
2767 as printed, the @file{ms} macros are suitable for longer documents that
2768 are meant to be printed rather than read on-line.
2770 The @file{ms} macro package included with @code{groff} is a complete,
2771 bottom-up re-implementation.  Several macros (specific to @acronym{AT&T}
2772 or Berkeley) are not included, while several new commands are.
2773 @xref{Differences from AT&T ms}, for more information.
2775 @c ---------------------------------------------------------------------
2777 @node General ms Structure, ms Document Control Registers, ms Intro, ms
2778 @subsection General structure of an @file{ms} document
2779 @cindex @code{ms} macros, general structure
2781 The @file{ms} macro package expects a certain amount of structure, but
2782 not as much as packages such as @file{man} or @file{mdoc}.
2784 The simplest documents can begin with a paragraph macro (such as
2785 @code{LP} or @code{PP}), and consist of text separated by paragraph
2786 macros or even blank lines.  Longer documents have a structure as
2787 follows:
2789 @table @strong
2790 @item Document type
2791 If you invoke the @code{RP} (report) macro on the first line of the
2792 document, @code{groff} prints the cover page information on its own
2793 page; otherwise it prints the information on the first page with your
2794 document text immediately following.  Other document formats found in
2795 @acronym{AT&T} @code{troff} are specific to @acronym{AT&T} or Berkeley,
2796 and are not supported in @code{groff}.
2798 @item Format and layout
2799 By setting number registers, you can change your document's type (font
2800 and size), margins, spacing, headers and footers, and footnotes.
2801 @xref{ms Document Control Registers}, for more details.
2803 @item Cover page
2804 A cover page consists of a title, the author's name and institution, an
2805 abstract, and the date.@footnote{Actually, only the title is required.}
2806 @xref{ms Cover Page Macros}, for more details.
2808 @item Body
2809 Following the cover page is your document.  You can use the @file{ms}
2810 macros to write reports, letters, books, and so forth.  The package is
2811 designed for structured documents, consisting of paragraphs interspersed
2812 with headings and augmented by lists, footnotes, tables, and other
2813 common constructs.  @xref{ms Body Text}, for more details.
2815 @item Table of contents
2816 Longer documents usually include a table of contents, which you can
2817 invoke by placing the @code{TC} macro at the end of your document.  The
2818 @file{ms} macros have minimal indexing facilities, consisting of the
2819 @code{IX} macro, which prints an entry on standard error.  Printing the
2820 table of contents at the end is necessary since @code{groff} is a
2821 single-pass text formatter, thus it cannot determine the page number of
2822 each section until that section has actually been set and printed.
2823 Since @file{ms} output is intended for hardcopy, you can manually
2824 relocate the pages containing the table of contents between the cover
2825 page and the body text after printing.
2826 @end table
2828 @c ---------------------------------------------------------------------
2830 @node ms Document Control Registers, ms Cover Page Macros, General ms Structure, ms
2831 @subsection Document control registers
2832 @cindex @code{ms} macros, document control registers
2834 The following is a list of document control number registers.  For the
2835 sake of consistency, set registers related to margins at the beginning
2836 of your document, or just after the @code{RP} macro.  You can set other
2837 registers later in your document, but you should keep them together at
2838 the beginning to make them easy to find and edit as necessary.
2840 @unnumberedsubsubsec Margin Settings
2842 @Defmpreg {PO, ms}
2843 Defines the page offset (i.e., the left margin).  There is no explicit
2844 right margin setting; the combination of the @code{PO} and @code{LL}
2845 registers implicitly define the right margin width.
2847 Effective: next page.
2849 Default value: 1@dmn{i}.
2850 @endDefmpreg
2852 @Defmpreg {LL, ms}
2853 Defines the line length (i.e., the width of the body text).
2855 Effective: next paragraph.
2857 Default: 6@dmn{i}.
2858 @endDefmpreg
2860 @Defmpreg {LT, ms}
2861 Defines the title length (i.e., the header and footer width).  This
2862 is usually the same as @code{LL}, but not necessarily.
2864 Effective: next paragraph.
2866 Default: 6@dmn{i}.
2867 @endDefmpreg
2869 @Defmpreg {HM, ms}
2870 Defines the header margin height at the top of the page.
2872 Effective: next page.
2874 Default: 1@dmn{i}.
2875 @endDefmpreg
2877 @Defmpreg {FM, ms}
2878 Defines the footer margin height at the bottom of the page.
2880 Effective: next page.
2882 Default: 1@dmn{i}.
2883 @endDefmpreg
2885 @unnumberedsubsubsec Text Settings
2887 @Defmpreg {PS, ms}
2888 Defines the point size of the body text.  If the value is larger than or
2889 equal to 1000, divide it by 1000 to get a fractional point size.  For
2890 example, @samp{.nr PS 10250} sets the document's point size to
2891 10.25@dmn{p}.
2893 Effective: next paragraph.
2895 Default: 10@dmn{p}.
2896 @endDefmpreg
2898 @Defmpreg {VS, ms}
2899 Defines the space between lines (line height plus leading).  If the
2900 value is larger than or equal to 1000, divide it by 1000 to get a
2901 fractional point size.  Due to backwards compatibility, @code{VS} must
2902 be smaller than 40000 (this is 40.0@dmn{p}).
2904 Effective: next paragraph.
2906 Default: 12@dmn{p}.
2907 @endDefmpreg
2909 @Defmpreg {PSINCR, ms}
2910 Defines an increment in point size, which is applied to section headings
2911 at nesting levels below the value specified in @code{GROWPS}.  The value
2912 of @code{PSINCR} should be specified in points, with the @dmn{p} scaling
2913 factor, and may include a fractional component; for example,
2914 @w{@samp{.nr PSINCR 1.5p}} sets a point size increment of 1.5@dmn{p}.
2916 Effective: next section heading.
2918 Default: 1@dmn{p}.
2919 @endDefmpreg
2921 @Defmpreg {GROWPS, ms}
2922 Defines the heading level below which the point size increment set by
2923 @code{PSINCR} becomes effective.  Section headings at and above the
2924 level specified by @code{GROWPS} are printed at the point size set by
2925 @code{PS}; for each level below the value of @code{GROWPS}, the point
2926 size is increased in steps equal to the value of @code{PSINCR}.  Setting
2927 @code{GROWPS} to any value less than@tie{}2 disables the incremental
2928 heading size feature.
2930 Effective: next section heading.
2932 Default: 0.
2933 @endDefmpreg
2935 @Defmpreg {HY, ms}
2936 Defines the hyphenation level.  @code{HY} sets safely the value of the
2937 low-level @code{hy} register.  Setting the value of @code{HY} to@tie{}0
2938 is equivalent to using the @code{nh} request.
2940 Effective: next paragraph.
2942 Default: 14.
2943 @endDefmpreg
2945 @Defmpreg {FAM, ms}
2946 Defines the font family used to typeset the document.
2948 Effective: next paragraph.
2950 Default: as defined in the output device.
2951 @endDefmpreg
2953 @unnumberedsubsubsec Paragraph Settings
2955 @Defmpreg {PI, ms}
2956 Defines the initial indentation of a (@code{PP} macro) paragraph.
2958 Effective: next paragraph.
2960 Default: 5@dmn{n}.
2961 @endDefmpreg
2963 @Defmpreg {PD, ms}
2964 Defines the space between paragraphs.
2966 Effective: next paragraph.
2968 Default: 0.3@dmn{v}.
2969 @endDefmpreg
2971 @Defmpreg {QI, ms}
2972 Defines the indentation on both sides of a quoted (@code{QP} macro)
2973 paragraph.
2975 Effective: next paragraph.
2977 Default: 5@dmn{n}.
2978 @endDefmpreg
2980 @Defmpreg {PORPHANS, ms}
2981 Defines the minimum number of initial lines of any paragraph which
2982 should be kept together, to avoid orphan lines at the bottom of a page.
2983 If a new paragraph is started close to the bottom of a page, and there
2984 is insufficient space to accommodate @code{PORPHANS} lines before an
2985 automatic page break, then the page break is forced, before the start of
2986 the paragraph.
2988 Effective: next paragraph.
2990 Default: 1.
2991 @endDefmpreg
2993 @Defmpreg {HORPHANS, ms}
2994 Defines the minimum number of lines of the following paragraph which
2995 should be kept together with any section heading introduced by the
2996 @code{NH} or @code{SH} macros.  If a section heading is placed close to
2997 the bottom of a page, and there is insufficient space to accommodate
2998 both the heading and at least @code{HORPHANS} lines of the following
2999 paragraph, before an automatic page break, then the page break is forced
3000 before the heading.
3002 Effective: next paragraph.
3004 Default: 1.
3005 @endDefmpreg
3007 @unnumberedsubsubsec Footnote Settings
3009 @Defmpreg {FL, ms}
3010 Defines the length of a footnote.
3012 Effective: next footnote.
3014 Default: @math{@code{@\n[LL]} * 5 / 6}.
3015 @endDefmpreg
3017 @Defmpreg {FI, ms}
3018 Defines the footnote indentation.
3020 Effective: next footnote.
3022 Default: 2@dmn{n}.
3023 @endDefmpreg
3025 @Defmpreg {FF, ms}
3026 The footnote format:
3027 @table @code
3028 @item 0
3029 Print the footnote number as a superscript; indent the footnote
3030 (default).
3032 @item 1
3033 Print the number followed by a period (like 1.@:) and indent the
3034 footnote.
3036 @item 2
3037 Like 1, without an indentation.
3039 @item 3
3040 Like 1, but print the footnote number as a hanging paragraph.
3041 @end table
3043 Effective: next footnote.
3045 Default: 0.
3046 @endDefmpreg
3048 @Defmpreg {FPS, ms}
3049 Defines the footnote point size.  If the value is larger than or equal
3050 to 1000, divide it by 1000 to get a fractional point size.
3052 Effective: next footnote.
3054 Default: @math{@code{@\n[PS]} - 2}.
3055 @endDefmpreg
3057 @Defmpreg {FVS, ms}
3058 Defines the footnote vertical spacing.  If the value is larger than or
3059 equal to 1000, divide it by 1000 to get a fractional point size.
3061 Effective: next footnote.
3063 Default: @math{@code{@\n[FPS]} + 2}.
3064 @endDefmpreg
3066 @Defmpreg {FPD, ms}
3067 Defines the footnote paragraph spacing.
3069 Effective: next footnote.
3071 Default: @math{@code{@\n[PD]} / 2}.
3072 @endDefmpreg
3074 @unnumberedsubsubsec Miscellaneous Number Registers
3076 @Defmpreg {MINGW, ms}
3077 Defines the minimum width between columns in a multi-column document.
3079 Effective: next page.
3081 Default: 2@dmn{n}.
3082 @endDefmpreg
3084 @c ---------------------------------------------------------------------
3086 @node ms Cover Page Macros, ms Body Text, ms Document Control Registers, ms
3087 @subsection Cover page macros
3088 @cindex @code{ms} macros, cover page
3089 @cindex cover page macros, [@code{ms}]
3091 Use the following macros to create a cover page for your document in the
3092 order shown.
3094 @Defmac {RP, [@code{no}], ms}
3095 Specifies the report format for your document.  The report format
3096 creates a separate cover page.  The default action (no @code{RP} macro)
3097 is to print a subset of the cover page on page@tie{}1 of your document.
3099 If you use the word @code{no} as an optional argument, @code{groff}
3100 prints a title page but does not repeat any of the title page
3101 information (title, author, abstract, etc.@:) on page@tie{}1 of the
3102 document.
3103 @endDefmac
3105 @Defmac {P1, , ms}
3106 (P-one) Prints the header on page@tie{}1.  The default is to suppress
3107 the header.
3108 @endDefmac
3110 @Defmac {DA, [@dots{}], ms}
3111 (optional) Prints the current date, or the arguments to the macro if
3112 any, on the title page (if specified) and in the footers.  This is the
3113 default for @code{nroff}.
3114 @endDefmac
3116 @Defmac {ND, [@dots{}], ms}
3117 (optional) Prints the current date, or the arguments to the macro if
3118 any, on the title page (if specified) but not in the footers.  This is
3119 the default for @code{troff}.
3120 @endDefmac
3122 @Defmac {TL, , ms}
3123 Specifies the document title.  @code{groff} collects text following the
3124 @code{TL} macro into the title, until reaching the author name or
3125 abstract.
3126 @endDefmac
3128 @Defmac {AU, , ms}
3129 Specifies the author's name, which appears on the line (or lines)
3130 immediately following.  You can specify multiple authors as follows:
3132 @Example
3134 John Doe
3136 University of West Bumblefuzz
3138 Martha Buck
3140 Monolithic Corporation
3143 @endExample
3144 @endDefmac
3146 @Defmac {AI, , ms}
3147 Specifies the author's institution.  You can specify multiple
3148 institutions in the same way that you specify multiple authors.
3149 @endDefmac
3151 @Defmac {AB, [@code{no}], ms}
3152 Begins the abstract.  The default is to print the word
3153 @acronym{ABSTRACT}, centered and in italics, above the text of the
3154 abstract.  The word @code{no} as an optional argument suppresses this
3155 heading.
3156 @endDefmac
3158 @Defmac {AE, , ms}
3159 Ends the abstract.
3160 @endDefmac
3162 The following is example mark-up for a title page.
3163 @cindex title page, example markup
3164 @cindex example markup, title page
3166 @Example
3167 @cartouche
3170 The Inevitability of Code Bloat
3171 in Commercial and Free Software
3173 J. Random Luser
3175 University of West Bumblefuzz
3177 This report examines the long-term growth
3178 of the code bases in two large, popular software
3179 packages; the free Emacs and the commercial
3180 Microsoft Word.
3181 While differences appear in the type or order
3182 of features added, due to the different
3183 methodologies used, the results are the same
3184 in the end.
3186 The free software approach is shown to be
3187 superior in that while free software can
3188 become as bloated as commercial offerings,
3189 free software tends to have fewer serious
3190 bugs and the added features are in line with
3191 user demand.
3194 ... the rest of the paper follows ...
3195 @end cartouche
3196 @endExample
3198 @c ---------------------------------------------------------------------
3200 @node ms Body Text, ms Page Layout, ms Cover Page Macros, ms
3201 @subsection Body text
3202 @cindex @code{ms} macros, body text
3204 This section describes macros used to mark up the body of your document.
3205 Examples include paragraphs, sections, and other groups.
3207 @menu
3208 * Paragraphs in ms::
3209 * Headings in ms::
3210 * Highlighting in ms::
3211 * Lists in ms::
3212 * Indentation values in ms::
3213 * Tabstops in ms::
3214 * ms Displays and Keeps::
3215 * ms Insertions::
3216 * Example multi-page table::
3217 * ms Footnotes::
3218 @end menu
3220 @c ---------------------------------------------------------------------
3222 @node Paragraphs in ms, Headings in ms, ms Body Text, ms Body Text
3223 @subsubsection Paragraphs
3224 @cindex @code{ms} macros, paragraph handling
3226 The following paragraph types are available.
3228 @DefmacList {PP, , ms}
3229 @DefmacListEnd {LP, , ms}
3230 Sets a paragraph with an initial indentation.
3231 @endDefmac
3233 @Defmac {QP, , ms}
3234 Sets a paragraph that is indented at both left and right margins.  The
3235 effect is identical to the @acronym{HTML} @code{<BLOCKQUOTE>} element.
3236 The next paragraph or heading returns margins to normal.
3237 @endDefmac
3239 @Defmac {XP, , ms}
3240 Sets a paragraph whose lines are indented, except for the first line.
3241 This is a Berkeley extension.
3242 @endDefmac
3244 The following markup uses all four paragraph macros.
3246 @Example
3247 @cartouche
3248 .NH 2
3249 Cases used in the study
3251 The following software and versions were
3252 considered for this report.
3254 For commercial software, we chose
3255 .B "Microsoft Word for Windows" ,
3256 starting with version 1.0 through the
3257 current version (Word 2000).
3259 For free software, we chose
3260 .B Emacs ,
3261 from its first appearance as a standalone
3262 editor through the current version (v20).
3263 See [Bloggs 2002] for details.
3265 Franklin's Law applied to software:
3266 software expands to outgrow both
3267 RAM and disk space over time.
3269 Bibliography:
3271 Bloggs, Joseph R.,
3272 .I "Everyone's a Critic" ,
3273 Underground Press, March 2002.
3274 A definitive work that answers all questions
3275 and criticisms about the quality and usability of
3276 free software.
3277 @end cartouche
3278 @endExample
3280 The @code{PORPHANS} register (@pxref{ms Document Control Registers})
3281 operates in conjunction with each of these macros, to inhibit the
3282 printing of orphan lines at the bottom of any page.
3284 @c ---------------------------------------------------------------------
3286 @node Headings in ms, Highlighting in ms, Paragraphs in ms, ms Body Text
3287 @subsubsection Headings
3288 @cindex @code{ms} macros, headings
3290 Use headings to create a hierarchical structure for your document.  The
3291 @file{ms} macros print headings in @strong{bold}, using the same font
3292 family and point size as the body text.
3294 The following describes the heading macros:
3296 @DefmacList {NH, @Var{curr-level}, ms}
3297 @DefmacListEnd {NH, @t{S} @Var{level0} @dots{}, ms}
3298 Numbered heading.  The argument is either a numeric argument to indicate
3299 the level of the heading, or the letter@tie{}@code{S} followed by
3300 numeric arguments to set the heading level explicitly.
3302 If you specify heading levels out of sequence, such as invoking
3303 @samp{.NH 3} after @samp{.NH 1}, @code{groff} prints a warning on
3304 standard error.
3305 @endDefmac
3307 @DefstrList {SN, ms}
3308 @DefstrItem {SN-DOT, ms}
3309 @DefstrListEnd {SN-NO-DOT, ms}
3310 After invocation of @code{NH}, the assigned section number is made
3311 available in the strings @code{SN-DOT} (as it appears in a printed
3312 section heading with default formatting, followed by a terminating
3313 period), and @code{SN-NO-DOT} (with the terminating period omitted).
3314 The string @code{SN} is also defined, as an alias for @code{SN-DOT}; if
3315 preferred, you may redefine it as an alias for @code{SN-NO-DOT}, by
3316 including the initialization
3317 @Example
3318 .als SN SN-NO-DOT
3319 @endExample
3321 @noindent
3322 at any time @strong{before} you would like the change to take effect.
3323 @endDefstr
3325 @Defstr {SN-STYLE, ms}
3326 You may control the style used to print section numbers, within numbered
3327 section headings, by defining an appropriate alias for the string
3328 @code{SN-STYLE}.  The default style, in which the printed section number
3329 is followed by a terminating period, is obtained by defining the alias
3330 @Example
3331 .als SN-STYLE SN-DOT
3332 @endExample
3334 @noindent
3335 If you prefer to omit the terminating period, from section numbers
3336 appearing in numbered section headings, you may define the alias
3337 @Example
3338 .als SN-STYLE SN-NO-DOT
3339 @endExample
3341 @noindent
3342 Any such change in section numbering style becomes effective from the
3343 next use of @code{.NH}, following redefinition of the alias for
3344 @code{SN-STYLE}.
3345 @endDefstr
3347 @Defmac {SH, [@Var{match-level}], ms}
3348 Unnumbered subheading.
3350 The optional @var{match-level} argument is a GNU extension.  It is a
3351 number indicating the level of the heading, in a manner analogous to the
3352 @var{curr-level} argument to @code{.NH}.  Its purpose is to match the
3353 point size, at which the heading is printed, to the size of a numbered
3354 heading at the same level, when the @code{GROWPS} and @code{PSINCR}
3355 heading size adjustment mechanism is in effect.  @xref{ms Document
3356 Control Registers}.
3357 @endDefmac
3359 The @code{HORPHANS} register (@pxref{ms Document Control Registers})
3360 operates in conjunction with the @code{NH} and @code{SH} macros, to
3361 inhibit the printing of orphaned section headings at the bottom of any
3362 page.
3364 @c ---------------------------------------------------------------------
3366 @node Highlighting in ms, Lists in ms, Headings in ms, ms Body Text
3367 @subsubsection Highlighting
3368 @cindex @code{ms} macros, highlighting
3370 The @file{ms} macros provide a variety of methods to highlight or
3371 emphasize text:
3373 @Defmac {B, [@Var{txt} [@Var{post} [@Var{pre}]]], ms}
3374 Sets its first argument in @strong{bold type}.  If you specify a second
3375 argument, @code{groff} prints it in the previous font after the bold
3376 text, with no intervening space (this allows you to set punctuation
3377 after the highlighted text without highlighting the punctuation).
3378 Similarly, it prints the third argument (if any) in the previous font
3379 @strong{before} the first argument.  For example,
3381 @Example
3382 .B foo ) (
3383 @endExample
3385 prints (@strong{foo}).
3387 If you give this macro no arguments, @code{groff} prints all text
3388 following in bold until the next highlighting, paragraph, or heading
3389 macro.
3390 @endDefmac
3392 @Defmac {R, [@Var{txt} [@Var{post} [@Var{pre}]]], ms}
3393 Sets its first argument in roman (or regular) type.  It operates
3394 similarly to the @code{B}@tie{}macro otherwise.
3395 @endDefmac
3397 @Defmac {I, [@Var{txt} [@Var{post} [@Var{pre}]]], ms}
3398 Sets its first argument in @emph{italic type}.  It operates similarly
3399 to the @code{B}@tie{}macro otherwise.
3400 @endDefmac
3402 @Defmac {CW, [@Var{txt} [@Var{post} [@Var{pre}]]], ms}
3403 Sets its first argument in a @code{constant width face}.  It operates
3404 similarly to the @code{B}@tie{}macro otherwise.
3405 @endDefmac
3407 @Defmac {BI, [@Var{txt} [@Var{post} [@Var{pre}]]], ms}
3408 Sets its first argument in bold italic type.  It operates similarly to
3409 the @code{B}@tie{}macro otherwise.
3410 @endDefmac
3412 @Defmac {BX, [@Var{txt}], ms}
3413 Prints its argument and draws a box around it.  If you want to box a
3414 string that contains spaces, use a digit-width space (@code{\0}).
3415 @endDefmac
3417 @Defmac {UL, [@Var{txt} [@Var{post}]], ms}
3418 Prints its first argument with an underline.  If you specify a second
3419 argument, @code{groff} prints it in the previous font after the
3420 underlined text, with no intervening space.
3421 @endDefmac
3423 @Defmac {LG, , ms}
3424 Prints all text following in larger type (two points larger than the
3425 current point size) until the next font size, highlighting, paragraph,
3426 or heading macro.  You can specify this macro multiple times to
3427 enlarge the point size as needed.
3428 @endDefmac
3430 @Defmac {SM, , ms}
3431 Prints all text following in smaller type (two points smaller than the
3432 current point size) until the next type size, highlighting, paragraph,
3433 or heading macro.  You can specify this macro multiple times to reduce
3434 the point size as needed.
3435 @endDefmac
3437 @Defmac {NL, , ms}
3438 Prints all text following in the normal point size (that is, the value
3439 of the @code{PS} register).
3440 @endDefmac
3442 @DefstrList {@Lbrace{}, ms}
3443 @DefstrListEnd {@Rbrace{}, ms}
3444 Text enclosed with @code{\*@{} and @code{\*@}} is printed as a
3445 superscript.
3446 @endDefstr
3448 @c ---------------------------------------------------------------------
3450 @node Lists in ms, Indentation values in ms, Highlighting in ms, ms Body Text
3451 @subsubsection Lists
3452 @cindex @code{ms} macros, lists
3454 The @code{IP} macro handles duties for all lists.
3456 @Defmac {IP, [@Var{marker} [@Var{width}]], ms}
3457 The @var{marker} is usually a bullet glyph (@code{\[bu]}) for unordered
3458 lists, a number (or auto-incrementing number register) for numbered
3459 lists, or a word or phrase for indented (glossary-style) lists.
3461 The @var{width} specifies the indentation for the body of each list
3462 item; its default unit is @samp{n}.  Once specified, the indentation
3463 remains the same for all list items in the document until specified
3464 again.
3466 The @code{PORPHANS} register (@pxref{ms Document Control Registers})
3467 operates in conjunction with the @code{IP} macro, to inhibit the
3468 printing of orphaned list markers at the bottom of any page.
3469 @endDefmac
3471 The following is an example of a bulleted list.
3472 @cindex example markup, bulleted list [@code{ms}]
3473 @cindex bulleted list, example markup [@code{ms}]
3475 @Example
3476 A bulleted list:
3477 .IP \[bu] 2
3478 lawyers
3479 .IP \[bu]
3480 guns
3481 .IP \[bu]
3482 money
3483 @endExample
3485 Produces:
3487 @Example
3488 A bulleted list:
3490 o lawyers
3492 o guns
3494 o money
3495 @endExample
3497 The following is an example of a numbered list.
3498 @cindex example markup, numbered list [@code{ms}]
3499 @cindex numbered list, example markup [@code{ms}]
3501 @Example
3502 .nr step 1 1
3503 A numbered list:
3504 .IP \n[step] 3
3505 lawyers
3506 .IP \n+[step]
3507 guns
3508 .IP \n+[step]
3509 money
3510 @endExample
3512 Produces:
3514 @Example
3515 A numbered list:
3517 1. lawyers
3519 2. guns
3521 3. money
3522 @endExample
3524 Note the use of the auto-incrementing number register in this example.
3526 The following is an example of a glossary-style list.
3527 @cindex example markup, glossary-style list [@code{ms}]
3528 @cindex glossary-style list, example markup [@code{ms}]
3530 @Example
3531 A glossary-style list:
3532 .IP lawyers 0.4i
3533 Two or more attorneys.
3534 .IP guns
3535 Firearms, preferably
3536 large-caliber.
3537 .IP money
3538 Gotta pay for those
3539 lawyers and guns!
3540 @endExample
3542 Produces:
3544 @Example
3545 A glossary-style list:
3547 lawyers
3548       Two or more attorneys.
3550 guns  Firearms, preferably large-caliber.
3552 money
3553       Gotta pay for those lawyers and guns!
3554 @endExample
3556 In the last example, the @code{IP} macro places the definition on the
3557 same line as the term if it has enough space; otherwise, it breaks to
3558 the next line and starts the definition below the term.  This may or may
3559 not be the effect you want, especially if some of the definitions break
3560 and some do not.  The following examples show two possible ways to force
3561 a break.
3563 The first workaround uses the @code{br} request to force a break after
3564 printing the term or label.
3566 @Example
3567 @cartouche
3568 A glossary-style list:
3569 .IP lawyers 0.4i
3570 Two or more attorneys.
3571 .IP guns
3573 Firearms, preferably large-caliber.
3574 .IP money
3575 Gotta pay for those lawyers and guns!
3576 @end cartouche
3577 @endExample
3579 The second workaround uses the @code{\p} escape to force the break.
3580 Note the space following the escape; this is important.  If you omit the
3581 space, @code{groff} prints the first word on the same line as the term
3582 or label (if it fits) @strong{then} breaks the line.
3584 @Example
3585 @cartouche
3586 A glossary-style list:
3587 .IP lawyers 0.4i
3588 Two or more attorneys.
3589 .IP guns
3590 \p Firearms, preferably large-caliber.
3591 .IP money
3592 Gotta pay for those lawyers and guns!
3593 @end cartouche
3594 @endExample
3596 To set nested lists, use the @code{RS} and @code{RE} macros.
3597 @xref{Indentation values in ms}, for more information.
3598 @cindex @code{ms} macros, nested lists
3599 @cindex nested lists [@code{ms}]
3601 For example:
3603 @Example
3604 @cartouche
3605 .IP \[bu] 2
3606 Lawyers:
3608 .IP \[bu]
3609 Dewey,
3610 .IP \[bu]
3611 Cheatham,
3612 .IP \[bu]
3613 and Howe.
3615 .IP \[bu]
3616 Guns
3617 @end cartouche
3618 @endExample
3620 Produces:
3622 @Example
3623 o Lawyers:
3625   o  Dewey,
3627   o  Cheatham,
3629   o  and Howe.
3631 o Guns
3632 @endExample
3634 @c ---------------------------------------------------------------------
3636 @node Indentation values in ms, Tabstops in ms, Lists in ms, ms Body Text
3637 @subsubsection Indentation values
3639 In many situations, you may need to indentation a section of text while
3640 still wrapping and filling.  @xref{Lists in ms}, for an example of
3641 nested lists.
3643 @DefmacList {RS, , ms}
3644 @DefmacListEnd {RE, , ms}
3645 These macros begin and end an indented section.  The @code{PI} register
3646 controls the amount of indentation, allowing the indented text to line
3647 up under hanging and indented paragraphs.
3648 @endDefmac
3650 @xref{ms Displays and Keeps}, for macros to indentation and turn off
3651 filling.
3653 @c ---------------------------------------------------------------------
3655 @node Tabstops in ms, ms Displays and Keeps, Indentation values in ms, ms Body Text
3656 @subsubsection Tab Stops
3658 Use the @code{ta} request to define tab stops as needed.  @xref{Tabs and
3659 Fields}.
3661 @Defmac {TA, , ms}
3662 Use this macro to reset the tab stops to the default for @file{ms}
3663 (every 5n).  You can redefine the @code{TA} macro to create a different
3664 set of default tab stops.
3665 @endDefmac
3667 @c ---------------------------------------------------------------------
3669 @node ms Displays and Keeps, ms Insertions, Tabstops in ms, ms Body Text
3670 @subsubsection Displays and keeps
3671 @cindex @code{ms} macros, displays
3672 @cindex @code{ms} macros, keeps
3673 @cindex keeps [@code{ms}]
3674 @cindex displays [@code{ms}]
3676 Use displays to show text-based examples or figures (such as code
3677 listings).
3679 Displays turn off filling, so lines of code are displayed as-is without
3680 inserting @code{br} requests in between each line.  Displays can be
3681 @dfn{kept} on a single page, or allowed to break across pages.
3683 @DefmacList {DS, @t{L}, ms}
3684 @DefmacItem {LD, , ms}
3685 @DefmacListEnd {DE, , ms}
3686 Left-justified display.  The @samp{.DS L} call generates a page break,
3687 if necessary, to keep the entire display on one page.  The @code{LD}
3688 macro allows the display to break across pages.  The @code{DE} macro
3689 ends the display.
3690 @endDefmac
3692 @DefmacList {DS, @t{I}, ms}
3693 @DefmacItem {ID, , ms}
3694 @DefmacListEnd {DE, , ms}
3695 Indents the display as defined by the @code{DI} register.  The @samp{.DS
3696 I} call generates a page break, if necessary, to keep the entire display
3697 on one page.  The @code{ID} macro allows the display to break across
3698 pages.  The @code{DE} macro ends the display.
3699 @endDefmac
3701 @DefmacList {DS, @t{B}, ms}
3702 @DefmacItem {BD, , ms}
3703 @DefmacListEnd {DE, , ms}
3704 Sets a block-centered display: the entire display is left-justified, but
3705 indented so that the longest line in the display is centered on the
3706 page.  The @samp{.DS B} call generates a page break, if necessary, to
3707 keep the entire display on one page.  The @code{BD} macro allows the
3708 display to break across pages.  The @code{DE} macro ends the display.
3709 @endDefmac
3711 @DefmacList {DS, @t{C}, ms}
3712 @DefmacItem {CD, , ms}
3713 @DefmacListEnd {DE, , ms}
3714 Sets a centered display: each line in the display is centered.  The
3715 @samp{.DS C} call generates a page break, if necessary, to keep the
3716 entire display on one page.  The @code{CD} macro allows the display to
3717 break across pages.  The @code{DE} macro ends the display.
3718 @endDefmac
3720 @DefmacList {DS, @t{R}, ms}
3721 @DefmacItem {RD, , ms}
3722 @DefmacListEnd {DE, , ms}
3723 Right-justifies each line in the display.  The @samp{.DS R} call
3724 generates a page break, if necessary, to keep the entire display on one
3725 page.  The @code{RD} macro allows the display to break across pages.
3726 The @code{DE} macro ends the display.
3727 @endDefmac
3729 @DefmacList {Ds, , ms}
3730 @DefmacListEnd {De, , ms}
3731 These two macros were formerly provided as aliases for @code{DS} and
3732 @code{DE}, respectively.  They have been removed, and should no longer
3733 be used.  The original implementations of @code{DS} and @code{DE} are
3734 retained, and should be used instead.  X11 documents which actually use
3735 @code{Ds} and @code{De} always load a specific macro file from the X11
3736 distribution (@file{macros.t}) which provides proper definitions for the
3737 two macros.
3738 @endDefmac
3740 On occasion, you may want to @dfn{keep} other text together on a page.
3741 For example, you may want to keep two paragraphs together, or a
3742 paragraph that refers to a table (or list, or other item) immediately
3743 following.  The @file{ms} macros provide the @code{KS} and @code{KE}
3744 macros for this purpose.
3746 @DefmacList {KS, , ms}
3747 @DefmacListEnd {KE, , ms}
3748 The @code{KS} macro begins a block of text to be kept on a single page,
3749 and the @code{KE} macro ends the block.
3750 @endDefmac
3752 @DefmacList {KF, , ms}
3753 @DefmacListEnd {KE, , ms}
3754 Specifies a @dfn{floating keep}; if the keep cannot fit on the current
3755 page, @code{groff} holds the contents of the keep and allows text
3756 following the keep (in the source file) to fill in the remainder of the
3757 current page.  When the page breaks, whether by an explicit @code{bp}
3758 request or by reaching the end of the page, @code{groff} prints the
3759 floating keep at the top of the new page.  This is useful for printing
3760 large graphics or tables that do not need to appear exactly where
3761 specified.
3762 @endDefmac
3764 You can also use the @code{ne} request to force a page break if there is
3765 not enough vertical space remaining on the page.
3767 Use the following macros to draw a box around a section of text (such as
3768 a display).
3770 @DefmacList {B1, , ms}
3771 @DefmacListEnd {B2, , ms}
3772 Marks the beginning and ending of text that is to have a box drawn
3773 around it.  The @code{B1} macro begins the box; the @code{B2} macro ends
3774 it.  Text in the box is automatically placed in a diversion (keep).
3775 @endDefmac
3777 @c ---------------------------------------------------------------------
3779 @node ms Insertions, Example multi-page table, ms Displays and Keeps, ms Body Text
3780 @subsubsection Tables, figures, equations, and references
3781 @cindex @code{ms} macros, tables
3782 @cindex @code{ms} macros, figures
3783 @cindex @code{ms} macros, equations
3784 @cindex @code{ms} macros, references
3785 @cindex tables [@code{ms}]
3786 @cindex figures [@code{ms}]
3787 @cindex equations [@code{ms}]
3788 @cindex references [@code{ms}]
3790 The @file{ms} macros support the standard @code{groff} preprocessors:
3791 @code{tbl}, @code{pic}, @code{eqn}, and @code{refer}.
3792 @pindex tbl
3793 @pindex pic
3794 @pindex eqn
3795 @pindex refer
3796 You mark text meant for preprocessors by enclosing it in pairs of tags
3797 as follows.
3799 @DefmacList {TS, [@code{H}], ms}
3800 @DefmacListEnd {TE, , ms}
3801 Denotes a table, to be processed by the @code{tbl} preprocessor.  The
3802 optional argument@tie{}@code{H} to @code{TS} instructs @code{groff} to
3803 create a running header with the information up to the @code{TH} macro.
3804 @code{groff} prints the header at the beginning of the table; if the
3805 table runs onto another page, @code{groff} prints the header on the next
3806 page as well.
3807 @endDefmac
3809 @DefmacList {PS, , ms}
3810 @DefmacListEnd {PE, , ms}
3811 Denotes a graphic, to be processed by the @code{pic} preprocessor.  You
3812 can create a @code{pic} file by hand, using the @acronym{AT&T}
3813 @code{pic} manual available on the Web as a reference, or by using a
3814 graphics program such as @code{xfig}.
3815 @endDefmac
3817 @DefmacList {EQ, [@Var{align}], ms}
3818 @DefmacListEnd {EN, , ms}
3819 Denotes an equation, to be processed by the @code{eqn} preprocessor.
3820 The optional @var{align} argument can be @code{C}, @code{L},
3821 or@tie{}@code{I} to center (the default), left-justify, or indent the
3822 equation.
3823 @endDefmac
3825 @DefmacList {[, , ms}
3826 @DefmacListEnd {], , ms}
3827 Denotes a reference, to be processed by the @code{refer} preprocessor.
3828 The @acronym{GNU} @cite{refer(1)} man page provides a comprehensive
3829 reference to the preprocessor and the format of the bibliographic
3830 database.
3831 @endDefmac
3833 @menu
3834 * Example multi-page table::
3835 @end menu
3837 @c ---------------------------------------------------------------------
3839 @node Example multi-page table, ms Footnotes, ms Insertions, ms Body Text
3840 @subsubsection An example multi-page table
3841 @cindex example markup, multi-page table [@code{ms}]
3842 @cindex multi-page table, example markup [@code{ms}]
3844 The following is an example of how to set up a table that may print
3845 across two or more pages.
3847 @Example
3848 @cartouche
3849 .TS H
3850 allbox expand;
3851 cb | cb .
3852 Text      ...of heading...
3856 l | l .
3857 ... the rest of the table follows...
3860 @end cartouche
3861 @endExample
3863 @c ---------------------------------------------------------------------
3865 @node ms Footnotes,  , Example multi-page table, ms Body Text
3866 @subsubsection Footnotes
3867 @cindex @code{ms} macros, footnotes
3868 @cindex footnotes [@code{ms}]
3870 The @file{ms} macro package has a flexible footnote system.  You can
3871 specify either numbered footnotes or symbolic footnotes (that is, using
3872 a marker such as a dagger symbol).
3874 @Defstr {*, ms}
3875 Specifies the location of a numbered footnote marker in the text.
3876 @endDefesc
3878 @DefmacList {FS, , ms}
3879 @DefmacListEnd {FE, , ms}
3880 Specifies the text of the footnote.  The default action is to create a
3881 numbered footnote; you can create a symbolic footnote by specifying a
3882 @dfn{mark} glyph (such as @code{\[dg]} for the dagger glyph) in the body
3883 text and as an argument to the @code{FS} macro, followed by the text of
3884 the footnote and the @code{FE} macro.
3885 @endDefmac
3887 You can control how @code{groff} prints footnote numbers by changing the
3888 value of the @code{FF} register.  @xref{ms Document Control Registers}.
3890 @cindex footnotes, and keeps [@code{ms}]
3891 @cindex keeps, and footnotes [@code{ms}]
3892 @cindex footnotes, and displays [@code{ms}]
3893 @cindex displays, and footnotes [@code{ms}]
3894 Footnotes can be safely used within keeps and displays, but you should
3895 avoid using numbered footnotes within floating keeps.  You can set a
3896 second @code{\**} marker between a @code{\**} and its corresponding
3897 @code{.FS} entry; as long as each @code{FS} macro occurs @emph{after}
3898 the corresponding @code{\**} and the occurrences of @code{.FS} are in
3899 the same order as the corresponding occurrences of @code{\**}.
3901 @c ---------------------------------------------------------------------
3903 @node ms Page Layout, Differences from AT&T ms, ms Body Text, ms
3904 @subsection Page layout
3905 @cindex @code{ms} macros, page layout
3906 @cindex page layout [@code{ms}]
3908 The default output from the @file{ms} macros provides a minimalist page
3909 layout: it prints a single column, with the page number centered at the
3910 top of each page.  It prints no footers.
3912 You can change the layout by setting the proper number registers and
3913 strings.
3915 @menu
3916 * ms Headers and Footers::
3917 * ms Margins::
3918 * ms Multiple Columns::
3919 * ms TOC::
3920 * ms Strings and Special Characters::
3921 @end menu
3923 @c ---------------------------------------------------------------------
3925 @node ms Headers and Footers, ms Margins, ms Page Layout, ms Page Layout
3926 @subsubsection Headers and footers
3927 @cindex @code{ms} macros, headers
3928 @cindex @code{ms} macros, footers
3929 @cindex headers [@code{ms}]
3930 @cindex footers [@code{ms}]
3932 For documents that do not distinguish between odd and even pages, set
3933 the following strings:
3935 @DefstrList {LH, ms}
3936 @DefstrItem {CH, ms}
3937 @DefstrListEnd {RH, ms}
3938 Sets the left, center, and right headers.
3939 @endDefstr
3941 @DefstrList {LF, ms}
3942 @DefstrItem {CF, ms}
3943 @DefstrListEnd {RF, ms}
3944 Sets the left, center, and right footers.
3945 @endDefstr
3947 For documents that need different information printed in the even and
3948 odd pages, use the following macros:
3950 @DefmacList {OH, @t{'}@Var{left}@t{'}@Var{center}@t{'}@Var{right}@t{'}, ms}
3951 @DefmacItem {EH, @t{'}@Var{left}@t{'}@Var{center}@t{'}@Var{right}@t{'}, ms}
3952 @DefmacItem {OF, @t{'}@Var{left}@t{'}@Var{center}@t{'}@Var{right}@t{'}, ms}
3953 @DefmacListEnd {EF, @t{'}@Var{left}@t{'}@Var{center}@t{'}@Var{right}@t{'}, ms}
3954 The @code{OH} and @code{EH} macros define headers for the odd and even
3955 pages; the @code{OF} and @code{EF} macros define footers for the odd and
3956 even pages.  This is more flexible than defining the individual strings.
3958 You can replace the quote (@code{'}) marks with any character not
3959 appearing in the header or footer text.
3960 @endDefmac
3962 To specify custom header and footer processing, redefine the following
3963 macros:
3965 @DefmacList {PT,, ms}
3966 @DefmacItem {HD,, ms}
3967 @DefmacListEnd {BT,, ms}
3968 The @code{PT} macro defines a custom header; the @code{BT} macro defines
3969 a custom footer.  These macros must handle odd/even/first page
3970 differences if necessary.
3972 The @code{HD} macro defines additional header processing to take place
3973 after executing the @code{PT} macro.
3974 @endDefmac
3976 @c ---------------------------------------------------------------------
3978 @node ms Margins, ms Multiple Columns, ms Headers and Footers, ms Page Layout
3979 @subsubsection Margins
3980 @cindex @code{ms} macros, margins
3982 You control margins using a set of number registers.  @xref{ms Document
3983 Control Registers}, for details.
3985 @c ---------------------------------------------------------------------
3987 @node ms Multiple Columns, ms TOC, ms Margins, ms Page Layout
3988 @subsubsection Multiple columns
3989 @cindex @code{ms} macros, multiple columns
3990 @cindex multiple columns [@code{ms}]
3992 The @file{ms} macros can set text in as many columns as do reasonably
3993 fit on the page.  The following macros are available; all of them force
3994 a page break if a multi-column mode is already set.  However, if the
3995 current mode is single-column, starting a multi-column mode does
3996 @emph{not} force a page break.
3998 @Defmac {1C, , ms}
3999 Single-column mode.
4000 @endDefmac
4002 @Defmac {2C, , ms}
4003 Two-column mode.
4004 @endDefmac
4006 @Defmac {MC, [@Var{width} [@Var{gutter}]], ms}
4007 Multi-column mode.  If you specify no arguments, it is equivalent to the
4008 @code{2C} macro.  Otherwise, @var{width} is the width of each column and
4009 @var{gutter} is the space between columns.  The @code{MINGW} number
4010 register controls the default gutter width.
4011 @endDefmac
4013 @c ---------------------------------------------------------------------
4015 @node ms TOC, ms Strings and Special Characters, ms Multiple Columns, ms Page Layout
4016 @subsubsection Creating a table of contents
4017 @cindex @code{ms} macros, creating table of contents
4018 @cindex table of contents, creating [@code{ms}]
4020 The facilities in the @file{ms} macro package for creating a table of
4021 contents are semi-automated at best.  Assuming that you want the table
4022 of contents to consist of the document's headings, you need to repeat
4023 those headings wrapped in @code{XS} and @code{XE} macros.
4025 @DefmacList {XS, [@Var{page}], ms}
4026 @DefmacItem {XA, [@Var{page}], ms}
4027 @DefmacListEnd {XE, , ms}
4028 These macros define a table of contents or an individual entry in the
4029 table of contents, depending on their use.  The macros are very simple;
4030 they cannot indent a heading based on its level.  The easiest way to
4031 work around this is to add tabs to the table of contents string.  The
4032 following is an example:
4034 @Example
4035 @cartouche
4036 .NH 1
4037 Introduction
4039 Introduction
4044 .NH 2
4045 Methodology
4047 Methodology
4051 @end cartouche
4052 @endExample
4054 You can manually create a table of contents by beginning with the
4055 @code{XS} macro for the first entry, specifying the page number for that
4056 entry as the argument to @code{XS}.  Add subsequent entries using the
4057 @code{XA} macro, specifying the page number for that entry as the
4058 argument to @code{XA}.  The following is an example:
4060 @Example
4061 @cartouche
4062 .XS 1
4063 Introduction
4064 .XA 2
4065 A Brief History of the Universe
4066 .XA 729
4067 Details of Galactic Formation
4070 @end cartouche
4071 @endExample
4072 @endDefmac
4074 @Defmac {TC, [@code{no}], ms}
4075 Prints the table of contents on a new page, setting the page number
4076 to@tie{}@strong{i} (Roman lowercase numeral one).  You should usually
4077 place this macro at the end of the file, since @code{groff} is a
4078 single-pass formatter and can only print what has been collected up to
4079 the point that the @code{TC} macro appears.
4081 The optional argument @code{no} suppresses printing the title specified
4082 by the string register @code{TOC}.
4083 @endDefmac
4085 @Defmac {PX, [@code{no}], ms}
4086 Prints the table of contents on a new page, using the current page
4087 numbering sequence.  Use this macro to print a manually-generated table
4088 of contents at the beginning of your document.
4090 The optional argument @code{no} suppresses printing the title specified
4091 by the string register @code{TOC}.
4092 @endDefmac
4094 The @cite{Groff and Friends HOWTO} includes a @code{sed} script that
4095 automatically inserts @code{XS} and @code{XE} macro entries after each
4096 heading in a document.
4098 Altering the @code{NH} macro to automatically build the table of
4099 contents is perhaps initially more difficult, but would save a great
4100 deal of time in the long run if you use @file{ms} regularly.
4102 @c ---------------------------------------------------------------------
4104 @node ms Strings and Special Characters,  , ms TOC, ms Page Layout
4105 @subsubsection Strings and Special Characters
4106 @cindex @code{ms} macros, strings
4107 @cindex @code{ms} macros, special characters
4108 @cindex @code{ms} macros, accent marks
4109 @cindex accent marks [@code{ms}]
4110 @cindex special characters [@code{ms}]
4111 @cindex strings [@code{ms}]
4113 The @file{ms} macros provide the following predefined strings.  You can
4114 change the string definitions to help in creating documents in languages
4115 other than English.
4117 @Defstr {REFERENCES, ms}
4118 Contains the string printed at the beginning of the references
4119 (bibliography) page.  The default is @samp{References}.
4120 @endDefstr
4122 @Defstr {ABSTRACT, ms}
4123 Contains the string printed at the beginning of the abstract.  The
4124 default is @samp{ABSTRACT}.
4125 @endDefstr
4127 @Defstr {TOC, ms}
4128 Contains the string printed at the beginning of the table of contents.
4129 @endDefstr
4131 @DefstrList {MONTH1, ms}
4132 @DefstrItem {MONTH2, ms}
4133 @DefstrItem {MONTH3, ms}
4134 @DefstrItem {MONTH4, ms}
4135 @DefstrItem {MONTH5, ms}
4136 @DefstrItem {MONTH6, ms}
4137 @DefstrItem {MONTH7, ms}
4138 @DefstrItem {MONTH8, ms}
4139 @DefstrItem {MONTH9, ms}
4140 @DefstrItem {MONTH10, ms}
4141 @DefstrItem {MONTH11, ms}
4142 @DefstrListEnd {MONTH12, ms}
4143 Prints the full name of the month in dates.  The default is
4144 @samp{January}, @samp{February}, etc.
4145 @endDefstr
4147 The following special characters are available@footnote{For an
4148 explanation what special characters are see @ref{Special Characters}.}:
4150 @Defstr {-, ms}
4151 Prints an em dash.
4152 @endDefstr
4154 @DefstrList {Q, ms}
4155 @DefstrListEnd {U, ms}
4156 Prints typographer's quotes in troff, and plain quotes in nroff.
4157 @code{\*Q} is the left quote and @code{\*U} is the right quote.
4158 @endDefstr
4160 Improved accent marks are available in the @file{ms} macros.
4162 @Defmac {AM, , ms}
4163 Specify this macro at the beginning of your document to enable extended
4164 accent marks and special characters.  This is a Berkeley extension.
4166 To use the accent marks, place them @strong{after} the character being
4167 accented.
4169 Note that groff's native support for accents is superior to the
4170 following definitions.
4171 @endDefmac
4173 The following accent marks are available after invoking the @code{AM}
4174 macro:
4176 @Defstr {\', ms}
4177 Acute accent.
4178 @endDefstr
4180 @Defstr {\`, ms}
4181 Grave accent.
4182 @endDefstr
4184 @Defstr {^, ms}
4185 Circumflex.
4186 @endDefstr
4188 @Defstr {\,, ms}
4189 Cedilla.
4190 @endDefstr
4192 @Defstr {~, ms}
4193 Tilde.
4194 @endDefstr
4196 @deffn String @t{\*[:]}
4197 @ifnotinfo
4198 @stindex : @r{[}ms@r{]}
4199 @end ifnotinfo
4200 @ifinfo
4201 @stindex \*[@r{<colon>}] @r{[}ms@r{]}
4202 @end ifinfo
4203 Umlaut.
4204 @end deffn
4206 @Defstr {v, ms}
4207 Hacek.
4208 @endDefstr
4210 @Defstr {_, ms}
4211 Macron (overbar).
4212 @endDefstr
4214 @Defstr {., ms}
4215 Underdot.
4216 @endDefstr
4218 @Defstr {o, ms}
4219 Ring above.
4220 @endDefstr
4222 The following are standalone characters available after invoking the
4223 @code{AM} macro:
4225 @Defstr {?, ms}
4226 Upside-down question mark.
4227 @endDefstr
4229 @Defstr {!, ms}
4230 Upside-down exclamation point.
4231 @endDefstr
4233 @Defstr {8, ms}
4234 German ÃŸ ligature.
4235 @endDefstr
4237 @Defstr {3, ms}
4238 Yogh.
4239 @endDefstr
4241 @Defstr {Th, ms}
4242 Uppercase thorn.
4243 @endDefstr
4245 @Defstr {th, ms}
4246 Lowercase thorn.
4247 @endDefstr
4249 @Defstr {D-, ms}
4250 Uppercase eth.
4251 @endDefstr
4253 @Defstr {d-, ms}
4254 Lowercase eth.
4255 @endDefstr
4257 @Defstr {q, ms}
4258 Hooked o.
4259 @endDefstr
4261 @Defstr {ae, ms}
4262 Lowercase Ã¦ ligature.
4263 @endDefstr
4265 @Defstr {Ae, ms}
4266 Uppercase Ã† ligature.
4267 @endDefstr
4269 @c ---------------------------------------------------------------------
4271 @node Differences from AT&T ms, Naming Conventions, ms Page Layout, ms
4272 @subsection Differences from @acronym{AT&T} @file{ms}
4273 @cindex @code{ms} macros, differences from @acronym{AT&T}
4274 @cindex @acronym{AT&T} @code{troff}, @code{ms} macro package differences
4276 This section lists the (minor) differences between the @code{groff -ms}
4277 macros and @acronym{AT&T} @code{troff -ms} macros.
4279 @itemize @bullet
4280 @item
4281 The internals of @code{groff -ms} differ from the internals of
4282 @acronym{AT&T} @code{troff -ms}.  Documents that depend upon
4283 implementation details of @acronym{AT&T} @code{troff -ms} may not format
4284 properly with @code{groff -ms}.
4286 @item
4287 The general error-handling policy of @code{groff -ms} is to detect and
4288 report errors, rather than silently to ignore them.
4290 @item
4291 @code{groff -ms} does not work in compatibility mode (this is, with the
4292 @option{-C} option).
4294 @item
4295 There is no special support for typewriter-like devices.
4297 @item
4298 @code{groff -ms} does not provide cut marks.
4300 @item
4301 Multiple line spacing is not supported.  Use a larger vertical spacing
4302 instead.
4304 @item
4305 Some @acronym{UNIX} @code{ms} documentation says that the @code{CW} and
4306 @code{GW} number registers can be used to control the column width and
4307 gutter width, respectively.  These number registers are not used in
4308 @code{groff -ms}.
4310 @item
4311 Macros that cause a reset (paragraphs, headings, etc.@:) may change the
4312 indentation.  Macros that change the indentation do not increment or
4313 decrement the indentation, but rather set it absolutely.  This can cause
4314 problems for documents that define additional macros of their own.  The
4315 solution is to use not the @code{in} request but instead the @code{RS}
4316 and @code{RE} macros.
4318 @item
4319 To make @code{groff -ms} use the default page offset (which also
4320 specifies the left margin), the @code{PO} register must stay undefined
4321 until the first @file{-ms} macro is evaluated.  This implies that
4322 @code{PO} should not be used early in the document, unless it is changed
4323 also: Remember that accessing an undefined register automatically
4324 defines it.
4325 @end itemize
4327 @Defmpreg {GS, ms}
4328 This number register is set to@tie{}1 by the @code{groff -ms} macros,
4329 but it is not used by the @code{AT&T} @code{troff -ms} macros.
4330 Documents that need to determine whether they are being formatted with
4331 @code{AT&T} @code{troff -ms} or @code{groff -ms} should use this number
4332 register.
4333 @endDefmpreg
4335 Emulations of a few ancient Bell Labs macros can be re-enabled by
4336 calling the otherwise undocumented @code{SC} section-header macro.
4337 Calling @code{SC} enables @code{UC} for marking up a product or
4338 application name, and the pair @code{P1}/@code{P2} for surrounding code
4339 example displays.
4341 These are not enabled by default because (a)@tie{}they were not
4342 documented, in the original @code{ms} manual, and (b)@tie{}the @code{P1}
4343 and @code{UC} macros collide with different macros with the same names
4344 in the Berkeley version of @code{ms}.
4346 These @code{groff} emulations are sufficient to give back the 1976
4347 Kernighan@tie{}& Cherry paper @cite{Typsetting Mathematics -- User's
4348 Guide} its section headings, and restore some text that had gone missing
4349 as arguments of undefined macros.  No warranty express or implied is
4350 given as to how well the typographic details these produce match the
4351 original Bell Labs macros.
4353 @menu
4354 * Missing ms Macros::
4355 * Additional ms Macros::
4356 @end menu
4358 @c ---------------------------------------------------------------------
4360 @node Missing ms Macros, Additional ms Macros, Differences from AT&T ms, Differences from AT&T ms
4361 @subsubsection @code{troff} macros not appearing in @code{groff}
4363 Macros missing from @code{groff -ms} are cover page macros specific to
4364 Bell Labs and Berkeley.  The macros known to be missing are:
4366 @table @code
4367 @item .TM
4368 Technical memorandum; a cover sheet style
4370 @item .IM
4371 Internal memorandum; a cover sheet style
4373 @item .MR
4374 Memo for record; a cover sheet style
4376 @item .MF
4377 Memo for file; a cover sheet style
4379 @item .EG
4380 Engineer's notes; a cover sheet style
4382 @item .TR
4383 Computing Science Tech Report; a cover sheet style
4385 @item .OK
4386 Other keywords
4388 @item .CS
4389 Cover sheet information
4391 @item .MH
4392 A cover sheet macro
4393 @end table
4395 @c ---------------------------------------------------------------------
4397 @node Additional ms Macros,  , Missing ms Macros, Differences from AT&T ms
4398 @subsubsection @code{groff} macros not appearing in @acronym{AT&T} @code{troff}
4400 The @code{groff -ms} macros have a few minor extensions compared to the
4401 @acronym{AT&T} @code{troff -ms} macros.
4403 @Defmac {AM, , ms}
4404 Improved accent marks.  @xref{ms Strings and Special Characters}, for
4405 details.
4406 @endDefmac
4408 @Defmac {DS, @t{I}, ms}
4409 Indented display.  The default behavior of @acronym{AT&T} @code{troff
4410 -ms} was to indent; the @code{groff} default prints displays flush left
4411 with the body text.
4412 @endDefmac
4414 @Defmac {CW, , ms}
4415 Print text in @code{constant width} (Courier) font.
4416 @endDefmac
4418 @Defmac {IX, , ms}
4419 Indexing term (printed on standard error).  You can write a script to
4420 capture and process an index generated in this manner.
4421 @endDefmac
4423 The following additional number registers
4424 appear in @code{groff -ms}:
4426 @Defmpreg {MINGW, ms}
4427 Specifies a minimum space between columns (for multi-column output);
4428 this takes the place of the @code{GW} register that was documented but
4429 apparently not implemented in @acronym{AT&T} @code{troff}.
4430 @endDefmpreg
4432 Several new string registers are available as well.  You can change
4433 these to handle (for example) the local language.  @xref{ms Strings and
4434 Special Characters}, for details.
4436 @c ---------------------------------------------------------------------
4438 @node Naming Conventions,  , Differences from AT&T ms, ms
4439 @subsection Naming Conventions
4440 @cindex @code{ms} macros, naming conventions
4441 @cindex naming conventions, @code{ms} macros
4443 The following conventions are used for names of macros, strings and
4444 number registers.  External names available to documents that use the
4445 @code{groff -ms} macros contain only uppercase letters and digits.
4447 Internally the macros are divided into modules; naming conventions are
4448 as follows:
4450 @itemize @bullet
4451 @item
4452 Names used only within one module are of the form
4453 @var{module}@code{*}@var{name}.
4455 @item
4456 Names used outside the module in which they are defined are of the form
4457 @var{module}@code{@@}@var{name}.
4459 @item
4460 Names associated with a particular environment are of the form
4461 @var{environment}@code{:}@var{name}; these are used only within the
4462 @code{par} module.
4464 @item
4465 @var{name} does not have a module prefix.
4467 @item
4468 Constructed names used to implement arrays are of the form
4469 @var{array}@code{!}@var{index}.
4470 @end itemize
4472 Thus the groff ms macros reserve the following names:
4474 @itemize @bullet
4475 @item
4476 Names containing the characters @code{*}, @code{@@}, and@tie{}@code{:}.
4478 @item
4479 Names containing only uppercase letters and digits.
4480 @end itemize
4483 @c =====================================================================
4485 @node me, mm, ms, Macro Packages
4486 @section @file{me}
4487 @cindex @code{me} macro package
4489 @c XXX documentation
4490 @c XXX this is a placeholder until we get stuff knocked into shape
4491 See the @file{meintro.me} and @file{meref.me} documents in groff's
4492 @file{doc} directory.
4495 @c =====================================================================
4497 @node mm,  , me, Macro Packages
4498 @section @file{mm}
4499 @cindex @code{mm} macro package
4501 @c XXX documentation
4502 @c XXX this is a placeholder until we get stuff knocked into shape
4503 See the @cite{groff_mm(7)} man page (type @command{man groff_mm} at the
4504 command line).
4508 @c =====================================================================
4509 @c =====================================================================
4511 @node gtroff Reference, Preprocessors, Macro Packages, Top
4512 @chapter @code{gtroff} Reference
4513 @cindex reference, @code{gtroff}
4514 @cindex @code{gtroff}, reference
4516 This chapter covers @strong{all} of the facilities of @code{gtroff}.
4517 Users of macro packages may skip it if not interested in details.
4520 @menu
4521 * Text::
4522 * Measurements::
4523 * Expressions::
4524 * Identifiers::
4525 * Embedded Commands::
4526 * Registers::
4527 * Manipulating Filling and Adjusting::
4528 * Manipulating Hyphenation::
4529 * Manipulating Spacing::
4530 * Tabs and Fields::
4531 * Character Translations::
4532 * Troff and Nroff Mode::
4533 * Line Layout::
4534 * Line Control::
4535 * Page Layout::
4536 * Page Control::
4537 * Fonts and Symbols::
4538 * Sizes::
4539 * Strings::
4540 * Conditionals and Loops::
4541 * Writing Macros::
4542 * Page Motions::
4543 * Drawing Requests::
4544 * Traps::
4545 * Diversions::
4546 * Environments::
4547 * Suppressing output::
4548 * Colors::
4549 * I/O::
4550 * Postprocessor Access::
4551 * Miscellaneous::
4552 * Gtroff Internals::
4553 * Debugging::
4554 * Implementation Differences::
4555 @end menu
4558 @c =====================================================================
4560 @node Text, Measurements, gtroff Reference, gtroff Reference
4561 @section Text
4562 @cindex text, @code{gtroff} processing
4564 @code{gtroff} input files contain text with control commands
4565 interspersed throughout.  But, even without control codes, @code{gtroff}
4566 still does several things with the input text:
4568 @itemize @bullet
4569 @item
4570 filling and adjusting
4572 @item
4573 adding additional space after sentences
4575 @item
4576 hyphenating
4578 @item
4579 inserting implicit line breaks
4580 @end itemize
4582 @menu
4583 * Filling and Adjusting::
4584 * Hyphenation::
4585 * Sentences::
4586 * Tab Stops::
4587 * Implicit Line Breaks::
4588 * Input Conventions::
4589 * Input Encodings::
4590 @end menu
4592 @c ---------------------------------------------------------------------
4594 @node Filling and Adjusting, Hyphenation, Text, Text
4595 @subsection Filling and Adjusting
4596 @cindex filling
4597 @cindex adjusting
4599 When @code{gtroff} reads text, it collects words from the input and fits
4600 as many of them together on one output line as it can.  This is known as
4601 @dfn{filling}.
4603 @cindex leading spaces
4604 @cindex spaces, leading and trailing
4605 @cindex extra spaces
4606 @cindex trailing spaces
4607 Once @code{gtroff} has a @dfn{filled} line, it tries to @dfn{adjust} it.
4608 This means it widens the spacing between words until the text reaches
4609 the right margin (in the default adjustment mode).  Extra spaces between
4610 words are preserved, but spaces at the end of lines are ignored.  Spaces
4611 at the front of a line cause a @dfn{break} (breaks are explained in
4612 @ref{Implicit Line Breaks}).
4614 @xref{Manipulating Filling and Adjusting}.
4616 @c ---------------------------------------------------------------------
4618 @node Hyphenation, Sentences, Filling and Adjusting, Text
4619 @subsection Hyphenation
4620 @cindex hyphenation
4622 Since the odds are not great for finding a set of words, for every
4623 output line, which fit nicely on a line without inserting excessive
4624 amounts of space between words, @code{gtroff} hyphenates words so that
4625 it can justify lines without inserting too much space between words.  It
4626 uses an internal hyphenation algorithm (a simplified version of the
4627 algorithm used within @TeX{}) to indicate which words can be hyphenated
4628 and how to do so.  When a word is hyphenated, the first part of the word
4629 is added to the current filled line being output (with an attached
4630 hyphen), and the other portion is added to the next line to be filled.
4632 @xref{Manipulating Hyphenation}.
4634 @c ---------------------------------------------------------------------
4636 @node Sentences, Tab Stops, Hyphenation, Text
4637 @subsection Sentences
4638 @cindex sentences
4640 Although it is often debated, some typesetting rules say there should be
4641 different amounts of space after various punctuation marks.  For
4642 example, the @cite{Chicago typsetting manual} says that a period at the
4643 end of a sentence should have twice as much space following it as would
4644 a comma or a period as part of an abbreviation.
4646 @c XXX exact citation of Chicago manual
4648 @cindex sentence space
4649 @cindex space between sentences
4650 @cindex french-spacing
4651 @code{gtroff} does this by flagging certain characters (normally
4652 @samp{!}, @samp{?}, and @samp{.}) as @dfn{end-of-sentence} characters.
4653 When @code{gtroff} encounters one of these characters at the end of a
4654 line, it appends a normal space followed by a @dfn{sentence space} in
4655 the formatted output.  (This justifies one of the conventions mentioned
4656 in @ref{Input Conventions}.)
4658 @cindex transparent characters
4659 @cindex character, transparent
4660 @cindex @code{dg} glyph, at end of sentence
4661 @cindex @code{rq} glyph, at end of sentence
4662 @cindex @code{"}, at end of sentence
4663 @cindex @code{'}, at end of sentence
4664 @cindex @code{)}, at end of sentence
4665 @cindex @code{]}, at end of sentence
4666 @cindex @code{*}, at end of sentence
4667 In addition, the following characters and symbols are treated
4668 transparently while handling end-of-sentence characters: @samp{"},
4669 @samp{'}, @samp{)}, @samp{]}, @samp{*}, @code{\[dg]}, and @code{\[rq]}.
4671 See the @code{cflags} request in @ref{Using Symbols}, for more details.
4673 @cindex @code{\&}, at end of sentence
4674 To prevent the insertion of extra space after an end-of-sentence
4675 character (at the end of a line), append @code{\&}.
4677 @c ---------------------------------------------------------------------
4679 @node Tab Stops, Implicit Line Breaks, Sentences, Text
4680 @subsection Tab Stops
4681 @cindex tab stops
4682 @cindex stops, tabulator
4683 @cindex tab character
4684 @cindex character, tabulator
4686 @cindex @acronym{EBCDIC} encoding
4687 @cindex encoding, @acronym{EBCDIC}
4688 @code{gtroff} translates @dfn{tabulator characters}, also called
4689 @dfn{tabs} (normally code point @acronym{ASCII} @code{0x09} or
4690 @acronym{EBCDIC} @code{0x05}), in the input into movements to the next
4691 tabulator stop.  These tab stops are initially located every half inch
4692 across the page.  Using this, simple tables can be made easily.
4693 However, it can often be deceptive as the appearance (and width) of the
4694 text on a terminal and the results from @code{gtroff} can vary greatly.
4696 Also, a possible sticking point is that lines beginning with tab
4697 characters are still filled, again producing unexpected results.  For
4698 example, the following input
4700 @multitable {12345678} {12345678} {12345678} {12345678}
4701 @item
4702 @tab 1 @tab 2 @tab 3
4703 @item
4704 @tab   @tab 4 @tab 5
4705 @end multitable
4707 @noindent
4708 produces
4710 @multitable {12345678} {12345678} {12345678} {12345678} {12345678} {12345678} {12345678}
4711 @item
4712 @tab 1 @tab 2 @tab 3 @tab   @tab 4 @tab 5
4713 @end multitable
4715 @xref{Tabs and Fields}.
4717 @c ---------------------------------------------------------------------
4719 @node Implicit Line Breaks, Input Conventions, Tab Stops, Text
4720 @subsection Implicit Line Breaks
4721 @cindex implicit line breaks
4722 @cindex implicit breaks of lines
4723 @cindex line, implicit breaks
4724 @cindex break, implicit
4725 @cindex line break
4727 An important concept in @code{gtroff} is the @dfn{break}.  When a break
4728 occurs, @code{gtroff} outputs the partially filled line (unjustified),
4729 and resumes collecting and filling text on the next output line.
4731 @cindex blank line
4732 @cindex empty line
4733 @cindex line, blank
4734 @cindex blank line macro (@code{blm})
4735 There are several ways to cause a break in @code{gtroff}.  A blank line
4736 not only causes a break, but it also outputs a one-line vertical space
4737 (effectively a blank line).  Note that this behaviour can be modified
4738 with the blank line macro request @code{blm}.  @xref{Blank Line Traps}.
4740 @cindex fill mode
4741 @cindex mode, fill
4742 A line that begins with a space causes a break and the space is output
4743 at the beginning of the next line.  Note that this space isn't adjusted,
4744 even in fill mode.
4746 The end of file also causes a break -- otherwise the last line of the
4747 document may vanish!
4749 Certain requests also cause breaks, implicitly or explicitly.  This is
4750 discussed in @ref{Manipulating Filling and Adjusting}.
4752 @c ---------------------------------------------------------------------
4754 @node Input Conventions, Input Encodings, Implicit Line Breaks, Text
4755 @subsection Input Conventions
4756 @cindex input conventions
4757 @cindex conventions for input
4759 Since @code{gtroff} does filling automatically, it is traditional in
4760 @code{groff} not to try and type things in as nicely formatted
4761 paragraphs.  These are some conventions commonly used when typing
4762 @code{gtroff} text:
4764 @itemize @bullet
4765 @item
4766 Break lines after punctuation, particularly at the end of a sentence and
4767 in other logical places.  Keep separate phrases on lines by themselves,
4768 as entire phrases are often added or deleted when editing.
4770 @item
4771 Try to keep lines less than 40-60@tie{}characters, to allow space for
4772 inserting more text.
4774 @item
4775 Do not try to do any formatting in a @acronym{WYSIWYG} manner (i.e.,
4776 don't try using spaces to get proper indentation).
4777 @end itemize
4779 @c ---------------------------------------------------------------------
4781 @node Input Encodings,  , Input Conventions, Text
4782 @subsection Input Encodings
4784 Currently, the following input encodings are available.
4786 @table @asis
4787 @item cp1047
4788 @cindex encoding, input, @acronym{EBCDIC}
4789 @cindex @acronym{EBCDIC}, input encoding
4790 @cindex input encoding, @acronym{EBCDIC}
4791 @cindex encoding, input, cp1047
4792 @cindex cp1047, input encoding
4793 @cindex input encoding, cp1047
4794 @cindex IBM cp1047 input encoding
4795 @pindex cp1047.tmac
4796 This input encoding works only on @acronym{EBCDIC} platforms (and vice
4797 versa, the other input encodings don't work with @acronym{EBCDIC}); the
4798 file @file{cp1047.tmac} is by default loaded at start-up.
4800 @item latin-1
4801 @cindex encoding, input, @w{latin-1} (ISO @w{8859-1})
4802 @cindex @w{latin-1} (ISO @w{8859-1}), input encoding
4803 @cindex ISO @w{8859-1} (@w{latin-1}), input encoding
4804 @cindex input encoding, @w{latin-1} (ISO @w{8859-1})
4805 @pindex latin1.tmac
4806 This is the default input encoding on non-@acronym{EBCDIC} platforms;
4807 the file @file{latin1.tmac} is loaded at start-up.
4809 @item latin-2
4810 @cindex encoding, input, @w{latin-2} (ISO @w{8859-2})
4811 @cindex @w{latin-2} (ISO @w{8859-2}), input encoding
4812 @cindex ISO @w{8859-2} (@w{latin-2}), input encoding
4813 @cindex input encoding, @w{latin-2} (ISO @w{8859-2})
4814 @pindex latin2.tmac
4815 To use this encoding, either say @w{@samp{.mso latin2.tmac}} at the very
4816 beginning of your document or use @samp{-mlatin2} as a command line
4817 argument for @code{groff}.
4819 @item latin-5
4820 @cindex encoding, input, @w{latin-5} (ISO @w{8859-9})
4821 @cindex @w{latin-2} (ISO @w{8859-9}), input encoding
4822 @cindex ISO @w{8859-9} (@w{latin-2}), input encoding
4823 @cindex input encoding, @w{latin-2} (ISO @w{8859-9})
4824 @pindex latin2.tmac
4825 For Turkish.  Either say @w{@samp{.mso latin9.tmac}} at the very
4826 beginning of your document or use @samp{-mlatin9} as a command line
4827 argument for @code{groff}.
4829 @item latin-9 (latin-0)
4830 @cindex encoding, input, @w{latin-9} (@w{latin-0}, ISO @w{8859-15})
4831 @cindex @w{latin-9} (@w{latin-0}, ISO @w{8859-15}), input encoding
4832 @cindex ISO @w{8859-15} (@w{latin-9}, @w{latin-0}), input encoding
4833 @cindex input encoding, @w{latin-9} (@w{latin-9}, ISO @w{8859-15})
4834 @pindex latin9.tmac
4835 This encoding is intended (at least in Europe) to replace @w{latin-1}
4836 encoding.  The main difference to @w{latin-1} is that @w{latin-9}
4837 contains the Euro character.  To use this encoding, either say
4838 @w{@samp{.mso latin9.tmac}} at the very beginning of your document or
4839 use @samp{-mlatin9} as a command line argument for @code{groff}.
4840 @end table
4842 Note that it can happen that some input encoding characters are not
4843 available for a particular output device.  For example, saying
4845 @Example
4846 groff -Tlatin1 -mlatin9 ...
4847 @endExample
4849 @noindent
4850 fails if you use the Euro character in the input.  Usually, this
4851 limitation is present only for devices which have a limited set of
4852 output glyphs (e.g.@: @option{-Tascii} and @option{-Tlatin1}); for other
4853 devices it is usually sufficient to install proper fonts which contain
4854 the necessary glyphs.
4856 @pindex freeeuro.pfa
4857 @pindex ec.tmac
4858 Due to the importance of the Euro glyph in Europe, the groff package now
4859 comes with a @sc{PostScript} font called @file{freeeuro.pfa} which
4860 provides various glyph shapes for the Euro.  With other words,
4861 @w{latin-9} encoding is supported for the @option{-Tps} device out of
4862 the box (@w{latin-2} isn't).
4864 By its very nature, @option{-Tutf8} supports all input encodings;
4865 @option{-Tdvi} has support for both @w{latin-2} and @w{latin-9} if the
4866 command line @option{-mec} is used also to load the file @file{ec.tmac}
4867 (which flips to the EC fonts).
4870 @c =====================================================================
4872 @node Measurements, Expressions, Text, gtroff Reference
4873 @section Measurements
4874 @cindex measurements
4875 @cindex scaling indicator
4876 @cindex indicator, scaling
4878 @cindex units of measurement
4879 @cindex basic unit (@code{u})
4880 @cindex machine unit (@code{u})
4881 @cindex measurement unit
4882 @cindex @code{u} unit
4883 @cindex unit, @code{u}
4884 @code{gtroff} (like many other programs) requires numeric parameters to
4885 specify various measurements.  Most numeric parameters@footnote{those
4886 that specify vertical or horizontal motion or a type size} may have a
4887 @dfn{measurement unit} attached.  These units are specified as a single
4888 character which immediately follows the number or expression.  Each of
4889 these units are understood, by @code{gtroff}, to be a multiple of its
4890 @dfn{basic unit}.  So, whenever a different measurement unit is
4891 specified @code{gtroff} converts this into its @dfn{basic units}.  This
4892 basic unit, represented by a @samp{u}, is a device dependent measurement
4893 which is quite small, ranging from 1/75@dmn{th} to 1/72000@dmn{th} of an
4894 inch.  The values may be given as fractional numbers; however,
4895 fractional basic units are always rounded to integers.
4897 Some of the measurement units are completely independent of any of the
4898 current settings (e.g.@: type size) of @code{gtroff}.
4900 @table @code
4901 @item i
4902 @cindex inch unit (@code{i})
4903 @cindex @code{i} unit
4904 @cindex unit, @code{i}
4905 Inches.  An antiquated measurement unit still in use in certain
4906 backwards countries with incredibly low-cost computer equipment.  One
4907 inch is equal to@tie{}2.54@dmn{cm}.
4909 @item c
4910 @cindex centimeter unit (@code{c})
4911 @cindex @code{c} unit
4912 @cindex unit, @code{c}
4913 Centimeters.  One centimeter is equal to@tie{}0.3937@dmn{in}.
4915 @item p
4916 @cindex point unit (@code{p})
4917 @cindex @code{p} unit
4918 @cindex unit, @code{p}
4919 Points.  This is a typesetter's measurement used for measure type size.
4920 It is 72@tie{}points to an inch.
4922 @item P
4923 @cindex pica unit (@code{P})
4924 @cindex @code{P} unit
4925 @cindex unit, @code{P}
4926 Pica.  Another typesetting measurement.  6@tie{}Picas to an inch (and
4927 12@tie{}points to a pica).
4929 @item s
4930 @itemx z
4931 @cindex @code{s} unit
4932 @cindex unit, @code{s}
4933 @cindex @code{z} unit
4934 @cindex unit, @code{z}
4935 @xref{Fractional Type Sizes}, for a discussion of these units.
4937 @item f
4938 @cindex @code{f} unit
4939 @cindex unit, @code{f}
4940 Fractions. Value is 65536.
4941 @xref{Colors}, for usage.
4942 @end table
4944 The other measurements understood by @code{gtroff} depend on settings
4945 currently in effect in @code{gtroff}.  These are very useful for
4946 specifying measurements which should look proper with any size of text.
4948 @table @code
4949 @item m
4950 @cindex em unit (@code{m})
4951 @cindex @code{m} unit
4952 @cindex unit, @code{m}
4953 Ems.  This unit is equal to the current font size in points.  So called
4954 because it is @emph{approximately} the width of the letter@tie{}@samp{m}
4955 in the current font.
4957 @item n
4958 @cindex en unit (@code{n})
4959 @cindex @code{n} unit
4960 @cindex unit, @code{n}
4961 Ens.  In @code{groff}, this is half of an em.
4963 @item v
4964 @cindex vertical space unit (@code{v})
4965 @cindex space, vertical, unit (@code{v})
4966 @cindex @code{v} unit
4967 @cindex unit, @code{v}
4968 Vertical space.  This is equivalent to the current line spacing.
4969 @xref{Sizes}, for more information about this.
4971 @item M
4972 @cindex @code{M} unit
4973 @cindex unit, @code{M}
4974 100ths of an em.
4975 @end table
4977 @menu
4978 * Default Units::
4979 @end menu
4981 @c ---------------------------------------------------------------------
4983 @node Default Units,  , Measurements, Measurements
4984 @subsection Default Units
4985 @cindex default units
4986 @cindex units, default
4988 Many requests take a default unit.  While this can be helpful at times,
4989 it can cause strange errors in some expressions.  For example, the line
4990 length request expects em units.  Here are several attempts to get a
4991 line length of 3.5@tie{}inches and their results:
4993 @Example
4994 3.5i      @result{}   3.5i
4995 7/2       @result{}   0i
4996 7/2i      @result{}   0i
4997 (7 / 2)u  @result{}   0i
4998 7i/2      @result{}   0.1i
4999 7i/2u     @result{}   3.5i
5000 @endExample
5002 @noindent
5003 Everything is converted to basic units first.  In the above example it
5004 is assumed that 1@dmn{i} equals@tie{}240@dmn{u}, and 1@dmn{m}
5005 equals@tie{}10@dmn{p} (thus 1@dmn{m} equals@tie{}33@dmn{u}).  The value
5006 7@dmn{i}/2 is first handled as 7@dmn{i}/2@dmn{m}, then converted to
5007 1680@dmn{u}/66@dmn{u} which is 25@dmn{u}, and this is approximately
5008 0.1@dmn{i}.  As can be seen, a scaling indicator after a closing
5009 parenthesis is simply ignored.
5011 @cindex measurements, specifying safely
5012 Thus, the safest way to specify measurements is to always attach a
5013 scaling indicator.  If you want to multiply or divide by a certain
5014 scalar value, use @samp{u} as the unit for that value.
5017 @c =====================================================================
5019 @node Expressions, Identifiers, Measurements, gtroff Reference
5020 @section Expressions
5021 @cindex expressions
5023 @code{gtroff} has most arithmetic operators common to other languages:
5025 @itemize @bullet
5026 @item
5027 @cindex arithmetic operators
5028 @cindex operators, arithmetic
5029 @opindex +
5030 @opindex -
5031 @opindex /
5032 @opindex *
5033 @opindex %
5034 Arithmetic: @samp{+} (addition), @samp{-} (subtraction), @samp{/}
5035 (division), @samp{*} (multiplication), @samp{%} (modulo).
5037 @code{gtroff} only provides integer arithmetic.  The internal type used
5038 for computing results is @samp{int}, which is usually a 32@dmn{bit}
5039 signed integer.
5041 @item
5042 @cindex comparison operators
5043 @cindex operators, comparison
5044 @opindex <
5045 @opindex >
5046 @opindex >=
5047 @opindex <=
5048 @opindex =
5049 @opindex ==
5050 Comparison: @samp{<} (less than), @samp{>} (greater than), @samp{<=}
5051 (less than or equal), @samp{>=} (greater than or equal), @samp{=}
5052 (equal), @samp{==} (the same as @samp{=}).
5054 @item
5055 @cindex logical operators
5056 @cindex operators, logical
5057 @opindex &
5058 @ifnotinfo
5059 @opindex :
5060 @end ifnotinfo
5061 @ifinfo
5062 @opindex @r{<colon>}
5063 @end ifinfo
5064 Logical: @samp{&} (logical and), @samp{:} (logical or).
5066 @item
5067 @cindex unary operators
5068 @cindex operators, unary
5069 @opindex -
5070 @opindex +
5071 @opindex !
5072 @cindex @code{if} request, and the @samp{!} operator
5073 @cindex @code{while} request, and the @samp{!} operator
5074 Unary operators: @samp{-} (negating, i.e.@: changing the sign), @samp{+}
5075 (just for completeness; does nothing in expressions), @samp{!} (logical
5076 not; this works only within @code{if} and @code{while}
5077 requests).@footnote{Note that, for example, @samp{!(-1)} evaluates to
5078 `true' because @code{gtroff} treats both negative numbers and zero as
5079 `false'.}  See below for the use of unary operators in motion requests.
5081 @item
5082 @cindex extremum operators (@code{>?}, @code{<?})
5083 @cindex operators, extremum (@code{>?}, @code{<?})
5084 @opindex >?
5085 @opindex <?
5086 Extrema: @samp{>?} (maximum), @samp{<?} (minimum).
5088 Example:
5090 @Example
5091 .nr x 5
5092 .nr y 3
5093 .nr z (\n[x] >? \n[y])
5094 @endExample
5096 @noindent
5097 The register@tie{}@code{z} now contains@tie{}5.
5099 @item
5100 @cindex scaling operator
5101 @cindex operator, scaling
5102 Scaling: @code{(@var{c};@var{e})}.  Evaluate@tie{}@var{e}
5103 using@tie{}@var{c} as the default scaling indicator.  If @var{c} is
5104 missing, ignore scaling indicators in the evaluation of@tie{}@var{e}.
5105 @end itemize
5107 @cindex parentheses
5108 @cindex order of evaluation in expressions
5109 @cindex expression, order of evaluation
5110 @opindex (
5111 @opindex )
5112 Parentheses may be used as in any other language.  However, in
5113 @code{gtroff} they are necessary to ensure order of evaluation.
5114 @code{gtroff} has no operator precedence; expressions are evaluated left
5115 to right.  This means that @code{gtroff} evaluates @samp{3+5*4} as if it
5116 were parenthesized like @samp{(3+5)*4}, not as @samp{3+(5*4)}, as might
5117 be expected.
5119 @cindex @code{+}, and page motion
5120 @cindex @code{-}, and page motion
5121 @cindex motion operators
5122 @cindex operators, motion
5123 For many requests which cause a motion on the page, the unary operators
5124 @samp{+} and @samp{-} work differently if leading an expression.  They
5125 then indicate a motion relative to the current position (down or up,
5126 respectively).
5128 @cindex @code{|}, and page motion
5129 @cindex absolute position operator (@code{|})
5130 @cindex position, absolute, operator (@code{|})
5131 Similarly, a leading @samp{|} operator indicates an absolute position.
5132 For vertical movements, it specifies the distance from the top of the
5133 page; for horizontal movements, it gives the distance from the beginning
5134 of the @emph{input} line.
5136 @cindex @code{bp} request, using @code{+} and@tie{}@code{-}
5137 @cindex @code{in} request, using @code{+} and@tie{}@code{-}
5138 @cindex @code{ll} request, using @code{+} and@tie{}@code{-}
5139 @cindex @code{lt} request, using @code{+} and@tie{}@code{-}
5140 @cindex @code{nm} request, using @code{+} and@tie{}@code{-}
5141 @cindex @code{nr} request, using @code{+} and@tie{}@code{-}
5142 @cindex @code{pl} request, using @code{+} and@tie{}@code{-}
5143 @cindex @code{pn} request, using @code{+} and@tie{}@code{-}
5144 @cindex @code{po} request, using @code{+} and@tie{}@code{-}
5145 @cindex @code{ps} request, using @code{+} and@tie{}@code{-}
5146 @cindex @code{pvs} request, using @code{+} and@tie{}@code{-}
5147 @cindex @code{rt} request, using @code{+} and@tie{}@code{-}
5148 @cindex @code{ti} request, using @code{+} and@tie{}@code{-}
5149 @cindex @code{\H}, using @code{+} and@tie{}@code{-}
5150 @cindex @code{\R}, using @code{+} and@tie{}@code{-}
5151 @cindex @code{\s}, using @code{+} and@tie{}@code{-}
5152 @samp{+} and @samp{-} are also treated differently by the following
5153 requests and escapes: @code{bp}, @code{in}, @code{ll}, @code{lt},
5154 @code{nm}, @code{nr}, @code{pl}, @code{pn}, @code{po}, @code{ps},
5155 @code{pvs}, @code{rt}, @code{ti}, @code{\H}, @code{\R}, and @code{\s}.
5156 Here, leading plus and minus signs indicate increments and decrements.
5158 @xref{Setting Registers}, for some examples.
5160 @Defesc {\\B, ', anything, '}
5161 @cindex numeric expression, valid
5162 @cindex valid numeric expression
5163 Return@tie{}1 if @var{anything} is a valid numeric expression; or@tie{}0
5164 if @var{anything} is empty or not a valid numeric expression.
5165 @endDefesc
5167 @cindex space characters, in expressions
5168 @cindex expressions, and space characters
5169 Due to the way arguments are parsed, spaces are not allowed in
5170 expressions, unless the entire expression is surrounded by parentheses.
5172 @xref{Request and Macro Arguments}, and @ref{Conditionals and Loops}.
5175 @c =====================================================================
5177 @node Identifiers, Embedded Commands, Expressions, gtroff Reference
5178 @section Identifiers
5179 @cindex identifiers
5181 Like any other language, @code{gtroff} has rules for properly formed
5182 @dfn{identifiers}.  In @code{gtroff}, an identifier can be made up of
5183 almost any printable character, with the exception of the following
5184 characters:
5186 @itemize @bullet
5187 @item
5188 @cindex whitespace characters
5189 @cindex newline character
5190 @cindex character, whitespace
5191 Whitespace characters (spaces, tabs, and newlines).
5193 @item
5194 @cindex character, backspace
5195 @cindex backspace character
5196 @cindex @acronym{EBCDIC} encoding of backspace
5197 Backspace (@acronym{ASCII}@tie{}@code{0x08} or
5198 @acronym{EBCDIC}@tie{}@code{0x16}) and character code @code{0x01}.
5200 @item
5201 @cindex invalid input characters
5202 @cindex input characters, invalid
5203 @cindex characters, invalid input
5204 @cindex Unicode
5205 The following input characters are invalid and are ignored if
5206 @code{groff} runs on a machine based on @acronym{ASCII}, causing a
5207 warning message of type @samp{input} (see @ref{Debugging}, for more
5208 details): @code{0x00}, @code{0x0B}, @code{0x0D}-@code{0x1F},
5209 @code{0x80}-@code{0x9F}.
5211 And here are the invalid input characters if @code{groff} runs on an
5212 @acronym{EBCDIC} host: @code{0x00}, @code{0x08}, @code{0x09},
5213 @code{0x0B}, @code{0x0D}-@code{0x14}, @code{0x17}-@code{0x1F},
5214 @code{0x30}-@code{0x3F}.
5216 Currently, some of these reserved codepoints are used internally, thus
5217 making it non-trivial to extend @code{gtroff} to cover Unicode or other
5218 character sets and encodings which use characters of these ranges.
5220 Note that invalid characters are removed before parsing; an identifier
5221 @code{foo}, followed by an invalid character, followed by @code{bar} is
5222 treated as @code{foobar}.
5223 @end itemize
5225 For example, any of the following is valid.
5227 @Example
5231 end-list
5233 @endExample
5235 @cindex @code{]}, as part of an identifier
5236 @noindent
5237 Note that identifiers longer than two characters with a closing bracket
5238 (@samp{]}) in its name can't be accessed with escape sequences which
5239 expect an identifier as a parameter.  For example, @samp{\[foo]]}
5240 accesses the glyph @samp{foo}, followed by @samp{]}, whereas
5241 @samp{\C'foo]'} really asks for glyph @samp{foo]}.
5243 @cindex @code{refer}, and macro names starting with @code{[} or @code{]}
5244 @cindex @code{[}, macro names starting with, and @code{refer}
5245 @cindex @code{]}, macro names starting with, and @code{refer}
5246 @cindex macro names, starting with @code{[} or @code{]}, and @code{refer}
5247 To avoid problems with the @code{refer} preprocessor, macro names should
5248 not start with @samp{[} or @samp{]}.  Due to backwards compatibility,
5249 everything after @samp{.[} and @samp{.]} is handled as a special
5250 argument to @code{refer}.  For example, @samp{.[foo} makes @code{refer}
5251 to start a reference, using @samp{foo} as a parameter.
5253 @Defesc {\\A, ', ident, '}
5254 Test whether an identifier @var{ident} is valid in @code{gtroff}.  It
5255 expands to the character@tie{}1 or@tie{}0 according to whether its
5256 argument (usually delimited by quotes) is or is not acceptable as the
5257 name of a string, macro, diversion, number register, environment, or
5258 font.  It returns@tie{}0 if no argument is given.  This is useful for
5259 looking up user input in some sort of associative table.
5261 @Example
5262 \A'end-list'
5263     @result{} 1
5264 @endExample
5265 @endDefesc
5267 @xref{Escapes}, for details on parameter delimiting characters.
5269 Identifiers in @code{gtroff} can be any length, but, in some contexts,
5270 @code{gtroff} needs to be told where identifiers end and text begins
5271 (and in different ways depending on their length):
5273 @itemize @bullet
5274 @item
5275 Single character.
5277 @cindex @code{(}, starting a two-character identifier
5278 @item
5279 Two characters.  Must be prefixed with @samp{(} in some situations.
5281 @cindex @code{[}, starting an identifier
5282 @cindex @code{]}, ending an identifier
5283 @item
5284 Arbitrary length (@code{gtroff} only).  Must be bracketed with @samp{[}
5285 and@tie{}@samp{]} in some situations.  Any length identifier can be put
5286 in brackets.
5287 @end itemize
5289 @cindex undefined identifiers
5290 @cindex identifiers, undefined
5291 Unlike many other programming languages, undefined identifiers are
5292 silently ignored or expanded to nothing.  When @code{gtroff} finds an
5293 undefined identifier, it emits a warning, doing the following:
5295 @itemize @bullet
5296 @item
5297 If the identifier is a string, macro, or diversion, @code{gtroff}
5298 defines it as empty.
5300 @item
5301 If the identifier is a number register, @code{gtroff} defines it with a
5302 value of@tie{}0.
5303 @end itemize
5305 @xref{Warnings}., @ref{Interpolating Registers}, and @ref{Strings}.
5307 Note that macros, strings, and diversions share the same name space.
5309 @Example
5310 .de xxx
5311 .  nop foo
5314 .di xxx
5319 .xxx
5320     @result{} bar
5321 @endExample
5323 @noindent
5324 As can be seen in the previous example, @code{gtroff} reuses the
5325 identifier @samp{xxx}, changing it from a macro to a diversion.  No
5326 warning is emitted!  The contents of the first macro definition is lost.
5328 @xref{Interpolating Registers}, and @ref{Strings}.
5331 @c =====================================================================
5333 @node Embedded Commands, Registers, Identifiers, gtroff Reference
5334 @section Embedded Commands
5335 @cindex embedded commands
5336 @cindex commands, embedded
5338 Most documents need more functionality beyond filling, adjusting and
5339 implicit line breaking.  In order to gain further functionality,
5340 @code{gtroff} allows commands to be embedded into the text, in two ways.
5342 The first is a @dfn{request} which takes up an entire line, and does
5343 some large-scale operation (e.g.@: break lines, start new pages).
5345 The other is an @dfn{escape} which can be usually embedded anywhere in
5346 the text; most requests can accept it even as an argument.  Escapes
5347 generally do more minor operations like sub- and superscripts, print a
5348 symbol, etc.
5350 @menu
5351 * Requests::
5352 * Macros::
5353 * Escapes::
5354 @end menu
5356 @c ---------------------------------------------------------------------
5358 @node Requests, Macros, Embedded Commands, Embedded Commands
5359 @subsection Requests
5360 @cindex requests
5362 @cindex control character (@code{.})
5363 @cindex character, control (@code{.})
5364 @cindex no-break control character (@code{'})
5365 @cindex character, no-break control (@code{'})
5366 @cindex control character, no-break (@code{'})
5367 A request line begins with a control character, which is either a single
5368 quote (@samp{'}, the @dfn{no-break control character}) or a period
5369 (@samp{.}, the normal @dfn{control character}).  These can be changed;
5370 see @ref{Character Translations}, for details.  After this there may be
5371 optional tabs or spaces followed by an identifier which is the name of
5372 the request.  This may be followed by any number of space-separated
5373 arguments (@emph{no} tabs here).
5375 @cindex structuring source code of documents or macro packages
5376 @cindex documents, structuring the source code
5377 @cindex macro packages, structuring the source code
5378 Since a control character followed by whitespace only is ignored, it is
5379 common practice to use this feature for structuring the source code of
5380 documents or macro packages.
5382 @Example
5383 .de foo
5384 .  tm This is foo.
5388 .de bar
5389 .  tm This is bar.
5391 @endExample
5393 @cindex blank line
5394 @cindex blank line macro (@code{blm})
5395 Another possibility is to use the blank line macro request @code{blm} by
5396 assigning an empty macro to it.
5398 @Example
5399 .de do-nothing
5401 .blm do-nothing  \" activate blank line macro
5403 .de foo
5404 .  tm This is foo.
5408 .de bar
5409 .  tm This is bar.
5412 .blm             \" deactivate blank line macro
5413 @endExample
5415 @xref{Blank Line Traps}.
5417 @cindex zero width space character (@code{\&})
5418 @cindex character, zero width space (@code{\&})
5419 @cindex space character, zero width (@code{\&})
5420 @cindex @code{\&}, escaping control characters
5421 To begin a line with a control character without it being interpreted,
5422 precede it with @code{\&}.  This represents a zero width space, which
5423 means it does not affect the output.
5425 In most cases the period is used as a control character.  Several
5426 requests cause a break implicitly; using the single quote control
5427 character prevents this.
5429 @Defreg {.br}
5430 A read-only number register which is set to@tie{}1 if a macro is called
5431 with the normal control character (as defined with the @code{cc}
5432 request), and set to@tie{}0 otherwise.
5434 @cindex modifying requests
5435 @cindex requests, modifying
5436 This allows to reliably modify requests.
5438 @Example
5439 .als bp*orig bp
5440 .de bp
5441 .  tm before bp
5442 .  ie \\n[.br] .bp*orig
5443 .  el 'bp*orig
5444 .  tm after bp
5446 @endExample
5448 Using this register outside of a macro makes no sense (it always returns
5449 zero in such cases).
5451 If a macro is called as a string (this is, using @code{\*}), the value
5452 of the @code{.br} register is inherited from the calling macro.
5453 @endDefreg
5455 @menu
5456 * Request and Macro Arguments::
5457 @end menu
5459 @node Request and Macro Arguments,  , Requests, Requests
5460 @subsubsection Request and Macro Arguments
5461 @cindex request arguments
5462 @cindex macro arguments
5463 @cindex arguments to requests and macros
5465 @cindex tabs, and macro arguments
5466 @cindex macro arguments, and tabs
5467 @cindex arguments to macros, and tabs
5468 Arguments to requests and macros are processed much like the shell:
5469 The line is split into arguments according to
5470 spaces.@footnote{Plan@tie{}9's @code{troff} implementation also allows
5471 tabs for argument separation -- @code{gtroff} intentionally doesn't
5472 support this.}
5474 @cindex spaces, in a macro argument
5475 An argument to a macro which is intended to contain spaces can either be
5476 enclosed in double quotes, or have the spaces @dfn{escaped} with
5477 backslashes.  This is @emph{not} true for requests.
5479 Here are a few examples for a hypothetical macro @code{uh}:
5481 @Example
5482 .uh The Mouse Problem
5483 .uh "The Mouse Problem"
5484 .uh The\ Mouse\ Problem
5485 @endExample
5487 @cindex @code{\~}, difference to @code{\@key{SP}}
5488 @cindex @code{\@key{SP}}, difference to @code{\~}
5489 @noindent
5490 The first line is the @code{uh} macro being called with 3 arguments,
5491 @samp{The}, @samp{Mouse}, and @samp{Problem}.  The latter two have the
5492 same effect of calling the @code{uh} macro with one argument, @samp{The
5493 Mouse Problem}.@footnote{The last solution, i.e., using escaped spaces,
5494 is ``classical'' in the sense that it can be found in most @code{troff}
5495 documents.  Nevertheless, it is not optimal in all situations, since
5496 @w{@samp{\ }} inserts a fixed-width, non-breaking space character which
5497 can't stretch.  @code{gtroff} provides a different command @code{\~} to
5498 insert a stretchable, non-breaking space.}
5500 @cindex @code{"}, in a macro argument
5501 @cindex double quote, in a macro argument
5502 A double quote which isn't preceded by a space doesn't start a macro
5503 argument.  If not closing a string, it is printed literally.
5505 For example,
5507 @Example
5508 .xxx a" "b c" "de"fg"
5509 @endExample
5511 @noindent
5512 has the arguments @samp{a"}, @w{@samp{b c}}, @samp{de}, and @samp{fg"}.
5513 Don't rely on this obscure behaviour!
5515 There are two possibilities to get a double quote reliably.
5517 @itemize @bullet
5518 @item
5519 Enclose the whole argument with double quotes and use two consecutive
5520 double quotes to represent a single one.  This traditional solution has
5521 the disadvantage that double quotes don't survive argument expansion
5522 again if called in compatibility mode (using the @option{-C} option of
5523 @code{groff}):
5525 @Example
5526 .de xx
5527 .  tm xx: `\\$1' `\\$2' `\\$3'
5529 .  yy "\\$1" "\\$2" "\\$3"
5531 .de yy
5532 .  tm yy: `\\$1' `\\$2' `\\$3'
5534 .xx A "test with ""quotes""" .
5535     @result{} xx: `A' `test with "quotes"' `.'
5536     @result{} yy: `A' `test with ' `quotes""'
5537 @endExample
5539 @noindent
5540 If not in compatibility mode, you get the expected result
5542 @Example
5543 xx: `A' `test with "quotes"' `.'
5544 yy: `A' `test with "quotes"' `.'
5545 @endExample
5547 @noindent
5548 since @code{gtroff} preserves the input level.
5550 @item
5551 Use the double quote glyph @code{\(dq}.  This works with and without
5552 compatibility mode enabled since @code{gtroff} doesn't convert
5553 @code{\(dq} back to a double quote input character.
5555 Note that this method won't work with @acronym{UNIX} @code{troff} in
5556 general since the glyph `dq' isn't defined normally.
5557 @end itemize
5559 @cindex @code{ds} request, and double quotes
5560 Double quotes in the @code{ds} request are handled differently.
5561 @xref{Strings}, for more details.
5563 @c ---------------------------------------------------------------------
5565 @node Macros, Escapes, Requests, Embedded Commands
5566 @subsection Macros
5567 @cindex macros
5569 @code{gtroff} has a @dfn{macro} facility for defining a series of lines
5570 which can be invoked by name.  They are called in the same manner as
5571 requests -- arguments also may be passed basically in the same manner.
5573 @xref{Writing Macros}, and @ref{Request and Macro Arguments}.
5575 @c ---------------------------------------------------------------------
5577 @node Escapes,  , Macros, Embedded Commands
5578 @subsection Escapes
5579 @cindex escapes
5581 Escapes may occur anywhere in the input to @code{gtroff}.  They usually
5582 begin with a backslash and are followed by a single character which
5583 indicates the function to be performed.  The escape character can be
5584 changed; see @ref{Character Translations}.
5586 Escape sequences which require an identifier as a parameter accept three
5587 possible syntax forms.
5589 @itemize @bullet
5590 @item
5591 The next single character is the identifier.
5593 @cindex @code{(}, starting a two-character identifier
5594 @item
5595 If this single character is an opening parenthesis, take the following
5596 two characters as the identifier.  Note that there is no closing
5597 parenthesis after the identifier.
5599 @cindex @code{[}, starting an identifier
5600 @cindex @code{]}, ending an identifier
5601 @item
5602 If this single character is an opening bracket, take all characters
5603 until a closing bracket as the identifier.
5604 @end itemize
5606 @noindent
5607 Examples:
5609 @Example
5611 \n(XX
5612 \*[TeX]
5613 @endExample
5615 @cindex @code{'}, delimiting arguments
5616 @cindex argument delimiting characters
5617 @cindex characters, argument delimiting
5618 @cindex delimiting characters for arguments
5619 Other escapes may require several arguments and/or some special format.
5620 In such cases the argument is traditionally enclosed in single quotes
5621 (and quotes are always used in this manual for the definitions of escape
5622 sequences).  The enclosed text is then processed according to what that
5623 escape expects.  Example:
5625 @Example
5626 \l'1.5i\(bu'
5627 @endExample
5629 @cindex @code{\o}, possible quote characters
5630 @cindex @code{\b}, possible quote characters
5631 @cindex @code{\X}, possible quote characters
5632 Note that the quote character can be replaced with any other character
5633 which does not occur in the argument (even a newline or a space
5634 character) in the following escapes: @code{\o}, @code{\b}, and
5635 @code{\X}.  This makes e.g.
5637 @Example
5638 A caf
5643 in Paris
5644   @result{} A café in Paris
5645 @endExample
5647 @noindent
5648 possible, but it is better not to use this feature to avoid confusion.
5650 @cindex @code{\%}, used as delimiter
5651 @cindex @code{\@key{SP}}, used as delimiter
5652 @cindex @code{\|}, used as delimiter
5653 @cindex @code{\^}, used as delimiter
5654 @cindex @code{\@{}, used as delimiter
5655 @cindex @code{\@}}, used as delimiter
5656 @cindex @code{\'}, used as delimiter
5657 @cindex @code{\`}, used as delimiter
5658 @cindex @code{\-}, used as delimiter
5659 @cindex @code{\_}, used as delimiter
5660 @cindex @code{\!}, used as delimiter
5661 @cindex @code{\?}, used as delimiter
5662 @cindex @code{\)}, used as delimiter
5663 @cindex @code{\/}, used as delimiter
5664 @cindex @code{\,}, used as delimiter
5665 @cindex @code{\&}, used as delimiter
5666 @ifnotinfo
5667 @cindex @code{\:}, used as delimiter
5668 @end ifnotinfo
5669 @ifinfo
5670 @cindex @code{\@r{<colon>}}, used as delimiter
5671 @end ifinfo
5672 @cindex @code{\~}, used as delimiter
5673 @cindex @code{\0}, used as delimiter
5674 @cindex @code{\a}, used as delimiter
5675 @cindex @code{\c}, used as delimiter
5676 @cindex @code{\d}, used as delimiter
5677 @cindex @code{\e}, used as delimiter
5678 @cindex @code{\E}, used as delimiter
5679 @cindex @code{\p}, used as delimiter
5680 @cindex @code{\r}, used as delimiter
5681 @cindex @code{\t}, used as delimiter
5682 @cindex @code{\u}, used as delimiter
5683 The following escapes sequences (which are handled similarly to
5684 characters since they don't take a parameter) are also allowed as
5685 delimiters: @code{\%}, @w{@samp{\ }}, @code{\|}, @code{\^}, @code{\@{},
5686 @code{\@}}, @code{\'}, @code{\`}, @code{\-}, @code{\_}, @code{\!},
5687 @code{\?}, @code{\)}, @code{\/}, @code{\,}, @code{\&}, @code{\:},
5688 @code{\~}, @code{\0}, @code{\a}, @code{\c}, @code{\d}, @code{\e},
5689 @code{\E}, @code{\p}, @code{\r}, @code{\t}, and @code{\u}.  Again, don't
5690 use these if possible.
5692 @cindex @code{\A}, allowed delimiters
5693 @cindex @code{\B}, allowed delimiters
5694 @cindex @code{\Z}, allowed delimiters
5695 @cindex @code{\C}, allowed delimiters
5696 @cindex @code{\w}, allowed delimiters
5697 No newline characters as delimiters are allowed in the following
5698 escapes: @code{\A}, @code{\B}, @code{\Z}, @code{\C}, and @code{\w}.
5700 @cindex @code{\D}, allowed delimiters
5701 @cindex @code{\h}, allowed delimiters
5702 @cindex @code{\H}, allowed delimiters
5703 @cindex @code{\l}, allowed delimiters
5704 @cindex @code{\L}, allowed delimiters
5705 @cindex @code{\N}, allowed delimiters
5706 @cindex @code{\R}, allowed delimiters
5707 @cindex @code{\s}, allowed delimiters
5708 @cindex @code{\S}, allowed delimiters
5709 @cindex @code{\v}, allowed delimiters
5710 @cindex @code{\x}, allowed delimiters
5711 Finally, the escapes @code{\D}, @code{\h}, @code{\H}, @code{\l},
5712 @code{\L}, @code{\N}, @code{\R}, @code{\s}, @code{\S}, @code{\v}, and
5713 @code{\x} can't use the following characters as delimiters:
5715 @itemize @bullet
5716 @item
5717 @cindex numbers, and delimiters
5718 @cindex digits, and delimiters
5719 The digits @code{0}-@code{9}.
5721 @item
5722 @cindex operators, as delimiters
5723 @cindex @code{+}, as delimiter
5724 @cindex @code{-}, as delimiter
5725 @cindex @code{/}, as delimiter
5726 @cindex @code{*}, as delimiter
5727 @cindex @code{%}, as delimiter
5728 @cindex @code{<}, as delimiter
5729 @cindex @code{>}, as delimiter
5730 @cindex @code{=}, as delimiter
5731 @cindex @code{&}, as delimiter
5732 @ifnotinfo
5733 @cindex @code{:}, as delimiter
5734 @end ifnotinfo
5735 @ifinfo
5736 @cindex <colon>, as delimiter
5737 @end ifinfo
5738 @cindex @code{(}, as delimiter
5739 @cindex @code{)}, as delimiter
5740 @cindex @code{.}, as delimiter
5741 The (single-character) operators @samp{+-/*%<>=&:().}.
5743 @item
5744 @cindex space character
5745 @cindex character, space
5746 @cindex tab character
5747 @cindex character, tab
5748 @cindex newline character
5749 @cindex character, newline
5750 The space, tab, and newline characters.
5752 @item
5753 @cindex @code{\%}, used as delimiter
5754 @ifnotinfo
5755 @cindex @code{\:}, used as delimiter
5756 @end ifnotinfo
5757 @ifinfo
5758 @cindex @code{\@r{<colon>}}, used as delimiter
5759 @end ifinfo
5760 @cindex @code{\@{}, used as delimiter
5761 @cindex @code{\@}}, used as delimiter
5762 @cindex @code{\'}, used as delimiter
5763 @cindex @code{\`}, used as delimiter
5764 @cindex @code{\-}, used as delimiter
5765 @cindex @code{\_}, used as delimiter
5766 @cindex @code{\!}, used as delimiter
5767 @cindex @code{\/}, used as delimiter
5768 @cindex @code{\c}, used as delimiter
5769 @cindex @code{\e}, used as delimiter
5770 @cindex @code{\p}, used as delimiter
5771 All escape sequences except @code{\%}, @code{\:}, @code{\@{},
5772 @code{\@}}, @code{\'}, @code{\`}, @code{\-}, @code{\_}, @code{\!},
5773 @code{\/}, @code{\c}, @code{\e}, and @code{\p}.
5774 @end itemize
5776 @cindex printing backslash (@code{\\}, @code{\e}, @code{\E}, @code{\[rs]})
5777 @cindex backslash, printing (@code{\\}, @code{\e}, @code{\E}, @code{\[rs]})
5778 To have a backslash (actually, the current escape character) appear in
5779 the output several escapes are defined: @code{\\}, @code{\e} or
5780 @code{\E}.  These are very similar, and only differ with respect to
5781 being used in macros or diversions.  @xref{Character Translations}, for
5782 an exact description of those escapes.
5784 @xref{Implementation Differences}, @ref{Copy-in Mode}, and
5785 @ref{Diversions}, @ref{Identifiers}, for more information.
5787 @menu
5788 * Comments::
5789 @end menu
5791 @node Comments,  , Escapes, Escapes
5792 @subsubsection Comments
5793 @cindex comments
5795 Probably one of the most@footnote{Unfortunately, this is a lie.  But
5796 hopefully future @code{gtroff} hackers will believe it @code{:-)}}
5797 common forms of escapes is the comment.
5799 @Defesc {\\", , , }
5800 Start a comment.  Everything to the end of the input line is ignored.
5802 This may sound simple, but it can be tricky to keep the comments from
5803 interfering with the appearance of the final output.
5805 @cindex @code{ds}, @code{ds1} requests, and comments
5806 @cindex @code{as}, @code{as1} requests, and comments
5807 If the escape is to the right of some text or a request, that portion of
5808 the line is ignored, but the space leading up to it is noticed by
5809 @code{gtroff}.  This only affects the @code{ds} and @code{as} request
5810 and its variants.
5812 @cindex tabs, before comments
5813 @cindex comments, lining up with tabs
5814 One possibly irritating idiosyncracy is that tabs must not be used to
5815 line up comments.  Tabs are not treated as whitespace between the
5816 request and macro arguments.
5818 @cindex undefined request
5819 @cindex request, undefined
5820 A comment on a line by itself is treated as a blank line, because after
5821 eliminating the comment, that is all that remains:
5823 @Example
5824 Test
5825 \" comment
5826 Test
5827 @endExample
5829 @noindent
5830 produces
5832 @Example
5833 Test
5835 Test
5836 @endExample
5838 To avoid this, it is common to start the line with @code{.\"} which
5839 causes the line to be treated as an undefined request and thus ignored
5840 completely.
5842 @cindex @code{'}, as a comment
5843 Another commenting scheme seen sometimes is three consecutive single
5844 quotes (@code{'''}) at the beginning of a line.  This works, but
5845 @code{gtroff} gives a warning about an undefined macro (namely
5846 @code{''}), which is harmless, but irritating.
5847 @endDefesc
5849 @Defesc {\\#, , , }
5850 To avoid all this, @code{gtroff} has a new comment mechanism using the
5851 @code{\#} escape.  This escape works the same as @code{\"} except that
5852 the newline is also ignored:
5854 @Example
5855 Test
5856 \# comment
5857 Test
5858 @endExample
5860 @noindent
5861 produces
5863 @Example
5864 Test Test
5865 @endExample
5867 @noindent
5868 as expected.
5869 @endDefesc
5871 @Defreq {ig, [@Var{end}]}
5872 Ignore all input until @code{gtroff} encounters the macro named
5873 @code{.}@var{end} on a line by itself (or @code{..} if @var{end} is not
5874 specified).  This is useful for commenting out large blocks of text:
5876 @Example
5877 text text text...
5879 This is part of a large block
5880 of text that has been
5881 temporarily(?) commented out.
5883 We can restore it simply by removing
5884 the .ig request and the ".." at the
5885 end of the block.
5887 More text text text...
5888 @endExample
5890 @noindent
5891 produces
5893 @Example
5894 text text text@dots{}  More text text text@dots{}
5895 @endExample
5897 @noindent
5898 Note that the commented-out block of text does not cause a break.
5900 @cindex @code{ig} request, and copy-in mode
5901 @cindex copy-in mode, and @code{ig} request
5902 @cindex mode, copy-in, and @code{ig} request
5903 @cindex @code{ig} request, and auto-increment
5904 @cindex auto-increment, and @code{ig} request
5905 The input is read in copy-mode; auto-incremented registers @emph{are}
5906 affected (@pxref{Auto-increment}).
5907 @endDefreq
5910 @c =====================================================================
5912 @node Registers, Manipulating Filling and Adjusting, Embedded Commands, gtroff Reference
5913 @section Registers
5914 @cindex registers
5916 Numeric variables in @code{gtroff} are called @dfn{registers}.  There
5917 are a number of built-in registers, supplying anything from the date to
5918 details of formatting parameters.
5920 @xref{Identifiers}, for details on register identifiers.
5922 @menu
5923 * Setting Registers::
5924 * Interpolating Registers::
5925 * Auto-increment::
5926 * Assigning Formats::
5927 * Built-in Registers::
5928 @end menu
5930 @c ---------------------------------------------------------------------
5932 @node Setting Registers, Interpolating Registers, Registers, Registers
5933 @subsection Setting Registers
5934 @cindex setting registers (@code{nr}, @code{\R})
5935 @cindex registers, setting (@code{nr}, @code{\R})
5937 Define or set registers using the @code{nr} request or the @code{\R}
5938 escape.
5940 @DefreqList {nr, ident value}
5941 @DefescListEnd {\\R, ', ident value, '}
5942 Set number register @var{ident} to @var{value}.  If @var{ident} doesn't
5943 exist, @code{gtroff} creates it.
5945 The argument to @code{\R} usually has to be enclosed in quotes.
5946 @xref{Escapes}, for details on parameter delimiting characters.
5948 The @code{\R} escape doesn't produce an input token in @code{gtroff};
5949 with other words, it vanishes completely after @code{gtroff} has
5950 processed it.
5951 @endDefreq
5953 For example, the following two lines are equivalent:
5955 @Example
5956 .nr a (((17 + (3 * 4))) % 4)
5957 \R'a (((17 + (3 * 4))) % 4)'
5958     @result{} 1
5959 @endExample
5961 Both @code{nr} and @code{\R} have two additional special forms to
5962 increment or decrement a register.
5964 @DefreqList {nr, ident @t{+}@Var{value}}
5965 @DefreqItem {nr, ident @t{-}@Var{value}}
5966 @DefescItem {\\R, ', ident @t{+}value, '}
5967 @DefescListEnd {\\R, ', ident @t{-}value, '}
5968 Increment (decrement) register @var{ident} by @var{value}.
5970 @Example
5971 .nr a 1
5972 .nr a +1
5974     @result{} 2
5975 @endExample
5977 @cindex negating register values
5978 To assign the negated value of a register to another register, some care
5979 must be taken to get the desired result:
5981 @Example
5982 .nr a 7
5983 .nr b 3
5984 .nr a -\nb
5986     @result{} 4
5987 .nr a (-\nb)
5989     @result{} -3
5990 @endExample
5992 @noindent
5993 The surrounding parentheses prevent the interpretation of the minus sign
5994 as a decrementing operator.  An alternative is to start the assignment
5995 with a @samp{0}:
5997 @Example
5998 .nr a 7
5999 .nr b -3
6000 .nr a \nb
6002     @result{} 4
6003 .nr a 0\nb
6005     @result{} -3
6006 @endExample
6007 @endDefreq
6009 @Defreq {rr, ident}
6010 @cindex removing number register (@code{rr})
6011 @cindex number register, removing (@code{rr})
6012 @cindex register, removing (@code{rr})
6013 Remove number register @var{ident}.  If @var{ident} doesn't exist, the
6014 request is ignored.
6015 @endDefreq
6017 @Defreq {rnn, ident1 ident2}
6018 @cindex renaming number register (@code{rnn})
6019 @cindex number register, renaming (@code{rnn})
6020 @cindex register, renaming (@code{rnn})
6021 Rename number register @var{ident1} to @var{ident2}.  If either
6022 @var{ident1} or @var{ident2} doesn't exist, the request is ignored.
6023 @endDefreq
6025 @Defreq {aln, ident1 ident2}
6026 @cindex alias, number register, creating (@code{aln})
6027 @cindex creating alias, for number register (@code{aln})
6028 @cindex number register, creating alias (@code{aln})
6029 @cindex register, creating alias (@code{aln})
6030 Create an alias @var{ident1} for a number register @var{ident2}.  The
6031 new name and the old name are exactly equivalent.  If @var{ident1} is
6032 undefined, a warning of type @samp{reg} is generated, and the request is
6033 ignored.  @xref{Debugging}, for information about warnings.
6034 @endDefreq
6036 @c ---------------------------------------------------------------------
6038 @node Interpolating Registers, Auto-increment, Setting Registers, Registers
6039 @subsection Interpolating Registers
6040 @cindex interpolating registers (@code{\n})
6041 @cindex registers, interpolating (@code{\n})
6043 Numeric registers can be accessed via the @code{\n} escape.
6045 @DefescList {\\n, , i, }
6046 @DefescItem {\\n, @Lparen{}, id, }
6047 @DefescListEnd {\\n, @Lbrack{}, ident, @Rbrack{}}
6048 @cindex nested assignments
6049 @cindex assignments, nested
6050 @cindex indirect assignments
6051 @cindex assignments, indirect
6052 Interpolate number register with name @var{ident} (one-character
6053 name@tie{}@var{i}, two-character name @var{id}).  This means that the
6054 value of the register is expanded in-place while @code{gtroff} is
6055 parsing the input line.  Nested assignments (also called indirect
6056 assignments) are possible.
6058 @Example
6059 .nr a 5
6060 .nr as \na+\na
6061 \n(as
6062     @result{} 10
6063 @endExample
6065 @Example
6066 .nr a1 5
6067 .nr ab 6
6068 .ds str b
6069 .ds num 1
6070 \n[a\n[num]]
6071     @result{} 5
6072 \n[a\*[str]]
6073     @result{} 6
6074 @endExample
6075 @endDefesc
6077 @c ---------------------------------------------------------------------
6079 @node Auto-increment, Assigning Formats, Interpolating Registers, Registers
6080 @subsection Auto-increment
6081 @cindex auto-increment
6082 @cindex increment, automatic
6084 Number registers can also be auto-incremented and auto-decremented.  The
6085 increment or decrement value can be specified with a third argument to
6086 the @code{nr} request or @code{\R} escape.
6088 @Defreq {nr, ident value incr}
6089 @cindex @code{\R}, difference to @code{nr}
6090 Set number register @var{ident} to @var{value}; the increment for
6091 auto-incrementing is set to @var{incr}.  Note that the @code{\R} escape
6092 doesn't support this notation.
6093 @endDefreq
6095 To activate auto-incrementing, the escape @code{\n} has a special syntax
6096 form.
6098 @DefescList {\\n, +, i, }
6099 @DefescItem {\\n, -, i, }
6100 @DefescItem {\\n, @Lparen{}+, id, }
6101 @DefescItem {\\n, @Lparen{}-, id, }
6102 @DefescItem {\\n, +@Lparen{}, id, }
6103 @DefescItem {\\n, -@Lparen{}, id, }
6104 @DefescItem {\\n, @Lbrack{}+, ident, @Rbrack{}}
6105 @DefescItem {\\n, @Lbrack{}-, ident, @Rbrack{}}
6106 @DefescItem {\\n, +@Lbrack{}, ident, @Rbrack{}}
6107 @DefescListEnd {\\n, -@Lbrack{}, ident, @Rbrack{}}
6108 Before interpolating, increment or decrement @var{ident} (one-character
6109 name@tie{}@var{i}, two-character name @var{id}) by the auto-increment
6110 value as specified with the @code{nr} request (or the @code{\R} escape).
6111 If no auto-increment value has been specified, these syntax forms are
6112 identical to @code{\n}.
6113 @endDefesc
6115 For example,
6117 @Example
6118 .nr a 0 1
6119 .nr xx 0 5
6120 .nr foo 0 -2
6121 \n+a, \n+a, \n+a, \n+a, \n+a
6123 \n-(xx, \n-(xx, \n-(xx, \n-(xx, \n-(xx
6125 \n+[foo], \n+[foo], \n+[foo], \n+[foo], \n+[foo]
6126 @endExample
6128 @noindent
6129 produces
6131 @Example
6132 1, 2, 3, 4, 5
6133 -5, -10, -15, -20, -25
6134 -2, -4, -6, -8, -10
6135 @endExample
6137 @cindex increment value without changing the register
6138 @cindex value, incrementing without changing the register
6139 To change the increment value without changing the value of a register
6140 (@var{a} in the example), the following can be used:
6142 @Example
6143 .nr a \na 10
6144 @endExample
6146 @c ---------------------------------------------------------------------
6148 @node Assigning Formats, Built-in Registers, Auto-increment, Registers
6149 @subsection Assigning Formats
6150 @cindex assigning formats (@code{af})
6151 @cindex formats, assigning (@code{af})
6153 When a register is used, it is always textually replaced (or
6154 interpolated) with a representation of that number.  This output format
6155 can be changed to a variety of formats (numbers, Roman numerals, etc.).
6156 This is done using the @code{af} request.
6158 @Defreq {af, ident format}
6159 Change the output format of a number register.  The first argument
6160 @var{ident} is the name of the number register to be changed, and the
6161 second argument @var{format} is the output format.  The following output
6162 formats are available:
6164 @table @code
6165 @item 1
6166 Decimal arabic numbers.  This is the default format: 0, 1, 2,
6167 3,@tie{}@enddots{}
6169 @item 0@dots{}0
6170 Decimal numbers with as many digits as specified.  So, @samp{00} would
6171 result in printing numbers as 01, 02, 03,@tie{}@enddots{}
6173 In fact, any digit instead of zero does work; @code{gtroff} only counts
6174 how many digits are specified.  As a consequence, @code{af}'s default
6175 format @samp{1} could be specified as @samp{0} also (and exactly this is
6176 returned by the @code{\g} escape, see below).
6178 @item I
6179 @cindex Roman numerals
6180 @cindex numerals, Roman
6181 Upper-case Roman numerals: 0, I, II, III, IV,@tie{}@enddots{}
6183 @item i
6184 Lower-case Roman numerals: 0, i, ii, iii, iv,@tie{}@enddots{}
6186 @item A
6187 Upper-case letters: 0, A, B, C, @dots{},@tie{}Z, AA, AB,@tie{}@enddots{}
6189 @item a
6190 Lower-case letters: 0, a, b, c, @dots{},@tie{}z, aa, ab,@tie{}@enddots{}
6191 @end table
6193 Omitting the number register format causes a warning of type
6194 @samp{missing}.  @xref{Debugging}, for more details.  Specifying a
6195 nonexistent format causes an error.
6197 The following example produces @samp{10, X, j, 010}:
6199 @Example
6200 .nr a 10
6201 .af a 1           \" the default format
6202 \na,
6203 .af a I
6204 \na,
6205 .af a a
6206 \na,
6207 .af a 001
6209 @endExample
6211 @cindex Roman numerals, maximum and minimum
6212 @cindex maximum values of Roman numerals
6213 @cindex minimum values of Roman numerals
6214 The largest number representable for the @samp{i} and @samp{I} formats
6215 is 39999 (or @minus{}39999); @acronym{UNIX} @code{troff} uses @samp{z}
6216 and @samp{w} to represent 10000 and 5000 in Roman numerals, and so does
6217 @code{gtroff}.  Currently, the correct glyphs of Roman numeral five
6218 thousand and Roman numeral ten thousand (Unicode code points
6219 @code{U+2182} and @code{U+2181}, respectively) are not available.
6221 If @var{ident} doesn't exist, it is created.
6223 @cindex read-only register, changing format
6224 @cindex changing format, and read-only registers
6225 Changing the output format of a read-only register causes an error.  It
6226 is necessary to first copy the register's value to a writeable register,
6227 then apply the @code{af} request to this other register.
6228 @endDefreq
6230 @DefescList {\\g, , i, }
6231 @DefescItem {\\g, @Lparen{}, id, }
6232 @DefescListEnd {\\g, @Lbrack{}, ident, @Rbrack{}}
6233 @cindex format of register (@code{\g})
6234 @cindex register, format (@code{\g})
6235 Return the current format of the specified register @var{ident}
6236 (one-character name@tie{}@var{i}, two-character name @var{id}).  For
6237 example, @samp{\ga} after the previous example would produce the string
6238 @samp{000}.  If the register hasn't been defined yet, nothing is
6239 returned.
6240 @endDefesc
6242 @c ---------------------------------------------------------------------
6244 @node Built-in Registers,  , Assigning Formats, Registers
6245 @subsection Built-in Registers
6246 @cindex built-in registers
6247 @cindex registers, built-in
6249 The following lists some built-in registers which are not described
6250 elsewhere in this manual.  Any register which begins with a @samp{.} is
6251 read-only.  A complete listing of all built-in registers can be found in
6252 @ref{Register Index}.
6254 @table @code
6255 @item \n[.F]
6256 @cindex current input file name register (@code{.F})
6257 @cindex input file name, current, register (@code{.F})
6258 @vindex .F
6259 This string-valued register returns the current input file name.
6261 @item \n[.H]
6262 @cindex horizontal resolution register (@code{.H})
6263 @cindex resolution, horizontal, register (@code{.H})
6264 @vindex .H
6265 Horizontal resolution in basic units.
6267 @item \n[.U]
6268 @cindex safer mode
6269 @cindex mode, safer
6270 @cindex unsafe mode
6271 @cindex mode, unsafe
6272 If @code{gtroff} is called with the @option{-U} command line option to
6273 activate unsafe mode, the number register @code{.U} is set to@tie{}1,
6274 and to zero otherwise.  @xref{Groff Options}.
6276 @item \n[.V]
6277 @cindex vertical resolution register (@code{.V})
6278 @cindex resolution, vertical, register (@code{.V})
6279 @vindex .V
6280 Vertical resolution in basic units.
6282 @item \n[seconds]
6283 @cindex seconds, current time (@code{seconds})
6284 @cindex time, current, seconds (@code{seconds})
6285 @cindex current time, seconds (@code{seconds})
6286 @vindex seconds
6287 The number of seconds after the minute, normally in the range@tie{}0
6288 to@tie{}59, but can be up to@tie{}61 to allow for leap seconds.
6289 Initialized at start-up of @code{gtroff}.
6291 @item \n[minutes]
6292 @cindex minutes, current time (@code{minutes})
6293 @cindex time, current, minutes (@code{minutes})
6294 @cindex current time, minutes (@code{minutes})
6295 @vindex minutes
6296 The number of minutes after the hour, in the range@tie{}0 to@tie{}59.
6297 Initialized at start-up of @code{gtroff}.
6299 @item \n[hours]
6300 @cindex hours, current time (@code{hours})
6301 @cindex time, current, hours (@code{hours})
6302 @cindex current time, hours (@code{hours})
6303 @vindex hours
6304 The number of hours past midnight, in the range@tie{}0 to@tie{}23.
6305 Initialized at start-up of @code{gtroff}.
6307 @item \n[dw]
6308 @cindex day of the week register (@code{dw})
6309 @cindex date, day of the week register (@code{dw})
6310 @vindex dw
6311 Day of the week (1-7).
6313 @item \n[dy]
6314 @cindex day of the month register (@code{dy})
6315 @cindex date, day of the month register (@code{dy})
6316 @vindex dy
6317 Day of the month (1-31).
6319 @item \n[mo]
6320 @cindex month of the year register (@code{mo})
6321 @cindex date, month of the year register (@code{mo})
6322 @vindex mo
6323 Current month (1-12).
6325 @item \n[year]
6326 @cindex date, year register (@code{year}, @code{yr})
6327 @cindex year, current, register (@code{year}, @code{yr})
6328 @vindex year
6329 The current year.
6331 @item \n[yr]
6332 @vindex yr
6333 The current year minus@tie{}1900.  Unfortunately, the documentation of
6334 @acronym{UNIX} Version@tie{}7's @code{troff} had a year@tie{}2000 bug:
6335 It incorrectly claimed that @code{yr} contains the last two digits of
6336 the year.  That claim has never been true of either @acronym{AT&T}
6337 @code{troff} or GNU @code{troff}.  Old @code{troff} input that looks
6338 like this:
6340 @Example
6341 '\" The following line stopped working after 1999
6342 This document was formatted in 19\n(yr.
6343 @endExample
6345 @noindent
6346 can be corrected as follows:
6348 @Example
6349 This document was formatted in \n[year].
6350 @endExample
6352 @noindent
6353 or, to be portable to older @code{troff} versions, as follows:
6355 @Example
6356 .nr y4 1900+\n(yr
6357 This document was formatted in \n(y4.
6358 @endExample
6360 @item \n[.c]
6361 @vindex .c
6362 @itemx \n[c.]
6363 @vindex c.
6364 @cindex input line number register (@code{.c}, @code{c.})
6365 @cindex line number, input, register (@code{.c}, @code{c.})
6366 The current @emph{input} line number.  Register @samp{.c} is read-only,
6367 whereas @samp{c.} (a @code{gtroff} extension) is writable also,
6368 affecting both @samp{.c} and @samp{c.}.
6370 @item \n[ln]
6371 @vindex ln
6372 @cindex output line number register (@code{ln})
6373 @cindex line number, output, register (@code{ln})
6374 The current @emph{output} line number after a call to the @code{nm}
6375 request to activate line numbering.
6377 @xref{Miscellaneous}, for more information about line numbering.
6379 @item \n[.x]
6380 @vindex .x
6381 @cindex major version number register (@code{.x})
6382 @cindex version number, major, register (@code{.x})
6383 The major version number.  For example, if the version number is 1.03
6384 then @code{.x} contains@tie{}@samp{1}.
6386 @item \n[.y]
6387 @vindex .y
6388 @cindex minor version number register (@code{.y})
6389 @cindex version number, minor, register (@code{.y})
6390 The minor version number.  For example, if the version number is 1.03
6391 then @code{.y} contains@tie{}@samp{03}.
6393 @item \n[.Y]
6394 @vindex .Y
6395 @cindex revision number register (@code{.Y})
6396 The revision number of @code{groff}.
6398 @item \n[$$]
6399 @vindex $$
6400 @cindex process ID of @code{gtroff} register (@code{$$})
6401 @cindex @code{gtroff}, process ID register (@code{$$})
6402 The process ID of @code{gtroff}.
6404 @item \n[.g]
6405 @vindex .g
6406 @cindex @code{gtroff}, identification register (@code{.g})
6407 @cindex GNU-specific register (@code{.g})
6408 Always@tie{}1.  Macros should use this to determine whether they are
6409 running under GNU @code{troff}.
6411 @item \n[.A]
6412 @vindex .A
6413 @cindex @acronym{ASCII} approximation output register (@code{.A})
6414 If the command line option @option{-a} is used to produce an
6415 @acronym{ASCII} approximation of the output, this is set to@tie{}1, zero
6416 otherwise.  @xref{Groff Options}.
6418 @item \n[.O]
6419 @vindex .O
6420 This read-only register is set to the suppression nesting level (see
6421 escapes @code{\O}).  @xref{Suppressing output}.
6423 @item \n[.P]
6424 @vindex .P
6425 This register is set to@tie{}1 (and to@tie{}0 otherwise) if the current
6426 page is actually being printed, i.e., if the @option{-o} option is being
6427 used to only print selected pages.  @xref{Groff Options}, for more
6428 information.
6430 @item \n[.T]
6431 @vindex .T
6432 If @code{gtroff} is called with the @option{-T} command line option, the
6433 number register @code{.T} is set to@tie{}1, and zero otherwise.
6434 @xref{Groff Options}.
6436 @item \*[.T]
6437 @stindex .T
6438 @cindex output device name string register (@code{.T})
6439 A single read-write string register which contains the current output
6440 device (for example, @samp{latin1} or @samp{ps}).  This is the only
6441 string register defined by @code{gtroff}.
6442 @end table
6445 @c =====================================================================
6447 @node Manipulating Filling and Adjusting, Manipulating Hyphenation, Registers, gtroff Reference
6448 @section Manipulating Filling and Adjusting
6449 @cindex manipulating filling and adjusting
6450 @cindex filling and adjusting, manipulating
6451 @cindex adjusting and filling, manipulating
6452 @cindex justifying text
6453 @cindex text, justifying
6455 @cindex break
6456 @cindex line break
6457 @cindex @code{bp} request, causing implicit linebreak
6458 @cindex @code{ce} request, causing implicit linebreak
6459 @cindex @code{cf} request, causing implicit linebreak
6460 @cindex @code{fi} request, causing implicit linebreak
6461 @cindex @code{fl} request, causing implicit linebreak
6462 @cindex @code{in} request, causing implicit linebreak
6463 @cindex @code{nf} request, causing implicit linebreak
6464 @cindex @code{rj} request, causing implicit linebreak
6465 @cindex @code{sp} request, causing implicit linebreak
6466 @cindex @code{ti} request, causing implicit linebreak
6467 @cindex @code{trf} request, causing implicit linebreak
6468 Various ways of causing @dfn{breaks} were given in @ref{Implicit Line
6469 Breaks}.  The @code{br} request likewise causes a break.  Several other
6470 requests also cause breaks, but implicitly.  These are @code{bp},
6471 @code{ce}, @code{cf}, @code{fi}, @code{fl}, @code{in}, @code{nf},
6472 @code{rj}, @code{sp}, @code{ti}, and @code{trf}.
6474 @Defreq {br, }
6475 Break the current line, i.e., the input collected so far is emitted
6476 without adjustment.
6478 If the no-break control character is used, @code{gtroff} suppresses the
6479 break:
6481 @Example
6485     @result{} a b
6486 @endExample
6487 @endDefreq
6489 Initially, @code{gtroff} fills and adjusts text to both margins.
6490 Filling can be disabled via the @code{nf} request and re-enabled with
6491 the @code{fi} request.
6493 @DefreqList {fi, }
6494 @DefregListEnd {.u}
6495 @cindex fill mode (@code{fi})
6496 @cindex mode, fill (@code{fi})
6497 Activate fill mode (which is the default).  This request implicitly
6498 enables adjusting; it also inserts a break in the text currently being
6499 filled.  The read-only number register @code{.u} is set to@tie{}1.
6501 The fill mode status is associated with the current environment
6502 (@pxref{Environments}).
6504 See @ref{Line Control}, for interaction with the @code{\c} escape.
6505 @endDefreq
6507 @Defreq {nf, }
6508 @cindex no-fill mode (@code{nf})
6509 @cindex mode, no-fill (@code{nf})
6510 Activate no-fill mode.  Input lines are output as-is, retaining line
6511 breaks and ignoring the current line length.  This command implicitly
6512 disables adjusting; it also causes a break.  The number register
6513 @code{.u} is set to@tie{}0.
6515 The fill mode status is associated with the current environment
6516 (@pxref{Environments}).
6518 See @ref{Line Control}, for interaction with the @code{\c} escape.
6519 @endDefreq
6521 @DefreqList {ad, [@Var{mode}]}
6522 @DefregListEnd {.j}
6523 Set adjusting mode.
6525 Activation and deactivation of adjusting is done implicitly with calls
6526 to the @code{fi} or @code{nf} requests.
6528 @var{mode} can have one of the following values:
6530 @table @code
6531 @item l
6532 @cindex ragged-right
6533 Adjust text to the left margin.  This produces what is traditionally
6534 called ragged-right text.
6536 @item r
6537 @cindex ragged-left
6538 Adjust text to the right margin, producing ragged-left text.
6540 @item c
6541 @cindex centered text
6542 @cindex @code{ce} request, difference to @samp{.ad@tie{}c}
6543 Center filled text.  This is different to the @code{ce} request which
6544 only centers text without filling.
6546 @item b
6547 @itemx n
6548 Justify to both margins.  This is the default used by @code{gtroff}.
6549 @end table
6551 Finally, @var{mode} can be the numeric argument returned by the
6552 @code{.j} register.
6554 With no argument, @code{gtroff} adjusts lines in the same way it did
6555 before adjusting was deactivated (with a call to @code{na}, for
6556 example).
6558 @Example
6559 text
6560 .ad r
6561 .nr ad \n[.j]
6562 text
6563 .ad c
6564 text
6566 text
6567 .ad         \" back to centering
6568 text
6569 .ad \n[ad]  \" back to right justifying
6570 @endExample
6572 @cindex adjustment mode register (@code{.j})
6573 The current adjustment mode is available in the read-only number
6574 register @code{.j}; it can be stored and subsequently used to set
6575 adjustment.
6577 The adjustment mode status is associated with the current environment
6578 (@pxref{Environments}).
6579 @endDefreq
6581 @Defreq {na, }
6582 Disable adjusting.  This request won't change the current adjustment
6583 mode: A subsequent call to @code{ad} uses the previous adjustment
6584 setting.
6586 The adjustment mode status is associated with the current environment
6587 (@pxref{Environments}).
6588 @endDefreq
6590 @DefreqList {brp, }
6591 @DefescListEnd {\\p, , , }
6592 Adjust the current line and cause a break.
6594 In most cases this produces very ugly results since @code{gtroff}
6595 doesn't have a sophisticated paragraph building algorithm (as @TeX{}
6596 have, for example); instead, @code{gtroff} fills and adjusts a paragraph
6597 line by line:
6599 @Example
6600 This is an uninteresting sentence.
6601 This is an uninteresting sentence.\p
6602 This is an uninteresting sentence.
6603 @endExample
6605 @noindent
6606 is formatted as
6608 @Example
6609 This is  an uninteresting  sentence.   This  is an
6610 uninteresting                            sentence.
6611 This is an uninteresting sentence.
6612 @endExample
6613 @endDefreq
6615 @DefreqList {ss, word_space_size [@Var{sentence_space_size}]}
6616 @DefregItem {.ss}
6617 @DefregListEnd {.sss}
6618 @cindex word space size register (@code{.ss})
6619 @cindex size of word space register (@code{.ss})
6620 @cindex space between words register (@code{.ss})
6621 @cindex sentence space size register (@code{.sss})
6622 @cindex size of sentence space register (@code{.sss})
6623 @cindex space between sentences register (@code{.sss})
6624 Change the size of a space between words.  It takes its units as one
6625 twelfth of the space width parameter for the current font.  Initially
6626 both the @var{word_space_size} and @var{sentence_space_size}
6627 are@tie{}12.  In fill mode, the values specify the minimum distance.
6629 @cindex fill mode
6630 @cindex mode, fill
6631 If two arguments are given to the @code{ss} request, the second argument
6632 sets the sentence space size.  If the second argument is not given,
6633 sentence space size is set to @var{word_space_size}.  The sentence space
6634 size is used in two circumstances: If the end of a sentence occurs at
6635 the end of a line in fill mode, then both an inter-word space and a
6636 sentence space are added; if two spaces follow the end of a sentence in
6637 the middle of a line, then the second space is a sentence space.  If a
6638 second argument is never given to the @code{ss} request, the behaviour
6639 of @acronym{UNIX} @code{troff} is the same as that exhibited by GNU
6640 @code{troff}.  In GNU @code{troff}, as in @acronym{UNIX} @code{troff}, a
6641 sentence should always be followed by either a newline or two spaces.
6643 The read-only number registers @code{.ss} and @code{.sss} hold the
6644 values of the parameters set by the first and second arguments of the
6645 @code{ss} request.
6647 The word space and sentence space values are associated with the current
6648 environment (@pxref{Environments}).
6650 Contrary to @acronym{AT&T} @code{troff}, this request is @emph{not}
6651 ignored if a TTY output device is used; the given values are then
6652 rounded down to a multiple of@tie{}12 (@pxref{Implementation
6653 Differences}).
6655 The request is ignored if there is no parameter.
6657 @cindex discardable horizontal space
6658 @cindex space, discardable, horizontal
6659 @cindex horizontal discardable space
6660 Another useful application of the @code{ss} request is to insert
6661 discardable horizontal space, i.e., space which is discarded at a line
6662 break.  For example, paragraph-style footnotes could be separated this
6663 way:
6665 @Example
6666 .ll 4.5i
6667 1.\ This is the first footnote.\c
6668 .ss 48
6669 .nop
6670 .ss 12
6671 2.\ This is the second footnote.
6672 @endExample
6674 @noindent
6675 The result:
6677 @Example
6678 1. This is the first footnote.        2. This
6679 is the second footnote.
6680 @endExample
6682 @noindent
6683 Note that the @code{\h} escape produces unbreakable space.
6684 @endDefreq
6686 @DefreqList {ce, [@Var{nnn}]}
6687 @DefregListEnd {.ce}
6688 @cindex centering lines (@code{ce})
6689 @cindex lines, centering (@code{ce})
6690 Center text.  While the @w{@samp{.ad c}} request also centers text, it
6691 fills the text as well.  @code{ce} does not fill the text it affects.
6692 This request causes a break.  The number of lines still to be centered
6693 is associated with the current environment (@pxref{Environments}).
6695 The following example demonstrates the differences.  Here the input:
6697 @Example
6698 .ll 4i
6699 .ce 1000
6700 This is a small text fragment which shows the differences
6701 between the `.ce' and the `.ad c' request.
6702 .ce 0
6704 .ad c
6705 This is a small text fragment which shows the differences
6706 between the `.ce' and the `.ad c' request.
6707 @endExample
6709 @noindent
6710 And here the result:
6712 @Example
6713   This is a small text fragment which
6714          shows the differences
6715 between the `.ce' and the `.ad c' request.
6717   This is a small text fragment which
6718 shows the differences between the `.ce'
6719         and the `.ad c' request.
6720 @endExample
6722 With no arguments, @code{ce} centers the next line of text.  @var{nnn}
6723 specifies the number of lines to be centered.  If the argument is zero
6724 or negative, centering is disabled.
6726 The basic length for centering text is the line length (as set with the
6727 @code{ll} request) minus the indentation (as set with the @code{in}
6728 request).  Temporary indentation is ignored.
6730 As can be seen in the previous example, it is a common idiom to turn on
6731 centering for a large number of lines, and to turn off centering after
6732 text to be centered.  This is useful for any request which takes a
6733 number of lines as an argument.
6735 The @code{.ce} read-only number register contains the number of lines
6736 remaining to be centered, as set by the @code{ce} request.
6737 @endDefreq
6739 @DefreqList {rj, [@Var{nnn}]}
6740 @DefregListEnd {.rj}
6741 @cindex justifying text (@code{rj})
6742 @cindex text, justifying (@code{rj})
6743 @cindex right-justifying (@code{rj})
6744 Justify unfilled text to the right margin.  Arguments are identical to
6745 the @code{ce} request.  The @code{.rj} read-only number register is the
6746 number of lines to be right-justified as set by the @code{rj} request.
6747 This request causes a break.  The number of lines still to be
6748 right-justified is associated with the current environment
6749 (@pxref{Environments}).
6750 @endDefreq
6753 @c =====================================================================
6755 @node Manipulating Hyphenation, Manipulating Spacing, Manipulating Filling and Adjusting, gtroff Reference
6756 @section Manipulating Hyphenation
6757 @cindex manipulating hyphenation
6758 @cindex hyphenation, manipulating
6760 Here a description of requests which influence hyphenation.
6762 @DefreqList {hy, [@Var{mode}]}
6763 @DefregListEnd {.hy}
6764 Enable hyphenation.  The request has an optional numeric argument,
6765 @var{mode}, to restrict hyphenation if necessary:
6767 @table @code
6768 @item 1
6769 The default argument if @var{mode} is omitted.  Hyphenate without
6770 restrictions.  This is also the start-up value of @code{gtroff}.
6772 @item 2
6773 Do not hyphenate the last word on a page or column.
6775 @item 4
6776 Do not hyphenate the last two characters of a word.
6778 @item 8
6779 Do not hyphenate the first two characters of a word.
6780 @end table
6782 Values in the previous table are additive.  For example, the
6783 value@tie{}12 causes @code{gtroff} to neither hyphenate the last two nor
6784 the first two characters of a word.
6786 @cindex hyphenation restrictions register (@code{.hy})
6787 The current hyphenation restrictions can be found in the read-only
6788 number register @samp{.hy}.
6790 The hyphenation mode is associated with the current environment
6791 (@pxref{Environments}).
6792 @endDefreq
6794 @Defreq {nh, }
6795 Disable hyphenation (i.e., set the hyphenation mode to zero).  Note that
6796 the hyphenation mode of the last call to @code{hy} is not remembered.
6798 The hyphenation mode is associated with the current environment
6799 (@pxref{Environments}).
6800 @endDefreq
6802 @DefreqList {hlm, [@Var{nnn}]}
6803 @DefregItem {.hlm}
6804 @DefregListEnd {.hlc}
6805 @cindex explicit hyphen (@code{\%})
6806 @cindex hyphen, explicit (@code{\%})
6807 @cindex consecutive hyphenated lines (@code{hlm})
6808 @cindex lines, consecutive hyphenated (@code{hlm})
6809 @cindex hyphenated lines, consecutive (@code{hlm})
6810 Set the maximum number of consecutive hyphenated lines to @var{nnn}.  If
6811 this number is negative, there is no maximum.  The default value
6812 is@tie{}@minus{}1 if @var{nnn} is omitted.  This value is associated
6813 with the current environment (@pxref{Environments}).  Only lines output
6814 from a given environment count towards the maximum associated with that
6815 environment.  Hyphens resulting from @code{\%} are counted; explicit
6816 hyphens are not.
6818 The current setting of @code{hlm} is available in the @code{.hlm}
6819 read-only number register.  Also the number of immediately preceding
6820 consecutive hyphenated lines are available in the read-only number
6821 register @samp{.hlc}.
6822 @endDefreq
6824 @Defreq {hw, word1 word2 @dots{}}
6825 Define how @var{word1}, @var{word2}, etc.@: are to be hyphenated.  The
6826 words must be given with hyphens at the hyphenation points.  For
6827 example:
6829 @Example
6830 .hw in-sa-lub-rious
6831 @endExample
6833 @noindent
6834 Besides the space character, any character whose hyphenation code value
6835 is zero can be used to separate the arguments of @code{hw} (see the
6836 documentation for the @code{hcode} request below for more information).
6837 In addition, this request can be used more than once.
6839 Hyphenation exceptions specified with the @code{hw} request are
6840 associated with the current hyphenation language; it causes an error if
6841 there is no current hyphenation language.
6843 This request is ignored if there is no parameter.
6845 In old versions of @code{troff} there was a limited amount of space to
6846 store such information; fortunately, with @code{gtroff}, this is no
6847 longer a restriction.
6848 @endDefreq
6850 @DefescList {\\%, , , }
6851 @deffnx Escape @t{\:}
6852 @ifnotinfo
6853 @esindex \:
6854 @end ifnotinfo
6855 @ifinfo
6856 @esindex \@r{<colon>}
6857 @end ifinfo
6858 @cindex hyphenation character (@code{\%})
6859 @cindex character, hyphenation (@code{\%})
6860 @cindex disabling hyphenation (@code{\%})
6861 @cindex hyphenation, disabling (@code{\%})
6862 To tell @code{gtroff} how to hyphenate words on the fly, use the
6863 @code{\%} escape, also known as the @dfn{hyphenation character}.
6864 Preceding a word with this character prevents it from being
6865 hyphenated; putting it inside a word indicates to @code{gtroff} that
6866 the word may be hyphenated at that point.  Note that this mechanism
6867 only affects that one occurrence of the word; to change the
6868 hyphenation of a word for the entire document, use the @code{hw}
6869 request.
6871 The @code{\:} escape inserts a zero-width break point (that is, the word
6872 breaks but without adding a hyphen).
6874 @Example
6875 ... check the /var/log/\:httpd/\:access_log file ...
6876 @endExample
6878 @cindex @code{\X}, followed by @code{\%}
6879 @cindex @code{\Y}, followed by @code{\%}
6880 @cindex @code{\%}, following @code{\X} or @code{\Y}
6881 Note that @code{\X} and @code{\Y} start a word, that is, the @code{\%}
6882 escape in (say) @w{@samp{\X'...'\%foobar}} and
6883 @w{@samp{\Y'...'\%foobar}} no longer prevents hyphenation but inserts a
6884 hyphenation point at the beginning of @samp{foobar}; most likely this
6885 isn't what you want to do.
6886 @endDefesc
6888 @Defreq {hc, [@Var{char}]}
6889 Change the hyphenation character to @var{char}.  This character then
6890 works the same as the @code{\%} escape, and thus, no longer appears in
6891 the output.  Without an argument, @code{hc} resets the hyphenation
6892 character to be @code{\%} (the default) only.
6894 The hyphenation character is associated with the current environment
6895 (@pxref{Environments}).
6896 @endDefreq
6898 @DefreqList {hpf, pattern_file}
6899 @DefreqItem {hpfa, pattern_file}
6900 @DefreqListEnd {hpfcode, a b [c d @dots{}]}
6901 @cindex hyphenation patterns (@code{hpf})
6902 @cindex patterns for hyphenation (@code{hpf})
6903 Read in a file of hyphenation patterns.  This file is searched for in
6904 the same way as @file{@var{name}.tmac} (or @file{tmac.@var{name}}) is
6905 searched for if the @option{-m@var{name}} option is specified.
6907 It should have the same format as (simple) @TeX{} patterns files.  More
6908 specifically, the following scanning rules are implemented.
6910 @itemize @bullet
6911 @item
6912 A percent sign starts a comment (up to the end of the line) even if
6913 preceded by a backslash.
6915 @item
6916 No support for `digraphs' like @code{\$}.
6918 @item
6919 @code{^^@var{xx}} (@var{x} is 0-9 or a-f) and @code{^^@var{x}}
6920 (character code of @var{x} in the range 0-127) are recognized; other use
6921 of @code{^} causes an error.
6923 @item
6924 No macro expansion.
6926 @item
6927 @code{hpf} checks for the expression @code{\patterns@{@dots{}@}}
6928 (possibly with whitespace before and after the braces).  Everything
6929 between the braces is taken as hyphenation patterns.  Consequently,
6930 @code{@{} and @code{@}} are not allowed in patterns.
6932 @item
6933 Similarly, @code{\hyphenation@{@dots{}@}} gives a list of hyphenation
6934 exceptions.
6936 @item
6937 @code{\endinput} is recognized also.
6939 @item
6940 For backwards compatibility, if @code{\patterns} is missing, the whole
6941 file is treated as a list of hyphenation patterns (only recognizing the
6942 @code{%} character as the start of a comment).
6943 @end itemize
6945 If no @code{hpf} request is specified (either in the document or in a
6946 macro package), @code{gtroff} won't hyphenate at all.
6948 The @code{hpfa} request appends a file of patterns to the current list.
6950 The @code{hpfcode} request defines mapping values for character codes in
6951 hyphenation patterns.  @code{hpf} or @code{hpfa} then apply the mapping
6952 (after reading the patterns) before replacing or appending them to the
6953 current list of patterns.  Its arguments are pairs of character codes --
6954 integers from 0 to@tie{}255.  The request maps character
6955 code@tie{}@var{a} to code@tie{}@var{b}, code@tie{}@var{c} to
6956 code@tie{}@var{d}, and so on.  You can use character codes which would
6957 be invalid otherwise.
6959 @pindex troffrc
6960 @pindex troffrc-end
6961 @pindex hyphen.us
6962 @pindex hyphenex.us
6963 The set of hyphenation patterns is associated with the current language
6964 set by the @code{hla} request.  The @code{hpf} request is usually
6965 invoked by the @file{troffrc} or @file{troffrc-end} file; by default,
6966 @file{troffrc} loads hyphenation patterns and exceptions for American
6967 English (in files @file{hyphen.us} and @file{hyphenex.us}).
6969 A second call to @code{hpf} (for the same language) replaces the
6970 hyphenation patterns with the new ones.
6972 Invoking @code{hpf} causes an error if there is no current hyphenation
6973 language.
6974 @endDefreq
6976 @Defreq {hcode, c1 code1 [c2 code2 @dots{}]}
6977 @cindex hyphenation code (@code{hcode})
6978 @cindex code, hyphenation (@code{hcode})
6979 Set the hyphenation code of character @var{c1} to @var{code1}, that of
6980 @var{c2} to @var{code2}, etc.  A hyphenation code must be a single input
6981 character (not a special character) other than a digit or a space.
6983 To make hyphenation work, hyphenation codes must be set up.  At
6984 start-up, groff only assigns hyphenation codes to the letters
6985 @samp{a}-@samp{z} (mapped to themselves) and to the letters
6986 @samp{A}-@samp{Z} (mapped to @samp{a}-@samp{z}); all other hyphenation
6987 codes are set to zero.  Normally, hyphenation patterns contain only
6988 lowercase letters which should be applied regardless of case.  With
6989 other words, the words `FOO' and `Foo' should be hyphenated exactly the
6990 same way as the word `foo' is hyphenated, and this is what @code{hcode}
6991 is good for.  Words which contain other letters won't be hyphenated
6992 properly if the corresponding hyphenation patterns actually do contain
6993 them.  For example, the following @code{hcode} requests are necessary to
6994 assign hyphenation codes to the letters @samp{ÄäÖöÜüß} (this is needed
6995 for German):
6997 @Example
6998 .hcode Ã¤ Ã¤  Ã„ Ã¤
6999 .hcode Ã¶ Ã¶  Ã– Ã¶
7000 .hcode Ã¼ Ã¼  Ãœ Ã¼
7001 .hcode ÃŸ ÃŸ
7002 @endExample
7004 Without those assignments, groff treats German words like
7005 @w{`Kindergärten'} (the plural form of `kindergarten') as two substrings
7006 @w{`kinderg'} and @w{`rten'} because the hyphenation code of the
7007 umlaut@tie{}a is zero by default.  There is a German hyphenation pattern
7008 which covers @w{`kinder'}, so groff finds the hyphenation `kin-der'.
7009 The other two hyphenation points (`kin-der-gär-ten') are missed.
7011 This request is ignored if it has no parameter.
7012 @endDefreq
7014 @DefreqList {hym, [@Var{length}]}
7015 @DefregListEnd {.hym}
7016 @cindex hyphenation margin (@code{hym})
7017 @cindex margin for hyphenation (@code{hym})
7018 @cindex @code{ad} request, and hyphenation margin
7019 Set the (right) hyphenation margin to @var{length}.  If the current
7020 adjustment mode is not @samp{b} or @samp{n}, the line is not hyphenated
7021 if it is shorter than @var{length}.  Without an argument, the
7022 hyphenation margin is reset to its default value, which is@tie{}0.  The
7023 default scaling indicator for this request is @samp{m}.  The hyphenation
7024 margin is associated with the current environment
7025 (@pxref{Environments}).
7027 A negative argument resets the hyphenation margin to zero, emitting a
7028 warning of type @samp{range}.
7030 @cindex hyphenation margin register (@code{.hym})
7031 The current hyphenation margin is available in the @code{.hym} read-only
7032 number register.
7033 @endDefreq
7035 @DefreqList {hys, [@Var{hyphenation_space}]}
7036 @DefregListEnd {.hys}
7037 @cindex hyphenation space (@code{hys})
7038 @cindex @code{ad} request, and hyphenation space
7039 Set the hyphenation space to @var{hyphenation_space}.  If the current
7040 adjustment mode is @samp{b} or @samp{n}, don't hyphenate the line if it
7041 can be justified by adding no more than @var{hyphenation_space} extra
7042 space to each word space.  Without argument, the hyphenation space is
7043 set to its default value, which is@tie{}0.  The default scaling
7044 indicator for this request is @samp{m}.  The hyphenation space is
7045 associated with the current environment (@pxref{Environments}).
7047 A negative argument resets the hyphenation space to zero, emitting a
7048 warning of type @samp{range}.
7050 @cindex hyphenation space register (@code{.hys})
7051 The current hyphenation space is available in the @code{.hys} read-only
7052 number register.
7053 @endDefreq
7055 @Defreq {shc, [@Var{glyph}]}
7056 @cindex soft hyphen character, setting (@code{shc})
7057 @cindex character, soft hyphen, setting (@code{shc})
7058 @cindex glyph, soft hyphen (@code{hy})
7059 @cindex soft hyphen glyph (@code{hy})
7060 @cindex @code{char} request, and soft hyphen character
7061 @cindex @code{tr} request, and soft hyphen character
7062 Set the @dfn{soft hyphen character} to @var{glyph}.@footnote{@dfn{Soft
7063 hyphen character} is a misnomer since it is an output glyph.}  If the
7064 argument is omitted, the soft hyphen character is set to the default
7065 glyph @code{\(hy} (this is the start-up value of @code{gtroff} also).
7066 The soft hyphen character is the glyph that is inserted when a word is
7067 hyphenated at a line break.  If the soft hyphen character does not exist
7068 in the font of the character immediately preceding a potential break
7069 point, then the line is not broken at that point.  Neither definitions
7070 (specified with the @code{char} request) nor translations (specified
7071 with the @code{tr} request) are considered when finding the soft hyphen
7072 character.
7073 @endDefreq
7075 @DefreqList {hla, language}
7076 @DefregListEnd {.hla}
7077 @cindex @code{hpf} request, and hyphenation language
7078 @cindex @code{hw} request, and hyphenation language
7079 @pindex troffrc
7080 @pindex troffrc-end
7081 Set the current hyphenation language to the string @var{language}.
7082 Hyphenation exceptions specified with the @code{hw} request and
7083 hyphenation patterns specified with the @code{hpf} and @code{hpfa}
7084 requests are both associated with the current hyphenation language.  The
7085 @code{hla} request is usually invoked by the @file{troffrc} or the
7086 @file{troffrc-end} files; @file{troffrc} sets the default language to
7087 @samp{us}.
7089 @cindex hyphenation language register (@code{.hla})
7090 The current hyphenation language is available as a string in the
7091 read-only number register @samp{.hla}.
7093 @Example
7094 .ds curr_language \n[.hla]
7095 \*[curr_language]
7096     @result{} us
7097 @endExample
7098 @endDefreq
7101 @c =====================================================================
7103 @node Manipulating Spacing, Tabs and Fields, Manipulating Hyphenation, gtroff Reference
7104 @section Manipulating Spacing
7105 @cindex manipulating spacing
7106 @cindex spacing, manipulating
7108 @Defreq {sp, [@Var{distance}]}
7109 Space downwards @var{distance}.  With no argument it advances
7110 1@tie{}line.  A negative argument causes @code{gtroff} to move up the
7111 page the specified distance.  If the argument is preceded by a @samp{|}
7112 then @code{gtroff} moves that distance from the top of the page.  This
7113 request causes a line break, and that adds the current line spacing to
7114 the space you have just specified.  The default scaling indicator is
7115 @samp{v}.
7117 For convenience you may wish to use the following macros to set the
7118 height of the next line at a given distance from the top or the bottom
7119 of the page:
7121 @Example
7122 .de y-from-top-down
7123 .  sp |\\$1-\\n[.v]u
7126 .de y-from-bot-up
7127 .  sp |\\n[.p]u-\\$1-\\n[.v]u
7129 @endExample
7131 @noindent
7132 A call to @samp{.y-from-bot-up 10c} means that the bottom of the next
7133 line will be at 10@dmn{cm} from the paper edge at the bottom.
7135 If a vertical trap is sprung during execution of @code{sp}, the amount
7136 of vertical space after the trap is discarded.  For example, this
7138 @Example
7139 .de xxx
7142 .wh 0 xxx
7144 .pl 5v
7146 .sp 2
7148 .sp 50
7150 @endExample
7152 @noindent
7153 results in
7155 @Example
7162 @endExample
7164 @cindex @code{sp} request, and traps
7165 @cindex discarded space in traps
7166 @cindex space, discarded, in traps
7167 @cindex traps, and discarded space
7168 The amount of discarded space is available in the number register
7169 @code{.trunc}.
7171 To protect @code{sp} against vertical traps, use the @code{vpt} request:
7173 @Example
7174 .vpt 0
7175 .sp -3
7176 .vpt 1
7177 @endExample
7178 @endDefreq
7180 @DefreqList {ls, [@Var{nnn}]}
7181 @DefregListEnd {.L}
7182 @cindex double-spacing (@code{ls})
7183 Output @w{@var{nnn}@minus{}1} blank lines after each line of text.  With
7184 no argument, @code{gtroff} uses the previous value before the last
7185 @code{ls} call.
7187 @Example
7188 .ls 2    \" This causes double-spaced output
7189 .ls 3    \" This causes triple-spaced output
7190 .ls      \" Again double-spaced
7191 @endExample
7193 The line spacing is associated with the current environment
7194 (@pxref{Environments}).
7196 @cindex line spacing register (@code{.L})
7197 The read-only number register @code{.L} contains the current line
7198 spacing setting.
7199 @endDefreq
7201 @xref{Changing Type Sizes}, for the requests @code{vs} and @code{pvs} as
7202 alternatives to @code{ls}.
7204 @DefescList {\\x, ', spacing, '}
7205 @DefregListEnd {.a}
7206 Sometimes, extra vertical spacing is only needed occasionally, e.g.@: to
7207 allow space for a tall construct (like an equation).  The @code{\x}
7208 escape does this.  The escape is given a numerical argument, usually
7209 enclosed in quotes (like @samp{\x'3p'}); the default scaling indicator
7210 is @samp{v}.  If this number is positive extra vertical space is
7211 inserted below the current line.  A negative number adds space above.
7212 If this escape is used multiple times on the same line, the maximum of
7213 the values is used.
7215 @xref{Escapes}, for details on parameter delimiting characters.
7217 @cindex extra post-vertical line space register (@code{.a})
7218 The @code{.a} read-only number register contains the most recent
7219 (nonnegative) extra vertical line space.
7221 Using @code{\x} can be necessary in combination with the @code{\b}
7222 escape, as the following example shows.
7224 @Example
7225 This is a test with the \[rs]b escape.
7227 This is a test with the \[rs]b escape.
7229 This is a test with \b'xyz'\x'-1m'\x'1m'.
7231 This is a test with the \[rs]b escape.
7233 This is a test with the \[rs]b escape.
7234 @endExample
7236 @noindent
7237 produces
7239 @Example
7240 This is a test with the \b escape.
7241 This is a test with the \b escape.
7242                     x
7243 This is a test with y.
7244                     z
7245 This is a test with the \b escape.
7246 This is a test with the \b escape.
7247 @endExample
7248 @endDefesc
7250 @DefreqList {ns, }
7251 @DefreqItem {rs, }
7252 @DefregListEnd {.ns}
7253 @cindex @code{sp} request, and no-space mode
7254 @cindex no-space mode (@code{ns})
7255 @cindex mode, no-space (@code{ns})
7256 @cindex blank lines, disabling
7257 @cindex lines, blank, disabling
7258 Enable @dfn{no-space mode}.  In this mode, spacing (either via @code{sp}
7259 or via blank lines) is disabled.  The @code{bp} request to advance to
7260 the next page is also disabled, except if it is accompanied by a page
7261 number (see @ref{Page Control}, for more information).  This mode ends
7262 when actual text is output or the @code{rs} request is encountered which
7263 ends no-space mode.  The read-only number register @code{.ns} is set
7264 to@tie{}1 as long as no-space mode is active.
7266 This request is useful for macros that conditionally insert vertical
7267 space before the text starts (for example, a paragraph macro could
7268 insert some space except when it is the first paragraph after a section
7269 header).
7270 @endDefreq
7273 @c =====================================================================
7275 @node Tabs and Fields, Character Translations, Manipulating Spacing, gtroff Reference
7276 @section Tabs and Fields
7277 @cindex tabs, and fields
7278 @cindex fields, and tabs
7280 @cindex @acronym{EBCDIC} encoding of a tab
7281 A tab character (@acronym{ASCII} char@tie{}9, @acronym{EBCDIC}
7282 char@tie{}5) causes a horizontal movement to the next tab stop (much
7283 like it did on a typewriter).
7285 @Defesc {\\t, , , }
7286 @cindex tab character, non-interpreted (@code{\t})
7287 @cindex character, tab, non-interpreted (@code{\t})
7288 @cindex @code{\t}, and copy-in mode
7289 @cindex copy-in mode, and @code{\t}
7290 @cindex mode, copy-in, and @code{\t}
7291 This escape is a non-interpreted tab character.  In copy mode
7292 (@pxref{Copy-in Mode}), @code{\t} is the same as a real tab character.
7293 @endDefesc
7295 @DefreqList {ta, [@Var{n1} @Var{n2} @dots{} @Var{nn} @t{T} @Var{r1} @Var{r2} @dots{} @Var{rn}]}
7296 @DefregListEnd {.tabs}
7297 Change tab stop positions.  This request takes a series of tab
7298 specifiers as arguments (optionally divided into two groups with the
7299 letter @samp{T}) which indicate where each tab stop is to be (overriding
7300 any previous settings).
7302 Tab stops can be specified absolutely, i.e., as the distance from the
7303 left margin.  For example, the following sets 6@tie{}tab stops every one
7304 inch.
7306 @Example
7307 .ta 1i 2i 3i 4i 5i 6i
7308 @endExample
7310 Tab stops can also be specified using a leading @samp{+} which means
7311 that the specified tab stop is set relative to the previous tab stop.
7312 For example, the following is equivalent to the previous example.
7314 @Example
7315 .ta 1i +1i +1i +1i +1i +1i
7316 @endExample
7318 @code{gtroff} supports an extended syntax to specify repeat values after
7319 the @samp{T} mark (these values are always taken as relative) -- this is
7320 the usual way to specify tabs set at equal intervals.  The following is,
7321 yet again, the same as the previous examples.  It does even more since
7322 it defines an infinite number of tab stops separated by one inch.
7324 @Example
7325 .ta T 1i
7326 @endExample
7328 Now we are ready to interpret the full syntax given at the beginning:
7329 Set tabs at positions @var{n1}, @var{n2}, @dots{}, @var{nn} and then set
7330 tabs at @var{nn}+@var{r1}, @var{nn}+@var{r2}, @dots{}, @var{nn}+@var{rn}
7331 and then at @var{nn}+@var{rn}+@var{r1}, @var{nn}+@var{rn}+@var{r2},
7332 @dots{}, @var{nn}+@var{rn}+@var{rn}, and so on.
7334 Example: @samp{4c +6c T 3c 5c 2c} is equivalent to @samp{4c 10c 13c 18c
7335 20c 23c 28c 30c @dots{}}.
7337 The material in each tab column (i.e., the column between two tab stops)
7338 may be justified to the right or left or centered in the column.  This
7339 is specified by appending @samp{R}, @samp{L}, or @samp{C} to the tab
7340 specifier.  The default justification is @samp{L}.  Example:
7342 @Example
7343 .ta 1i 2iC 3iR
7344 @endExample
7346 Some notes:
7348 @itemize @bullet
7349 @item
7350 The default unit of the @code{ta} request is @samp{m}.
7352 @item
7353 A tab stop is converted into a non-breakable horizontal movement which
7354 can be neither stretched nor squeezed.  For example,
7356 @Example
7357 .ds foo a\tb\tc
7358 .ta T 5i
7359 \*[foo]
7360 @endExample
7362 @noindent
7363 creates a single line which is a bit longer than 10@tie{}inches (a
7364 string is used to show exactly where the tab characters are).  Now
7365 consider the following:
7367 @Example
7368 .ds bar a\tb b\tc
7369 .ta T 5i
7370 \*[bar]
7371 @endExample
7373 @noindent
7374 @code{gtroff} first converts the tab stops of the line into unbreakable
7375 horizontal movements, then splits the line after the second @samp{b}
7376 (assuming a sufficiently short line length).  Usually, this isn't what
7377 the user wants.
7379 @item
7380 Superfluous tabs (i.e., tab characters which do not correspond to a tab
7381 stop) are ignored except the first one which delimits the characters
7382 belonging to the last tab stop for right-justifying or centering.
7383 Consider the following example
7385 @Example
7386 .ds Z   foo\tbar\tfoo
7387 .ds ZZ  foo\tbar\tfoobar
7388 .ds ZZZ foo\tbar\tfoo\tbar
7389 .ta 2i 4iR
7390 \*[Z]
7392 \*[ZZ]
7394 \*[ZZZ]
7396 @endExample
7398 @noindent
7399 which produces the following output:
7401 @Example
7402 foo                 bar              foo
7403 foo                 bar           foobar
7404 foo                 bar              foobar
7405 @endExample
7407 @noindent
7408 The first line right-justifies the second `foo' relative to the tab
7409 stop.  The second line right-justifies `foobar'.  The third line finally
7410 right-justifies only `foo' because of the additional tab character which
7411 marks the end of the string belonging to the last defined tab stop.
7413 @item
7414 Tab stops are associated with the current environment
7415 (@pxref{Environments}).
7417 @item
7418 Calling @code{ta} without an argument removes all tab stops.
7420 @item
7421 @cindex tab stops, for TTY output devices
7422 The start-up value of @code{gtroff} is @w{@samp{T 0.8i}}.
7423 @end itemize
7425 @cindex tab settings register (@code{.tabs})
7426 The read-only number register @code{.tabs} contains a string
7427 representation of the current tab settings suitable for use as an
7428 argument to the @code{ta} request.
7430 @Example
7431 .ds tab-string \n[.tabs]
7432 \*[tab-string]
7433     @result{} T120u
7434 @endExample
7436 @cindex @code{.S} register, Plan@tie{}9 alias for @code{.tabs}
7437 @cindex @code{.tabs} register, Plan@tie{}9 alias (@code{.S})
7438 The @code{troff} version of the Plan@tie{}9 operating system uses
7439 register @code{.S} for the same purpose.
7440 @endDefreq
7442 @Defreq {tc, [@Var{fill-glyph}]}
7443 @cindex tab repetition character (@code{tc})
7444 @cindex character, tab repetition (@code{tc})
7445 @cindex glyph, tab repetition (@code{tc})
7446 Normally @code{gtroff} fills the space to the next tab stop with
7447 whitespace.  This can be changed with the @code{tc} request.  With no
7448 argument @code{gtroff} reverts to using whitespace, which is the
7449 default.  The value of this @dfn{tab repetition character} is associated
7450 with the current environment (@pxref{Environments}).@footnote{@dfn{Tab
7451 repetition character} is a misnomer since it is an output glyph.}
7452 @endDefreq
7454 @DefreqList {linetabs, n}
7455 @DefregListEnd {.linetabs}
7456 @cindex tab, line-tabs mode
7457 @cindex line-tabs mode
7458 @cindex mode, line-tabs
7459 If @var{n} is missing or not zero, enable @dfn{line-tabs} mode, or
7460 disable it otherwise (the default).  In line-tabs mode, @code{gtroff}
7461 computes tab distances relative to the (current) output line instead of
7462 the input line.
7464 For example, the following code:
7466 @Example
7467 .ds x a\t\c
7468 .ds y b\t\c
7469 .ds z c
7470 .ta 1i 3i
7474 @endExample
7476 @noindent
7477 in normal mode, results in the output
7479 @Example
7480 a         b         c
7481 @endExample
7483 @noindent
7484 in line-tabs mode, the same code outputs
7486 @Example
7487 a         b                   c
7488 @endExample
7490 Line-tabs mode is associated with the current environment.  The
7491 read-only register @code{.linetabs} is set to@tie{}1 if in line-tabs
7492 mode, and 0 in normal mode.
7493 @endDefreq
7495 @menu
7496 * Leaders::
7497 * Fields::
7498 @end menu
7500 @c ---------------------------------------------------------------------
7502 @node Leaders, Fields, Tabs and Fields, Tabs and Fields
7503 @subsection Leaders
7504 @cindex leaders
7506 Sometimes it may may be desirable to use the @code{tc} request to fill a
7507 particular tab stop with a given glyph (for example dots in a table of
7508 contents), but also normal tab stops on the rest of the line.  For this
7509 @code{gtroff} provides an alternate tab mechanism, called @dfn{leaders}
7510 which does just that.
7512 @cindex leader character
7513 A leader character (character code@tie{}1) behaves similarly to a tab
7514 character: It moves to the next tab stop.  The only difference is that
7515 for this movement, the fill glyph defaults to a period character and not
7516 to space.
7518 @Defesc {\\a, , , }
7519 @cindex leader character, non-interpreted (@code{\a})
7520 @cindex character, leader, non-interpreted (@code{\a})
7521 @cindex @code{\a}, and copy-in mode
7522 @cindex copy-in mode, and @code{\a}
7523 @cindex mode, copy-in, and @code{\a}
7524 This escape is a non-interpreted leader character.  In copy mode
7525 (@pxref{Copy-in Mode}), @code{\a} is the same as a real leader
7526 character.
7527 @endDefesc
7529 @Defreq {lc, [@Var{fill-glyph}]}
7530 @cindex leader repetition character (@code{lc})
7531 @cindex character, leader repetition (@code{lc})
7532 @cindex glyph, leader repetition (@code{lc})
7533 Declare the @dfn{leader repetition character}.@footnote{@dfn{Leader
7534 repetition character} is a misnomer since it is an output glyph.}
7535 Without an argument, leaders act the same as tabs (i.e., using
7536 whitespace for filling).  @code{gtroff}'s start-up value is a dot
7537 (@samp{.}).  The value of the leader repetition character is associated
7538 with the current environment (@pxref{Environments}).
7539 @endDefreq
7541 @cindex table of contents
7542 @cindex contents, table of
7543 For a table of contents, to name an example, tab stops may be defined so
7544 that the section number is one tab stop, the title is the second with
7545 the remaining space being filled with a line of dots, and then the page
7546 number slightly separated from the dots.
7548 @Example
7549 .ds entry 1.1\tFoo\a\t12
7550 .lc .
7551 .ta 1i 5i +.25i
7552 \*[entry]
7553 @endExample
7555 @noindent
7556 This produces
7558 @Example
7559 1.1  Foo..........................................  12
7560 @endExample
7562 @c ---------------------------------------------------------------------
7564 @node Fields,  , Leaders, Tabs and Fields
7565 @subsection Fields
7566 @cindex fields
7568 @cindex field delimiting character (@code{fc})
7569 @cindex delimiting character, for fields (@code{fc})
7570 @cindex character, field delimiting (@code{fc})
7571 @cindex field padding character (@code{fc})
7572 @cindex padding character, for fields (@code{fc})
7573 @cindex character, field padding (@code{fc})
7574 @dfn{Fields} are a more general way of laying out tabular data.  A field
7575 is defined as the data between a pair of @dfn{delimiting characters}.
7576 It contains substrings which are separated by @dfn{padding characters}.
7577 The width of a field is the distance on the @emph{input} line from the
7578 position where the field starts to the next tab stop.  A padding
7579 character inserts stretchable space similar to @TeX{}'s @code{\hss}
7580 command (thus it can even be negative) to make the sum of all substring
7581 lengths plus the stretchable space equal to the field width.  If more
7582 than one padding character is inserted, the available space is evenly
7583 distributed among them.
7585 @Defreq {fc, [@Var{delim-char} [@Var{padding-char}]]}
7586 Define a delimiting and a padding character for fields.  If the latter
7587 is missing, the padding character defaults to a space character.  If
7588 there is no argument at all, the field mechanism is disabled (which is
7589 the default).  Note that contrary to e.g.@: the tab repetition
7590 character, delimiting and padding characters are @emph{not} associated
7591 to the current environment (@pxref{Environments}).
7593 Example:
7595 @Example
7596 .fc # ^
7597 .ta T 3i
7598 #foo^bar^smurf#
7600 #foo^^bar^smurf#
7601 @endExample
7603 @noindent
7604 and here the result:
7606 @Example
7607 foo         bar          smurf
7608 foo            bar       smurf
7609 @endExample
7610 @endDefreq
7613 @c =====================================================================
7615 @node Character Translations, Troff and Nroff Mode, Tabs and Fields, gtroff Reference
7616 @section Character Translations
7617 @cindex character translations
7618 @cindex translations of characters
7620 @cindex control character, changing (@code{cc})
7621 @cindex character, control, changing (@code{cc})
7622 @cindex no-break control character, changing (@code{c2})
7623 @cindex character, no-break control, changing (@code{c2})
7624 @cindex control character, no-break, changing (@code{c2})
7625 The control character (@samp{.}) and the no-break control character
7626 (@samp{'}) can be changed with the @code{cc} and @code{c2} requests,
7627 respectively.
7629 @Defreq {cc, [@Var{c}]}
7630 Set the control character to@tie{}@var{c}.  With no argument the default
7631 control character @samp{.} is restored.  The value of the control
7632 character is associated with the current environment
7633 (@pxref{Environments}).
7634 @endDefreq
7636 @Defreq {c2, [@Var{c}]}
7637 Set the no-break control character to@tie{}@var{c}.  With no argument
7638 the default control character @samp{'} is restored.  The value of the
7639 no-break control character is associated with the current environment
7640 (@pxref{Environments}).
7641 @endDefreq
7643 @xref{Requests}.
7645 @Defreq {eo, }
7646 @cindex disabling @code{\} (@code{eo})
7647 @cindex @code{\}, disabling (@code{eo})
7648 Disable the escape mechanism completely.  After executing this request,
7649 the backslash character @samp{\} no longer starts an escape sequence.
7651 This request can be very helpful in writing macros since it is not
7652 necessary then to double the escape character.  Here an example:
7654 @Example
7655 .\" This is a simplified version of the
7656 .\" .BR request from the man macro package
7658 .de BR
7659 .  ds result \&
7660 .  while (\n[.$] >= 2) \@{\
7661 .    as result \fB\$1\fR\$2
7662 .    shift 2
7663 .  \@}
7664 .  if \n[.$] .as result \fB\$1
7665 \*[result]
7666 .  ft R
7669 @endExample
7670 @endDefreq
7672 @Defreq {ec, [@Var{c}]}
7673 @cindex escape character, changing (@code{ec})
7674 @cindex character, escape, changing (@code{ec})
7675 Set the escape character to@tie{}@var{c}.  With no argument the default
7676 escape character @samp{\} is restored.  It can be also used to re-enable
7677 the escape mechanism after an @code{eo} request.
7679 Note that changing the escape character globally likely breaks macro
7680 packages since @code{gtroff} has no mechanism to `intern' macros, i.e.,
7681 to convert a macro definition into an internal form which is independent
7682 of its representation (@TeX{} has this mechanism).  If a macro is
7683 called, it is executed literally.
7684 @endDefreq
7686 @DefreqList {ecs, }
7687 @DefreqListEnd {ecr, }
7688 The @code{ecs} request saves the current escape character in an internal
7689 register.  Use this request in combination with the @code{ec} request to
7690 temporarily change the escape character.
7692 The @code{ecr} request restores the escape character saved with
7693 @code{ecs}.  Without a previous call to @code{ecs}, this request sets
7694 the escape character to @code{\}.
7695 @endDefreq
7697 @DefescList {\\\\, , , }
7698 @DefescItem {\\e, , , }
7699 @DefescListEnd {\\E, , , }
7700 Print the current escape character (which is the backslash character
7701 @samp{\} by default).
7703 @code{\\} is a `delayed' backslash; more precisely, it is the default
7704 escape character followed by a backslash, which no longer has special
7705 meaning due to the leading escape character.  It is @emph{not} an escape
7706 sequence in the usual sense!  In any unknown escape sequence
7707 @code{\@var{X}} the escape character is ignored and @var{X} is printed.
7708 But if @var{X} is equal to the current escape character, no warning is
7709 emitted.
7711 @cindex @code{\E}, and copy-in mode
7712 @cindex copy-in mode, and @code{\E}
7713 @cindex mode, copy-in, and @code{\E}
7714 As a consequence, only at top-level or in a diversion a backslash glyph
7715 is printed; in copy-in mode, it expands to a single backslash which then
7716 combines with the following character to an escape sequence.
7718 The @code{\E} escape differs from @code{\e} by printing an escape
7719 character that is not interpreted in copy mode.  Use this to define
7720 strings with escapes that work when used in copy mode (for example, as a
7721 macro argument).  The following example defines strings to begin and end
7722 a superscript:
7724 @Example
7725 .ds @{ \v'-.3m'\s'\En[.s]*60/100'
7726 .ds @} \s0\v'.3m'
7727 @endExample
7729 Another example to demonstrate the differences between the various
7730 escape sequences, using a strange escape character, @samp{-}.
7732 @Example
7733 .ec -
7734 .de xxx
7735 --A'123'
7737 .xxx
7738     @result{} -A'foo'
7739 @endExample
7741 @noindent
7742 The result is surprising for most users, expecting @samp{1} since
7743 @samp{foo} is a valid identifier.  What has happened?  As mentioned
7744 above, the leading escape character makes the following character
7745 ordinary.  Written with the default escape character the sequence
7746 @samp{--} becomes @samp{\-} -- this is the minus sign.
7748 If the escape character followed by itself is a valid escape sequence,
7749 only @code{\E} yields the expected result:
7751 @Example
7752 .ec -
7753 .de xxx
7754 -EA'123'
7756 .xxx
7757     @result{} 1
7758 @endExample
7759 @endDefesc
7761 @Defesc {\\., , , }
7762 Similar to @code{\\}, the sequence @code{\.} isn't a real escape
7763 sequence.  As before, a warning message is suppressed if the escape
7764 character is followed by a dot, and the dot itself is printed.
7766 @Example
7767 .de foo
7768 .  nop foo
7770 .  de bar
7771 .    nop bar
7772 \\..
7775 .foo
7776 .bar
7777     @result{} foo bar
7778 @endExample
7780 @noindent
7781 The first backslash is consumed while the macro is read, and the second
7782 is swallowed while exexuting macro @code{foo}.
7783 @endDefesc
7785 A @dfn{translation} is a mapping of an input character to an output
7786 glyph.  The mapping occurs at output time, i.e., the input character
7787 gets assigned the metric information of the mapped output character
7788 right before input tokens are converted to nodes (@pxref{Gtroff
7789 Internals}, for more on this process).
7791 @DefreqList {tr, @Var{a}@Var{b}@Var{c}@Var{d}@dots{}}
7792 @DefreqListEnd {trin, @Var{a}@Var{b}@Var{c}@Var{d}@dots{}}
7793 Translate character @var{a} to glyph@tie{}@var{b}, character @var{c} to
7794 glyph@tie{}@var{d}, etc.  If there is an odd number of arguments, the
7795 last one is translated to an unstretchable space (@w{@samp{\ }}).
7797 The @code{trin} request is identical to @code{tr}, but when you unformat
7798 a diversion with @code{asciify} it ignores the translation.
7799 @xref{Diversions}, for details about the @code{asciify} request.
7801 Some notes:
7803 @itemize @bullet
7804 @item
7805 @cindex @code{\(}, and translations
7806 @cindex @code{\[}, and translations
7807 @cindex @code{\'}, and translations
7808 @cindex @code{\`}, and translations
7809 @cindex @code{\-}, and translations
7810 @cindex @code{\_}, and translations
7811 @cindex @code{\C}, and translations
7812 @cindex @code{\N}, and translations
7813 @cindex @code{char} request, and translations
7814 @cindex special characters
7815 @cindex character, special
7816 @cindex numbered glyph (@code{\N})
7817 @cindex glyph, numbered (@code{\N})
7818 Special characters (@code{\(@var{xx}}, @code{\[@var{xxx}]},
7819 @code{\C'@var{xxx}'}, @code{\'}, @code{\`}, @code{\-}, @code{\_}),
7820 glyphs defined with the @code{char} request, and numbered glyphs
7821 (@code{\N'@var{xxx}'}) can be translated also.
7823 @item
7824 @cindex @code{\e}, and translations
7825 The @code{\e} escape can be translated also.
7827 @item
7828 @cindex @code{\%}, and translations
7829 @cindex @code{\~}, and translations
7830 Characters can be mapped onto the @code{\%} and @code{\~} escapes (but
7831 @code{\%} and @code{\~} can't be mapped onto another glyph).
7833 @item
7834 @cindex backspace character, and translations
7835 @cindex character, backspace, and translations
7836 @cindex leader character, and translations
7837 @cindex character, leader, and translations
7838 @cindex newline character, and translations
7839 @cindex character, newline, and translations
7840 @cindex tab character, and translations
7841 @cindex character, tab, and translations
7842 @cindex @code{\a}, and translations
7843 @cindex @code{\t}, and translations
7844 The following characters can't be translated: space (with one exception,
7845 see below), backspace, newline, leader (and @code{\a}), tab (and
7846 @code{\t}).
7848 @item
7849 @cindex @code{shc} request, and translations
7850 Translations are not considered for finding the soft hyphen character
7851 set with the @code{shc} request.
7853 @item
7854 @cindex @code{\&}, and translations
7855 The pair @samp{@var{c}\&} (this is an arbitrary character@tie{}@var{c}
7856 followed by the zero width space character) maps this character to
7857 nothing.
7859 @Example
7860 .tr a\&
7861 foo bar
7862     @result{} foo br
7863 @endExample
7865 @noindent
7866 It is even possible to map the space character to nothing:
7868 @Example
7869 .tr aa \&
7870 foo bar
7871     @result{} foobar
7872 @endExample
7874 @noindent
7875 As shown in the example, the space character can't be the first
7876 character/glyph pair as an argument of @code{tr}.  Additionally, it is
7877 not possible to map the space character to any other glyph; requests
7878 like @w{@samp{.tr aa x}} undo @w{@samp{.tr aa \&}} instead.
7880 If justification is active, lines are justified in spite of the `empty'
7881 space character (but there is no minimal distance, i.e.@: the space
7882 character, between words).
7884 @item
7885 After an output glyph has been constructed (this happens at the moment
7886 immediately before the glyph is appended to an output glyph list, either
7887 by direct output, in a macro, diversion, or string), it is no longer
7888 affected by @code{tr}.
7890 @item
7891 Translating character to glyphs where one of them or both are undefined
7892 is possible also; @code{tr} does not check whether the entities in its
7893 argument do exist.
7895 @xref{Gtroff Internals}.
7897 @item
7898 @code{troff} no longer has a hard-coded dependency on @w{Latin-1}; all
7899 @code{char@var{XXX}} entities have been removed from the font
7900 description files.  This has a notable consequence which shows up in
7901 warnings like @code{can't find character with input code @var{XXX}} if
7902 the @code{tr} request isn't handled properly.
7904 Consider the following translation:
7906 @Example
7907 .tr Ã©Ã‰
7908 @endExample
7910 @noindent
7911 This maps input character @code{é} onto glyph @code{É}, which is
7912 identical to glyph @code{char201}.  But this glyph intentionally doesn't
7913 exist!  Instead, @code{\[char201]} is treated as an input character
7914 entity and is by default mapped onto @code{\['E]}, and @code{gtroff}
7915 doesn't handle translations of translations.
7917 The right way to write the above translation is
7919 @Example
7920 .tr Ã©\['E]
7921 @endExample
7923 @noindent
7924 With other words, the first argument of @code{tr} should be an input
7925 character or entity, and the second one a glyph entity.
7927 @item
7928 Without an argument, the @code{tr} request is ignored.
7929 @end itemize
7930 @endDefreq
7932 @Defreq {trnt, @Var{a}@Var{b}@Var{c}@Var{d}@dots{}}
7933 @cindex @code{\!}, and @code{trnt}
7934 @code{trnt} is the same as the @code{tr} request except that the
7935 translations do not apply to text that is transparently throughput into
7936 a diversion with @code{\!}.  @xref{Diversions}, for more information.
7938 For example,
7940 @Example
7941 .tr ab
7942 .di x
7943 \!.tm a
7946 @endExample
7948 @noindent
7949 prints @samp{b} to the standard error stream; if @code{trnt} is used
7950 instead of @code{tr} it prints @samp{a}.
7951 @endDefreq
7954 @c =====================================================================
7956 @node Troff and Nroff Mode, Line Layout, Character Translations, gtroff Reference
7957 @section Troff and Nroff Mode
7958 @cindex troff mode
7959 @cindex mode, troff
7960 @cindex nroff mode
7961 @cindex mode, nroff
7963 Originally, @code{nroff} and @code{troff} were two separate programs,
7964 the former for TTY output, the latter for everything else.  With GNU
7965 @code{troff}, both programs are merged into one executable, sending its
7966 output to a device driver (@code{grotty} for TTY devices, @code{grops}
7967 for @sc{PostScript}, etc.)@: which interprets the intermediate output of
7968 @code{gtroff}.  For @acronym{UNIX} @code{troff} it makes sense to talk
7969 about @dfn{Nroff mode} and @dfn{Troff mode} since the differences are
7970 hardcoded.  For GNU @code{troff}, this distinction is not appropriate
7971 because @code{gtroff} simply takes the information given in the font
7972 files for a particular device without handling requests specially if a
7973 TTY output device is used.
7975 Usually, a macro package can be used with all output devices.
7976 Nevertheless, it is sometimes necessary to make a distinction between
7977 TTY and non-TTY devices: @code{gtroff} provides two built-in conditions
7978 @samp{n} and @samp{t} for the @code{if}, @code{ie}, and @code{while}
7979 requests to decide whether @code{gtroff} shall behave like @code{nroff}
7980 or like @code{troff}.
7982 @Defreq {troff, }
7983 @pindex troffrc
7984 @pindex troffrc-end
7985 Make the @samp{t} built-in condition true (and the @samp{n} built-in
7986 condition false) for @code{if}, @code{ie}, and @code{while} conditional
7987 requests.  This is the default if @code{gtroff} (@emph{not}
7988 @code{groff}) is started with the @option{-R} switch to avoid loading of
7989 the start-up files @file{troffrc} and @file{troffrc-end}.  Without
7990 @option{-R}, @code{gtroff} stays in troff mode if the output device is
7991 not a TTY (e.g.@: `ps').
7992 @endDefreq
7994 @Defreq {nroff, }
7995 @pindex tty.tmac
7996 Make the @samp{n} built-in condition true (and the @samp{t} built-in
7997 condition false) for @code{if}, @code{ie}, and @code{while} conditional
7998 requests.  This is the default if @code{gtroff} uses a TTY output
7999 device; the code for switching to nroff mode is in the file
8000 @file{tty.tmac} which is loaded by the start-up file @code{troffrc}.
8001 @endDefreq
8003 @xref{Conditionals and Loops}, for more details on built-in conditions.
8006 @c =====================================================================
8008 @node Line Layout, Line Control, Troff and Nroff Mode, gtroff Reference
8009 @section Line Layout
8010 @cindex line layout
8011 @cindex layout, line
8013 @cindex dimensions, line
8014 @cindex line dimensions
8015 The following drawing shows the dimensions which @code{gtroff} uses for
8016 placing a line of output onto the page.  They are labeled with the
8017 request which manipulates each dimension.
8019 @Example
8020      -->| in |<--
8021         |<-----------ll------------>|
8022    +----+----+----------------------+----+
8023    |    :    :                      :    |
8024    +----+----+----------------------+----+
8025 -->| po |<--
8026    |<--------paper width---------------->|
8027 @endExample
8029 @noindent
8030 These dimensions are:
8032 @ftable @code
8033 @item po
8034 @cindex left margin (@code{po})
8035 @cindex margin, left (@code{po})
8036 @cindex page offset (@code{po})
8037 @cindex offset, page (@code{po})
8038 @dfn{Page offset} -- this is the leftmost position of text on the final
8039 output, defining the @dfn{left margin}.
8041 @item in
8042 @cindex indentation (@code{in})
8043 @cindex line indentation (@code{in})
8044 @dfn{Indentation} -- this is the distance from the left margin where
8045 text is printed.
8047 @item ll
8048 @cindex line length (@code{ll})
8049 @cindex length of line (@code{ll})
8050 @dfn{Line length} -- this is the distance from the left margin to right
8051 margin.
8052 @end ftable
8054 A simple demonstration:
8056 @Example
8057 .ll 3i
8058 This is text without indentation.
8059 The line length has been set to 3\~inch.
8060 .in +.5i
8061 .ll -.5i
8062 Now the left and right margins are both increased.
8065 Calling .in and .ll without parameters restore
8066 the previous values.
8067 @endExample
8069 Result:
8071 @Example
8072 This  is text without indenta-
8073 tion.   The  line  length  has
8074 been set to 3 inch.
8075      Now   the  left  and
8076      right  margins   are
8077      both increased.
8078 Calling  .in  and  .ll without
8079 parameters restore the  previ-
8080 ous values.
8081 @endExample
8083 @DefreqList {po, [@Var{offset}]}
8084 @DefreqItem {po, @t{+}@Var{offset}}
8085 @DefreqItem {po, @t{-}@Var{offset}}
8086 @DefregListEnd {.o}
8087 @pindex troffrc
8088 Set horizontal page offset to @var{offset} (or increment or decrement
8089 the current value by @var{offset}).  Note that this request does not
8090 cause a break, so changing the page offset in the middle of text being
8091 filled may not yield the expected result.  The initial value is
8092 1@dmn{i}.  For TTY output devices, it is set to 0 in the startup file
8093 @file{troffrc}; the default scaling indicator is @samp{m} (and not
8094 @samp{v} as incorrectly documented in the original @acronym{UNIX} troff
8095 manual).
8097 The current page offset can be found in the read-only number register
8098 @samp{.o}.
8100 If @code{po} is called without an argument, the page offset is reset to
8101 the previous value before the last call to @code{po}.
8103 @Example
8104 .po 3i
8105 \n[.o]
8106     @result{} 720
8107 .po -1i
8108 \n[.o]
8109     @result{} 480
8111 \n[.o]
8112     @result{} 720
8113 @endExample
8114 @endDefreq
8116 @DefreqList {in, [@Var{indent}]}
8117 @DefreqItem {in, @t{+}@Var{indent}}
8118 @DefreqItem {in, @t{-}@Var{indent}}
8119 @DefregListEnd {.i}
8120 Set indentation to @var{indent} (or increment or decrement the current
8121 value by @var{indent}).  This request causes a break.  Initially, there
8122 is no indentation.
8124 If @code{in} is called without an argument, the indentation is reset to
8125 the previous value before the last call to @code{in}.  The default
8126 scaling indicator is @samp{m}.
8128 The indentation is associated with the current environment
8129 (@pxref{Environments}).
8131 If a negative indentation value is specified (which is not allowed),
8132 @code{gtroff} emits a warning of type @samp{range} and sets the
8133 indentation to zero.
8135 The effect of @code{in} is delayed until a partially collected line (if
8136 it exists) is output.  A temporary indentation value is reset to zero
8137 also.
8139 The current indentation (as set by @code{in}) can be found in the
8140 read-only number register @samp{.i}.
8141 @endDefreq
8143 @DefreqList {ti, offset}
8144 @DefreqItem {ti, @t{+}@Var{offset}}
8145 @DefreqItem {ti, @t{-}@Var{offset}}
8146 @DefregListEnd {.in}
8147 Temporarily indent the next output line by @var{offset}.  If an
8148 increment or decrement value is specified, adjust the temporary
8149 indentation relative to the value set by the @code{in} request.
8151 This request causes a break; its value is associated with the current
8152 environment (@pxref{Environments}).  The default scaling indicator is
8153 @samp{m}.  A call of @code{ti} without an argument is ignored.
8155 If the total indentation value is negative (which is not allowed),
8156 @code{gtroff} emits a warning of type @samp{range} and sets the
8157 temporary indentation to zero.  `Total indentation' is either
8158 @var{offset} if specified as an absolute value, or the temporary plus
8159 normal indentation, if @var{offset} is given as a relative value.
8161 The effect of @code{ti} is delayed until a partially collected line (if
8162 it exists) is output.
8164 The read-only number register @code{.in} is the indentation that applies
8165 to the current output line.
8167 The difference between @code{.i} and @code{.in} is that the latter takes
8168 into account whether a partially collected line still uses the old
8169 indentation value or a temporary indentation value is active.
8170 @endDefreq
8172 @DefreqList {ll, [@Var{length}]}
8173 @DefreqItem {ll, @t{+}@Var{length}}
8174 @DefreqItem {ll, @t{-}@Var{length}}
8175 @DefregItem {.l}
8176 @DefregListEnd {.ll}
8177 Set the line length to @var{length} (or increment or decrement the
8178 current value by @var{length}).  Initially, the line length is set to
8179 6.5@dmn{i}.  The effect of @code{ll} is delayed until a partially
8180 collected line (if it exists) is output.  The default scaling indicator
8181 is @samp{m}.
8183 If @code{ll} is called without an argument, the line length is reset to
8184 the previous value before the last call to @code{ll}.  If a negative
8185 line length is specified (which is not allowed), @code{gtroff} emits a
8186 warning of type @samp{range} and sets the line length to zero.
8188 The line length is associated with the current environment
8189 (@pxref{Environments}).
8191 @cindex line length register (@code{.l})
8192 The current line length (as set by @code{ll}) can be found in the
8193 read-only number register @samp{.l}.  The read-only number register
8194 @code{.ll} is the line length that applies to the current output line.
8196 Similar to @code{.i} and @code{.in}, the difference between @code{.l}
8197 and @code{.ll} is that the latter takes into account whether a partially
8198 collected line still uses the old line length value.
8199 @endDefreq
8202 @c =====================================================================
8204 @node Line Control, Page Layout, Line Layout, gtroff Reference
8205 @section Line Control
8206 @cindex line control
8207 @cindex control, line
8209 It is important to understand how @code{gtroff} handles input and output
8210 lines.
8212 Many escapes use positioning relative to the input line.  For example,
8213 this
8215 @Example
8216 This is a \h'|1.2i'test.
8218 This is a
8219 \h'|1.2i'test.
8220 @endExample
8222 @noindent
8223 produces
8225 @Example
8226 This is a   test.
8228 This is a             test.
8229 @endExample
8231 The main usage of this feature is to define macros which act exactly at
8232 the place where called.
8234 @Example
8235 .\" A simple macro to underline a word
8236 .de underline
8237 .  nop \\$1\l'|0\[ul]'
8239 @endExample
8241 @noindent
8242 In the above example, @samp{|0} specifies a negative distance from the
8243 current position (at the end of the just emitted argument @code{\$1})
8244 back to the beginning of the input line.  Thus, the @samp{\l} escape
8245 draws a line from right to left.
8247 @cindex input line continuation (@code{\})
8248 @cindex line, input, continuation (@code{\})
8249 @cindex continuation, input line (@code{\})
8250 @cindex output line, continuation (@code{\c})
8251 @cindex line, output, continuation (@code{\c})
8252 @cindex continuation, output line (@code{\c})
8253 @cindex interrupted line
8254 @cindex line, interrupted
8255 @code{gtroff} makes a difference between input and output line
8256 continuation; the latter is also called @dfn{interrupting} a line.
8258 @DefescList {\\@key{RET}, , ,}
8259 @DefescItem {\\c, , ,}
8260 @DefregListEnd {.int}
8261 Continue a line.  @code{\@key{RET}} (this is a backslash at the end of a
8262 line immediately followed by a newline) works on the input level,
8263 suppressing the effects of the following newline in the input.
8265 @Example
8266 This is a \
8267 .test
8268     @result{} This is a .test
8269 @endExample
8271 The @samp{|} operator is also affected.
8273 @cindex @code{\R}, after @code{\c}
8274 @code{\c} works on the output level.  Anything after this escape on the
8275 same line is ignored, except @code{\R} which works as usual.  Anything
8276 before @code{\c} on the same line is appended to the current partial
8277 output line.  The next non-command line after an interrupted line counts
8278 as a new input line.
8280 The visual results depend on whether no-fill mode is active.
8282 @itemize @bullet
8283 @item
8284 @cindex @code{\c}, and no-fill mode
8285 @cindex no-fill mode, and @code{\c}
8286 @cindex mode, no-fill, and @code{\c}
8287 If no-fill mode is active (using the @code{nf} request), the next input
8288 text line after @code{\c} is handled as a continuation of the same input
8289 text line.
8291 @Example
8293 This is a \c
8294 test.
8295     @result{} This is a test.
8296 @endExample
8298 @item
8299 @cindex @code{\c}, and fill mode
8300 @cindex fill mode, and @code{\c}
8301 @cindex mode, fill, and @code{\c}
8302 If fill mode is active (using the @code{fi} request), a word interrupted
8303 with @code{\c} is continued with the text on the next input text line,
8304 without an intervening space.
8306 @Example
8307 This is a te\c
8309     @result{} This is a test.
8310 @endExample
8311 @end itemize
8313 Note that an intervening control line which causes a break is stronger
8314 than @code{\c}, flushing out the current partial line in the usual way.
8316 @cindex interrupted line register (@code{.int})
8317 The @code{.int} register contains a positive value if the last output
8318 line was interrupted with @code{\c}; this is associated with the current
8319 environment (@pxref{Environments}).
8320 @endDefesc
8323 @c =====================================================================
8325 @node Page Layout, Page Control, Line Control, gtroff Reference
8326 @section Page Layout
8327 @cindex page layout
8328 @cindex layout, page
8330 @code{gtroff} provides some very primitive operations for controlling
8331 page layout.
8333 @DefreqList {pl, [@Var{length}]}
8334 @DefreqItem {pl, @t{+}@Var{length}}
8335 @DefreqItem {pl, @t{-}@Var{length}}
8336 @DefregListEnd {.p}
8337 @cindex page length (@code{pl})
8338 @cindex length of page (@code{pl})
8339 Set the @dfn{page length} to @var{length} (or increment or decrement the
8340 current value by @var{length}).  This is the length of the physical
8341 output page.  The default scaling indicator is @samp{v}.
8343 @cindex page length register (@code{.p})
8344 The current setting can be found in the read-only number register
8345 @samp{.p}.
8347 @cindex top margin
8348 @cindex margin, top
8349 @cindex bottom margin
8350 @cindex margin, bottom
8351 Note that this only specifies the size of the page, not the top and
8352 bottom margins.  Those are not set by @code{gtroff} directly.
8353 @xref{Traps}, for further information on how to do this.
8355 Negative @code{pl} values are possible also, but not very useful: No
8356 trap is sprung, and each line is output on a single page (thus
8357 suppressing all vertical spacing).
8359 If no argument or an invalid argument is given, @code{pl} sets the page
8360 length to 11@dmn{i}.
8361 @endDefreq
8363 @cindex headers
8364 @cindex footers
8365 @cindex titles
8366 @code{gtroff} provides several operations which help in setting up top
8367 and bottom titles (or headers and footers).
8369 @Defreq {tl, @t{'}@Var{left}@t{'}@Var{center}@t{'}@Var{right}@t{'}}
8370 @cindex title line (@code{tl})
8371 @cindex three-part title (@code{tl})
8372 @cindex page number character (@code{%})
8373 Print a @dfn{title line}.  It consists of three parts: a left justified
8374 portion, a centered portion, and a right justified portion.  The
8375 argument separator @samp{'} can be replaced with any character not
8376 occurring in the title line.  The @samp{%} character is replaced with
8377 the current page number.  This character can be changed with the
8378 @code{pc} request (see below).
8380 Without argument, @code{tl} is ignored.
8382 Some notes:
8384 @itemize @bullet
8385 @item
8386 A title line is not restricted to the top or bottom of a page.
8388 @item
8389 @code{tl} prints the title line immediately, ignoring a partially filled
8390 line (which stays untouched).
8392 @item
8393 It is not an error to omit closing delimiters.  For example,
8394 @w{@samp{.tl /foo}} is equivalent to @w{@samp{.tl /foo///}}: It prints a
8395 title line with the left justified word @samp{foo}; the centered and
8396 right justfied parts are empty.
8398 @item
8399 @code{tl} accepts the same parameter delimiting characters as the
8400 @code{\A} escape; see @ref{Escapes}.
8401 @end itemize
8402 @endDefreq
8404 @DefreqList {lt, [@Var{length}]}
8405 @DefreqItem {lt, @t{+}@Var{length}}
8406 @DefreqItem {lt, @t{-}@Var{length}}
8407 @DefregListEnd {.lt}
8408 @cindex length of title line (@code{lt})
8409 @cindex title line, length (@code{lt})
8410 @cindex title line length register (@code{.lt})
8411 The title line is printed using its own line length, which is specified
8412 (or incremented or decremented) with the @code{lt} request.  Initially,
8413 the title line length is set to 6.5@dmn{i}.  If a negative line length
8414 is specified (which is not allowed), @code{gtroff} emits a warning of
8415 type @samp{range} and sets the title line length to zero.  The default
8416 scaling indicator is @samp{m}.  If @code{lt} is called without an
8417 argument, the title length is reset to the previous value before the
8418 last call to @code{lt}.
8420 The current setting of this is available in the @code{.lt} read-only
8421 number register; it is associated with the current environment
8422 (@pxref{Environments}).
8423 @endDefreq
8425 @DefreqList {pn, page}
8426 @DefreqItem {pn, @t{+}@Var{page}}
8427 @DefreqItem {pn, @t{-}@Var{page}}
8428 @DefregListEnd {.pn}
8429 @cindex page number (@code{pn})
8430 @cindex number, page (@code{pn})
8431 Change (increase or decrease) the page number of the @emph{next} page.
8432 The only argument is the page number; the request is ignored without a
8433 parameter.
8435 The read-only number register @code{.pn} contains the number of the next
8436 page: either the value set by a @code{pn} request, or the number of the
8437 current page plus@tie{}1.
8438 @endDefreq
8440 @Defreq {pc, [@Var{char}]}
8441 @cindex changing the page number character (@code{pc})
8442 @cindex page number character, changing (@code{pc})
8443 @vindex %
8444 Change the page number character (used by the @code{tl} request) to a
8445 different character.  With no argument, this mechanism is disabled.
8446 Note that this doesn't affect the number register@tie{}@code{%}.
8447 @endDefreq
8449 @xref{Traps}.
8452 @c =====================================================================
8454 @node Page Control, Fonts and Symbols, Page Layout, gtroff Reference
8455 @section Page Control
8456 @cindex page control
8457 @cindex control, page
8459 @DefreqList {bp, [@Var{page}]}
8460 @DefreqItem {bp, @t{+}@Var{page}}
8461 @DefreqItem {bp, @t{-}@Var{page}}
8462 @DefregListEnd {%}
8463 @cindex new page (@code{bp})
8464 @cindex page, new (@code{bp})
8465 Stop processing the current page and move to the next page.  This
8466 request causes a break.  It can also take an argument to set (increase,
8467 decrease) the page number of the next page (which actually becomes the
8468 current page after @code{bp} has finished).  The difference between
8469 @code{bp} and @code{pn} is that @code{pn} does not cause a break or
8470 actually eject a page.  @xref{Page Layout}.
8472 @Example
8473 .de newpage                         \" define macro
8474 'bp                                 \" begin page
8475 'sp .5i                             \" vertical space
8476 .tl 'left top'center top'right top' \" title
8477 'sp .3i                             \" vertical space
8478 ..                                  \" end macro
8479 @endExample
8481 @cindex @code{bp} request, and top-level diversion
8482 @cindex top-level diversion, and @code{bp}
8483 @cindex diversion, top-level, and @code{bp}
8484 @code{bp} has no effect if not called within the top-level diversion
8485 (@pxref{Diversions}).
8487 @cindex page number register (@code{%})
8488 @cindex current page number (@code{%})
8489 The read-write register@tie{}@code{%} holds the current page number.
8491 The number register @code{.pe} is set to@tie{}1 while @code{bp} is
8492 active.  @xref{Page Location Traps}.
8493 @endDefreq
8495 @Defreq {ne, [@Var{space}]}
8496 @cindex orphan lines, preventing with @code{ne}
8497 @cindex conditional page break (@code{ne})
8498 @cindex page break, conditional (@code{ne})
8499 It is often necessary to force a certain amount of space before a new
8500 page occurs.  This is most useful to make sure that there is not a
8501 single @dfn{orphan} line left at the bottom of a page.  The @code{ne}
8502 request ensures that there is a certain distance, specified by the first
8503 argument, before the next page is triggered (see @ref{Traps}, for
8504 further information).  The default scaling indicator for @code{ne} is
8505 @samp{v}; the default value of @var{space} is@tie{}1@dmn{v} if no
8506 argument is given.
8508 For example, to make sure that no fewer than 2@tie{}lines get orphaned,
8509 do the following before each paragraph:
8511 @Example
8512 .ne 2
8513 text text text
8514 @endExample
8516 @code{ne} then automatically causes a page break if there is space for
8517 one line only.
8518 @endDefreq
8520 @DefreqList {sv, [@Var{space}]}
8521 @DefreqListEnd {os, }
8522 @cindex @code{ne} request, comparison with @code{sv}
8523 @code{sv} is similar to the @code{ne} request; it reserves the specified
8524 amount of vertical space.  If the desired amount of space exists before
8525 the next trap (or the bottom page boundary if no trap is set), the space
8526 is output immediately (ignoring a partially filled line which stays
8527 untouched).  If there is not enough space, it is stored for later output
8528 via the @code{os} request.  The default value is@tie{}1@dmn{v} if no
8529 argument is given; the default scaling indicator is @samp{v}.
8531 @cindex @code{sv} request, and no-space mode
8532 @cindex @code{os} request, and no-space mode
8533 Both @code{sv} and @code{os} ignore no-space mode.  While the @code{sv}
8534 request allows negative values for @var{space}, @code{os} ignores them.
8535 @endDefreq
8537 @Defreg {nl}
8538 @cindex current vertical position (@code{nl})
8539 @cindex vertical position, current (@code{nl})
8540 @cindex position, vertical, current (@code{nl})
8541 This register contains the current vertical position.  If the vertical
8542 position is zero and the top of page transition hasn't happened yet,
8543 @code{nl} is set to negative value.  @code{gtroff} itself does this at
8544 the very beginning of a document before anything has been printed, but
8545 the main usage is to plant a header trap on a page if this page has
8546 already started.
8548 Consider the following:
8550 @Example
8551 .de xxx
8552 .  sp
8553 .  tl ''Header''
8554 .  sp
8557 First page.
8559 .wh 0 xxx
8560 .nr nl (-1)
8561 Second page.
8562 @endExample
8564 @noindent
8565 Result:
8567 @Example
8568 First page.
8572                              Header
8574 Second page.
8577 @endExample
8579 @noindent
8580 Without resetting @code{nl} to a negative value, the just planted trap
8581 would be active beginning with the @emph{next} page, not the current
8582 one.
8584 @xref{Diversions}, for a comparison with the @code{.h} and @code{.d}
8585 registers.
8586 @endDefreg
8589 @c =====================================================================
8591 @node Fonts and Symbols, Sizes, Page Control, gtroff Reference
8592 @section Fonts and Symbols
8593 @cindex fonts
8595 @code{gtroff} can switch fonts at any point in the text.
8597 The basic set of fonts is @samp{R}, @samp{I}, @samp{B}, and @samp{BI}.
8598 These are Times Roman, Italic, Bold, and Bold Italic.  For non-TTY
8599 devices, there is also at least one symbol font which contains various
8600 special symbols (Greek, mathematics).
8602 @menu
8603 * Changing Fonts::
8604 * Font Families::
8605 * Font Positions::
8606 * Using Symbols::
8607 * Special Fonts::
8608 * Artificial Fonts::
8609 * Ligatures and Kerning::
8610 @end menu
8612 @c ---------------------------------------------------------------------
8614 @node Changing Fonts, Font Families, Fonts and Symbols, Fonts and Symbols
8615 @subsection Changing Fonts
8616 @cindex fonts
8618 @DefreqList {ft, [@Var{font}]}
8619 @DefescItem {\\f, , f, }
8620 @DefescItem {\\f, @Lparen{}, fn, }
8621 @DefescItem {\\f, @Lbrack{}, font, @Rbrack{}}
8622 @DefregListEnd {.sty}
8623 @cindex changing fonts (@code{ft}, @code{\f})
8624 @cindex fonts, changing (@code{ft}, @code{\f})
8625 @cindex @code{sty} request, and changing fonts
8626 @cindex @code{fam} request, and changing fonts
8627 @cindex @code{\F}, and changing fonts
8628 @kindex styles
8629 @kindex family
8630 @pindex DESC
8631 The @code{ft} request and the @code{\f} escape change the current font
8632 to @var{font} (one-character name@tie{}@var{f}, two-character name
8633 @var{fn}).
8635 If @var{font} is a style name (as set with the @code{sty} request or
8636 with the @code{styles} command in the @file{DESC} file), use it within
8637 the current font family (as set with the @code{fam} request, @code{\F}
8638 escape, or with the @code{family} command in the @file{DESC} file).
8640 It is not possible to switch to a font with the name @samp{DESC}
8641 (whereas this name could be used as a style name; however, this is not
8642 recommended).
8644 @cindex previous font (@code{ft}, @code{\f[]}, @code{\fP})
8645 @cindex font, previous (@code{ft}, @code{\f[]}, @code{\fP})
8646 With no argument or using @samp{P} as an argument, @code{.ft} switches
8647 to the previous font.  Use @code{\f[]} to do this with the escape.  The
8648 old syntax forms @code{\fP} or @code{\f[P]} are also supported.
8650 Fonts are generally specified as upper-case strings, which are usually
8651 1@tie{}to 4 characters representing an abbreviation or acronym of the
8652 font name.  This is no limitation, just a convention.
8654 The example below produces two identical lines.
8656 @Example
8657 eggs, bacon,
8658 .ft B
8659 spam
8661 and sausage.
8663 eggs, bacon, \fBspam\fP and sausage.
8664 @endExample
8666 Note that @code{\f} doesn't produce an input token in @code{gtroff}.  As
8667 a consequence, it can be used in requests like @code{mc} (which expects
8668 a single character as an argument) to change the font on the fly:
8670 @Example
8671 .mc \f[I]x\f[]
8672 @endExample
8674 The current style name is available in the read-only number register
8675 @samp{.sty} (this is a string-valued register); if the current font
8676 isn't a style, the empty string is returned.  It is associated with the
8677 current environment.
8679 @xref{Font Positions}, for an alternative syntax.
8680 @endDefreq
8682 @Defreq {ftr, f [@Var{g}]}
8683 @cindex font translation (@code{ftr})
8684 @cindex @code{ft} request, and font translations
8685 @cindex @code{ul} request, and font translations
8686 @cindex @code{bd} request, and font translations
8687 @cindex @code{\f}, and font translations
8688 @cindex @code{cs} request, and font translations
8689 @cindex @code{tkf} request, and font translations
8690 @cindex @code{special} request, and font translations
8691 @cindex @code{fspecial} request, and font translations
8692 @cindex @code{fp} request, and font translations
8693 @cindex @code{sty} request, and font translations
8694 @cindex @code{if} request, and font translations
8695 @cindex @code{ie} request, and font translations
8696 @cindex @code{while} request, and font translations
8697 Translate font@tie{}@var{f} to font@tie{}@var{g}.  Whenever a font
8698 named@tie{}@var{f} is referred to in a @code{\f} escape sequence, in the
8699 @code{F} and @code{S} conditional operators, or in the @code{ft},
8700 @code{ul}, @code{bd}, @code{cs}, @code{tkf}, @code{special},
8701 @code{fspecial}, @code{fp}, or @code{sty} requests, font@tie{}@var{g} is
8702 used.  If @var{g} is missing or equal to@tie{}@var{f} the translation is
8703 undone.
8705 Note that it is not possible to chain font translations.  Example:
8707 @Example
8708 .ftr XXX TR
8709 .ftr XXX YYY
8710 .ft XXX
8711     @result{} warning: can't find font `XXX'
8712 @endExample
8713 @endDefreq
8715 @DefreqList {fzoom, f [@Var{zoom}]}
8716 @DefregListEnd {.zoom}
8717 @cindex magnification of a font (@code{fzoom})
8718 @cindex font, magnification (@code{fzoom})
8719 @cindex zoom factor of a font (@code{fzoom})
8720 @cindex factor, zoom, of a font (@code{fzoom})
8721 @cindex font, zoom factor (@code{fzoom})
8722 @cindex optical size of a font
8723 @cindex font, optical size
8724 @cindex size, optical, of a font
8725 Set magnification of font@tie{}@var{f} to factor @var{zoom}, which must
8726 be a non-negative integer multiple of 1/1000th.  This request is useful
8727 to adjust the optical size of a font in relation to the others.  In the
8728 example below, font @code{CR} is magnified by 10% (the zoom factor is
8729 thus 1.1).
8731 @Example
8732 .fam P
8733 .fzoom CR 1100
8734 .ps 12
8735 Palatino and \f[CR]Courier\f[]
8736 @endExample
8738 A missing or zero value of @var{zoom} is the same as a value of 1000,
8739 which means no magnification.  @var{f}@tie{}must be a real font name,
8740 not a style.
8742 Note that the magnification of a font is completely transparent to
8743 troff; a change of the zoom factor doesn't cause any effect except that
8744 the dimensions of glyphs, (word) spaces, kerns, etc., of the affected
8745 font are adjusted accordingly.
8747 The zoom factor of the current font is available in the read-only number
8748 register @samp{.zoom}, in multiples of 1/1000th.  It returns zero if
8749 there is no magnification.
8750 @endDefreq
8752 @c ---------------------------------------------------------------------
8754 @node Font Families, Font Positions, Changing Fonts, Fonts and Symbols
8755 @subsection Font Families
8756 @cindex font families
8757 @cindex families, font
8758 @cindex font styles
8759 @cindex styles, font
8761 Due to the variety of fonts available, @code{gtroff} has added the
8762 concept of @dfn{font families} and @dfn{font styles}.  The fonts are
8763 specified as the concatenation of the font family and style.  Specifying
8764 a font without the family part causes @code{gtroff} to use that style of
8765 the current family.
8767 @cindex PostScript fonts
8768 @cindex fonts, PostScript
8769 Currently, fonts for the devices @option{-Tps}, @option{-Tdvi},
8770 @option{-Tlj4}, @option{-Tlbp}, and the X11 fonts are set up to this
8771 mechanism.  By default, @code{gtroff} uses the Times family with the
8772 four styles @samp{R}, @samp{I}, @samp{B}, and @samp{BI}.
8774 This way, it is possible to use the basic four fonts and to select a
8775 different font family on the command line (@pxref{Groff Options}).
8777 @DefreqList {fam, [@Var{family}]}
8778 @DefregItem {.fam}
8779 @DefescItem {\\F, , f, }
8780 @DefescItem {\\F, @Lparen{}, fm, }
8781 @DefescItem {\\F, @Lbrack{}, family, @Rbrack{}}
8782 @DefregListEnd {.fn}
8783 @cindex changing font family (@code{fam}, @code{\F})
8784 @cindex font family, changing (@code{fam}, @code{\F})
8785 Switch font family to @var{family} (one-character name@tie{}@var{f},
8786 two-character name @var{fm}).  If no argument is given, switch back to
8787 the previous font family.  Use @code{\F[]} to do this with the escape.
8788 Note that @code{\FP} doesn't work; it selects font family @samp{P}
8789 instead.
8791 The value at start-up is @samp{T}.  The current font family is available
8792 in the read-only number register @samp{.fam} (this is a string-valued
8793 register); it is associated with the current environment.
8795 @Example
8796 spam,
8797 .fam H    \" helvetica family
8798 spam,     \" used font is family H + style R = HR
8799 .ft B     \" family H + style B = font HB
8800 spam,
8801 .fam T    \" times family
8802 spam,     \" used font is family T + style B = TB
8803 .ft AR    \" font AR (not a style)
8804 baked beans,
8805 .ft R     \" family T + style R = font TR
8806 and spam.
8807 @endExample
8809 Note that @code{\F} doesn't produce an input token in @code{gtroff}.  As
8810 a consequence, it can be used in requests like @code{mc} (which expects
8811 a single character as an argument) to change the font family on the fly:
8813 @Example
8814 .mc \F[P]x\F[]
8815 @endExample
8817 The @samp{.fn} register contains the current @dfn{real font name} of the
8818 current font.  This is a string-valued register.  If the current font is
8819 a style, the value of @code{\n[.fn]} is the proper concatenation of
8820 family and style name.
8821 @endDefreq
8823 @Defreq {sty, n style}
8824 @cindex changing font style (@code{sty})
8825 @cindex font style, changing (@code{sty})
8826 @cindex @code{cs} request, and font styles
8827 @cindex @code{bd} request, and font styles
8828 @cindex @code{tkf} request, and font styles
8829 @cindex @code{uf} request, and font styles
8830 @cindex @code{fspecial} request, and font styles
8831 Associate @var{style} with font position@tie{}@var{n}.  A font position
8832 can be associated either with a font or with a style.  The current font
8833 is the index of a font position and so is also either a font or a style.
8834 If it is a style, the font that is actually used is the font which name
8835 is the concatenation of the name of the current family and the name of
8836 the current style.  For example, if the current font is@tie{}1 and font
8837 position@tie{}1 is associated with style @samp{R} and the current font
8838 family is @samp{T}, then font @samp{TR} is used.  If the current font is
8839 not a style, then the current family is ignored.  If the requests
8840 @code{cs}, @code{bd}, @code{tkf}, @code{uf}, or @code{fspecial} are
8841 applied to a style, they are instead applied to the member of the
8842 current family corresponding to that style.
8844 @var{n}@tie{}must be a non-negative integer value.
8846 @pindex DESC
8847 @kindex styles
8848 The default family can be set with the @option{-f} option (@pxref{Groff
8849 Options}).  The @code{styles} command in the @file{DESC} file controls
8850 which font positions (if any) are initially associated with styles
8851 rather than fonts.  For example, the default setting for @sc{PostScript}
8852 fonts
8854 @Example
8855 styles R I B BI
8856 @endExample
8858 @noindent
8859 is equivalent to
8861 @Example
8862 .sty 1 R
8863 .sty 2 I
8864 .sty 3 B
8865 .sty 4 BI
8866 @endExample
8868 @code{fam} and @code{\F} always check whether the current font position
8869 is valid; this can give surprising results if the current font position
8870 is associated with a style.
8872 In the following example, we want to access the @sc{PostScript} font
8873 @code{FooBar} from the font family @code{Foo}:
8875 @Example
8876 .sty \n[.fp] Bar
8877 .fam Foo
8878     @result{} warning: can't find font `FooR'
8879 @endExample
8881 @noindent
8882 The default font position at start-up is@tie{}1; for the @sc{PostScript}
8883 device, this is associated with style @samp{R}, so @code{gtroff} tries
8884 to open @code{FooR}.
8886 A solution to this problem is to use a dummy font like the following:
8888 @Example
8889 .fp 0 dummy TR    \" set up dummy font at position 0
8890 .sty \n[.fp] Bar  \" register style `Bar'
8891 .ft 0             \" switch to font at position 0
8892 .fam Foo          \" activate family `Foo'
8893 .ft Bar           \" switch to font `FooBar'
8894 @endExample
8896 @xref{Font Positions}.
8897 @endDefreq
8899 @c ---------------------------------------------------------------------
8901 @node Font Positions, Using Symbols, Font Families, Fonts and Symbols
8902 @subsection Font Positions
8903 @cindex font positions
8904 @cindex positions, font
8906 For the sake of old phototypesetters and compatibility with old versions
8907 of @code{troff}, @code{gtroff} has the concept of font @dfn{positions},
8908 on which various fonts are mounted.
8910 @DefreqList {fp, pos font [@Var{external-name}]}
8911 @DefregItem {.f}
8912 @DefregListEnd {.fp}
8913 @cindex mounting font (@code{fp})
8914 @cindex font, mounting (@code{fp})
8915 Mount font @var{font} at position @var{pos} (which must be a
8916 non-negative integer).  This numeric position can then be referred to
8917 with font changing commands.  When @code{gtroff} starts it is using font
8918 position@tie{}1 (which must exist; position@tie{}0 is unused usually at
8919 start-up).
8921 @cindex font position register (@code{.f})
8922 The current font in use, as a font position, is available in the
8923 read-only number register @samp{.f}.  This can be useful to remember the
8924 current font for later recall.  It is associated with the current
8925 environment (@pxref{Environments}).
8927 @Example
8928 .nr save-font \n[.f]
8929 .ft B
8930 ... text text text ...
8931 .ft \n[save-font]
8932 @endExample
8934 @cindex next free font position register (@code{.fp})
8935 The number of the next free font position is available in the read-only
8936 number register @samp{.fp}.  This is useful when mounting a new font,
8937 like so:
8939 @Example
8940 .fp \n[.fp] NEATOFONT
8941 @endExample
8943 @pindex DESC@r{, and font mounting}
8944 Fonts not listed in the @file{DESC} file are automatically mounted on
8945 the next available font position when they are referenced.  If a font is
8946 to be mounted explicitly with the @code{fp} request on an unused font
8947 position, it should be mounted on the first unused font position, which
8948 can be found in the @code{.fp} register.  Although @code{gtroff} does
8949 not enforce this strictly, it is not allowed to mount a font at a
8950 position whose number is much greater (approx.@: 1000 positions) than
8951 that of any currently used position.
8953 The @code{fp} request has an optional third argument.  This argument
8954 gives the external name of the font, which is used for finding the font
8955 description file.  The second argument gives the internal name of the
8956 font which is used to refer to the font in @code{gtroff} after it has
8957 been mounted.  If there is no third argument then the internal name is
8958 used as the external name.  This feature makes it possible to use fonts
8959 with long names in compatibility mode.
8960 @endDefreq
8962 Both the @code{ft} request and the @code{\f} escape have alternative
8963 syntax forms to access font positions.
8965 @DefreqList {ft, nnn}
8966 @DefescItem {\\f, , n, }
8967 @DefescItem {\\f, @Lparen{}, nn, }
8968 @DefescListEnd {\\f, @Lbrack{}, nnn, @Rbrack{}}
8969 @cindex changing font position (@code{\f})
8970 @cindex font position, changing (@code{\f})
8971 @cindex @code{sty} request, and font positions
8972 @cindex @code{fam} request, and font positions
8973 @cindex @code{\F}, and font positions
8974 @kindex styles
8975 @kindex family
8976 @pindex DESC
8977 Change the current font position to @var{nnn} (one-digit
8978 position@tie{}@var{n}, two-digit position @var{nn}), which must be a
8979 non-negative integer.
8981 If @var{nnn} is associated with a style (as set with the @code{sty}
8982 request or with the @code{styles} command in the @file{DESC} file), use
8983 it within the current font family (as set with the @code{fam} request,
8984 the @code{\F} escape, or with the @code{family} command in the
8985 @file{DESC} file).
8987 @Example
8988 this is font 1
8989 .ft 2
8990 this is font 2
8991 .ft                   \" switch back to font 1
8992 .ft 3
8993 this is font 3
8995 this is font 1 again
8996 @endExample
8998 @xref{Changing Fonts}, for the standard syntax form.
8999 @endDefreq
9001 @c ---------------------------------------------------------------------
9003 @node Using Symbols, Special Fonts, Font Positions, Fonts and Symbols
9004 @subsection Using Symbols
9005 @cindex using symbols
9006 @cindex symbols, using
9008 @cindex glyph
9009 @cindex character
9010 @cindex ligature
9011 A @dfn{glyph} is a graphical representation of a @dfn{character}.  While
9012 a character is an abstract entity containing semantic information, a
9013 glyph is something which can be actually seen on screen or paper.  It is
9014 possible that a character has multiple glyph representation forms (for
9015 example, the character `A' can be either written in a roman or an italic
9016 font, yielding two different glyphs); sometimes more than one character
9017 maps to a single glyph (this is a @dfn{ligature} -- the most common is
9018 `fi').
9020 @cindex symbol
9021 @cindex special fonts
9022 @kindex fonts
9023 @pindex DESC
9024 @cindex @code{special} request, and glyph search order
9025 @cindex @code{fspecial} request, and glyph search order
9026 A @dfn{symbol} is simply a named glyph.  Within @code{gtroff}, all glyph
9027 names of a particular font are defined in its font file.  If the user
9028 requests a glyph not available in this font, @code{gtroff} looks up an
9029 ordered list of @dfn{special fonts}.  By default, the @sc{PostScript}
9030 output device supports the two special fonts @samp{SS} (slanted symbols)
9031 and @samp{S} (symbols) (the former is looked up before the latter).
9032 Other output devices use different names for special fonts.  Fonts
9033 mounted with the @code{fonts} keyword in the @file{DESC} file are
9034 globally available.  To install additional special fonts locally (i.e.@:
9035 for a particular font), use the @code{fspecial} request.
9037 Here the exact rules how @code{gtroff} searches a given symbol:
9039 @itemize @bullet
9040 @item
9041 If the symbol has been defined with the @code{char} request, use it.
9042 This hides a symbol with the same name in the current font.
9044 @item
9045 Check the current font.
9047 @item
9048 If the symbol has been defined with the @code{fchar} request, use it.
9050 @item
9051 Check whether the current font has a font-specific list of special
9052 fonts; test all fonts in the order of appearance in the last
9053 @code{fspecial} call if appropriate.
9055 @item
9056 If the symbol has been defined with the @code{fschar} request for the
9057 current font, use it.
9059 @item
9060 Check all fonts in the order of appearance in the last @code{special}
9061 call.
9063 @item
9064 If the symbol has been defined with the @code{schar} request, use it.
9066 @item
9067 As a last resort, consult all fonts loaded up to now for special fonts
9068 and check them, starting with the lowest font number.  Note that this
9069 can sometimes lead to surprising results since the @code{fonts} line in
9070 the @file{DESC} file often contains empty positions which are filled
9071 later on.  For example, consider the following:
9073 @Example
9074 fonts 3 0 0 FOO
9075 @endExample
9077 @noindent
9078 This mounts font @code{foo} at font position@tie{}3.  We assume that
9079 @code{FOO} is a special font, containing glyph @code{foo}, and that no
9080 font has been loaded yet.  The line
9082 @Example
9083 .fspecial BAR BAZ
9084 @endExample
9086 @noindent
9087 makes font @code{BAZ} special only if font @code{BAR} is active.  We
9088 further assume that @code{BAZ} is really a special font, i.e., the font
9089 description file contains the @code{special} keyword, and that it also
9090 contains glyph @code{foo} with a special shape fitting to font
9091 @code{BAR}.  After executing @code{fspecial}, font @code{BAR} is loaded
9092 at font position@tie{}1, and @code{BAZ} at position@tie{}2.
9094 We now switch to a new font @code{XXX}, trying to access glyph
9095 @code{foo} which is assumed to be missing.  There are neither
9096 font-specific special fonts for @code{XXX} nor any other fonts made
9097 special with the @code{special} request, so @code{gtroff} starts the
9098 search for special fonts in the list of already mounted fonts, with
9099 increasing font positions.  Consequently, it finds @code{BAZ} before
9100 @code{FOO} even for @code{XXX} which is not the intended behaviour.
9101 @end itemize
9103 @xref{Font Files}, and @ref{Special Fonts}, for more details.
9105 @cindex list of available glyphs (@cite{groff_char(7)} man page)
9106 @cindex available glyphs, list (@cite{groff_char(7)} man page)
9107 @cindex glyphs, available, list (@cite{groff_char(7)} man page)
9108 The list of available symbols is device dependent; see the
9109 @cite{groff_char(7)} man page for a complete list of all glyphs.  For
9110 example, say
9112 @Example
9113 man -Tdvi groff_char > groff_char.dvi
9114 @endExample
9116 @noindent
9117 for a list using the default DVI fonts (not all versions of the
9118 @code{man} program support the @option{-T} option).  If you want to use
9119 an additional macro package to change the used fonts, @code{groff} must
9120 be called directly:
9122 @Example
9123 groff -Tdvi -mec -man groff_char.7 > groff_char.dvi
9124 @endExample
9126 @cindex composite glyph names
9127 @cindex glyph names, composite
9128 @cindex groff glyph list (GGL)
9129 @cindex GGL (groff glyph list)
9130 @cindex adobe glyph list (AGL)
9131 @cindex AGL (adobe glyph list)
9132 Glyph names not listed in groff_char(7) are derived algorithmically,
9133 using a simplified version of the Adobe Glyph List (AGL) algorithm which
9134 is described in
9135 @uref{http://partners.adobe.com@//public@//developer@//opentype@//index_glyph.html}.
9136 The (frozen) set of glyph names which can't be derived algorithmically
9137 is called @dfn{groff glyph list (GGL)}.
9139 @itemize @bullet
9140 @item
9141 A glyph for Unicode character U+@var{XXXX}[@var{X}[@var{X}]] which is
9142 not a composite character is named
9143 @code{u@var{XXXX}@r{[}@var{X}@r{[}@var{X}@r{]]}}.  @var{X} must be an
9144 uppercase hexadecimal digit.  Examples: @code{u1234}, @code{u008E},
9145 @code{u12DB8}.  The largest Unicode value is 0x10FFFF.  There must be at
9146 least four @code{X} digits; if necessary, add leading zeroes (after the
9147 @samp{u}).  No zero padding is allowed for character codes greater than
9148 0xFFFF.  Surrogates (i.e., Unicode values greater than 0xFFFF
9149 represented with character codes from the surrogate area U+D800-U+DFFF)
9150 are not allowed too.
9152 @item
9153 A glyph representing more than a single input character is named
9155 @display
9156 @samp{u} @var{component1} @samp{_} @var{component2} @samp{_} @var{component3} @dots{}
9157 @end display
9159 @noindent
9160 Example: @code{u0045_0302_0301}.
9162 For simplicity, all Unicode characters which are composites must be
9163 decomposed maximally (this is normalization form@tie{}D in the Unicode
9164 standard); for example, @code{u00CA_0301} is not a valid glyph name
9165 since U+00CA (@sc{latin capital letter e with circumflex}) can be
9166 further decomposed into U+0045 (@sc{latin capital letter e}) and U+0302
9167 (@sc{combining circumflex accent}).  @code{u0045_0302_0301} is thus the
9168 glyph name for U+1EBE, @sc{latin capital letter e with circumflex and
9169 acute}.
9171 @item
9172 groff maintains a table to decompose all algorithmically derived glyph
9173 names which are composites itself.  For example, @code{u0100} (@sc{latin
9174 letter a with macron}) is automatically decomposed into
9175 @code{u0041_0304}.  Additionally, a glyph name of the GGL is preferred
9176 to an algorithmically derived glyph name; groff also automatically does
9177 the mapping.  Example: The glyph @code{u0045_0302} is mapped to
9178 @code{^E}.
9180 @item
9181 glyph names of the GGL can't be used in composite glyph names; for
9182 example, @code{^E_u0301} is invalid.
9183 @end itemize
9185 @DefescList {\\, @Lparen{}, nm, }
9186 @DefescItem {\\, @Lbrack{}, name, @Rbrack{}}
9187 @DefescListEnd {\\, @Lbrack{}, component1 component2 @dots{}, @Rbrack{}}
9188 Insert a symbol @var{name} (two-character name @var{nm}) or a composite
9189 glyph with component glyphs @var{component1}, @var{component2},
9190 @enddots{} There is no special syntax for one-character names -- the
9191 natural form @samp{\@var{n}} would collide with escapes.@footnote{Note
9192 that a one-character symbol is not the same as an input character, i.e.,
9193 the character @code{a} is not the same as @code{\[a]}.  By default,
9194 @code{groff} defines only a single one-character symbol, @code{\[-]}; it
9195 is usually accessed as @code{\-}.  On the other hand, @code{gtroff} has
9196 the special feature that @code{\[char@var{XXX}]} is the same as the
9197 input character with character code @var{XXX}.  For example,
9198 @code{\[char97]} is identical to the letter @code{a} if @acronym{ASCII}
9199 encoding is active.}
9201 If @var{name} is undefined, a warning of type @samp{char} is generated,
9202 and the escape is ignored.  @xref{Debugging}, for information about
9203 warnings.
9205 groff resolves @code{\[...]} with more than a single component as
9206 follows:
9208 @itemize @bullet
9209 @item
9210 Any component which is found in the GGL is converted to the
9211 @code{u@var{XXXX}} form.
9213 @item
9214 Any component @code{u@var{XXXX}} which is found in the list of
9215 decomposable glyphs is decomposed.
9217 @item
9218 The resulting elements are then concatenated with @samp{_} inbetween,
9219 dropping the leading @samp{u} in all elements but the first.
9220 @end itemize
9222 No check for the existence of any component (similar to @code{tr}
9223 request) is done.
9225 Examples:
9227 @table @code
9228 @item \[A ho]
9229 @samp{A} maps to @code{u0041}, @samp{ho} maps to @code{u02DB}, thus the
9230 final glyph name would be @code{u0041_02DB}.  Note this is not the
9231 expected result: The ogonek glyph @samp{ho} is a spacing ogonek, but for
9232 a proper composite a non-spacing ogonek (U+0328) is necessary.  Looking
9233 into the file @file{composite.tmac} one can find @w{@samp{.composite ho
9234 u0328}} which changes the mapping of @samp{ho} while a composite glyph
9235 name is constructed, causing the final glyph name to be
9236 @code{u0041_0328}.
9238 @item \[^E u0301]
9239 @itemx \[^E aa]
9240 @itemx \[E a^ aa]
9241 @itemx \[E ^ ']
9242 @samp{^E} maps to @code{u0045_0302}, thus the final glyph name is
9243 @code{u0045_0302_0301} in all forms (assuming proper calls of the
9244 @code{composite} request).
9245 @end table
9247 It is not possible to define glyphs with names like @w{@samp{A ho}}
9248 within a groff font file.  This is not really a limitation; instead, you
9249 have to define @code{u0041_0328}.
9250 @endDefesc
9252 @Defesc {\\C, ', xxx, '}
9253 @cindex named character (@code{\C})
9254 @cindex character, named (@code{\C})
9255 Typeset the glyph named @var{xxx}.@footnote{@code{\C} is actually a
9256 misnomer since it accesses an output glyph.}  Normally it is more
9257 convenient to use @code{\[@var{xxx}]}, but @code{\C} has the advantage
9258 that it is compatible with newer versions of @acronym{AT&T} @code{troff}
9259 and is available in compatibility mode.
9260 @endDefesc
9262 @Defreq {composite, from to}
9263 @pindex composite.tmac
9264 Map glyph name @var{from} to glyph name @var{to} if it is used in
9265 @code{\[...]} with more than one component.  See above for examples.
9267 This mapping is based on glyph names only; no check for the existence of
9268 either glyph is done.
9270 A set of default mappings for many accents can be found in the file
9271 @file{composite.tmac} which is loaded at start-up.
9272 @endDefreq
9274 @Defesc {\\N, ', n, '}
9275 @cindex numbered glyph (@code{\N})
9276 @cindex glyph, numbered (@code{\N})
9277 @cindex @code{char} request, used with @code{\N}
9278 @cindex Unicode
9279 Typeset the glyph with code@tie{}@var{n} in the current font
9280 (@code{n}@tie{}is @strong{not} the input character code).  The number
9281 @var{n}@tie{}can be any non-negative decimal integer.  Most devices only
9282 have glyphs with codes between 0 and@tie{}255; the Unicode output device
9283 uses codes in the range 0--65535.  If the current font does not contain
9284 a glyph with that code, special fonts are @emph{not} searched.  The
9285 @code{\N} escape sequence can be conveniently used in conjunction with
9286 the @code{char} request:
9288 @Example
9289 .char \[phone] \f[ZD]\N'37'
9290 @endExample
9292 @noindent
9293 @pindex DESC
9294 @cindex unnamed glyphs
9295 @cindex glyphs, unnamed
9296 The code of each glyph is given in the fourth column in the font
9297 description file after the @code{charset} command.  It is possible to
9298 include unnamed glyphs in the font description file by using a name of
9299 @samp{---}; the @code{\N} escape sequence is the only way to use these.
9301 No kerning is applied to glyphs accessed with @code{\N}.
9302 @endDefesc
9304 Some escape sequences directly map onto special glyphs.
9306 @Defesc {\\', , , }
9307 This is a backslash followed by the apostrophe character,
9308 @acronym{ASCII} character @code{0x27} (@acronym{EBCDIC} character
9309 @code{0x7D}).  The same as @code{\[aa]}, the acute accent.
9310 @endDefesc
9312 @Defesc {\\`, , , }
9313 This is a backslash followed by @acronym{ASCII} character @code{0x60}
9314 (@acronym{EBCDIC} character @code{0x79} usually).  The same as
9315 @code{\[ga]}, the grave accent.
9316 @endDefesc
9318 @Defesc {\\-, , , }
9319 This is the same as @code{\[-]}, the minus sign in the current font.
9320 @endDefesc
9322 @Defesc {\\_, , , }
9323 This is the same as @code{\[ul]}, the underline character.
9324 @endDefesc
9326 @Defreq {cflags, n c1 c2 @dots{}}
9327 @cindex glyph properties (@code{cflags})
9328 @cindex character properties (@code{cflags})
9329 @cindex properties of glyphs (@code{cflags})
9330 @cindex properties of characters (@code{cflags})
9331 Input characters and symbols have certain properties associated with
9332 it.@footnote{Note that the output glyphs themselves don't have such
9333 properties.  For @code{gtroff}, a glyph is a numbered box with a given
9334 width, depth, and height, nothing else.  All manipulations with the
9335 @code{cflags} request work on the input level.}  These properties can be
9336 modified with the @code{cflags} request.  The first argument is the sum
9337 of the desired flags and the remaining arguments are the characters or
9338 symbols to have those properties.  It is possible to omit the spaces
9339 between the characters or symbols.
9341 @table @code
9342 @item 1
9343 @cindex end-of-sentence characters
9344 @cindex characters, end-of-sentence
9345 The character ends sentences (initially characters @samp{.?!} have this
9346 property).
9348 @item 2
9349 @cindex hyphenating characters
9350 @cindex characters, hyphenation
9351 Lines can be broken before the character (initially no characters have
9352 this property).  This only works if both the characters before and after
9353 have non-zero hyphenation codes (as set with the @code{hcode} request).
9354 Use value@tie{}64 to override this behaviour.
9356 @item 4
9357 @cindex @code{hy} glyph, and @code{cflags}
9358 @cindex @code{em} glyph, and @code{cflags}
9359 Lines can be broken after the character (initially the character
9360 @samp{-} and the symbols @samp{\[hy]} and @samp{\[em]} have this
9361 property).  This only works if both the characters before and after have
9362 non-zero hyphenation codes (as set with the @code{hcode} request).  Use
9363 value@tie{}64 to override this behaviour.
9365 @item 8
9366 @cindex overlapping characters
9367 @cindex characters, overlapping
9368 @cindex @code{ul} glyph, and @code{cflags}
9369 @cindex @code{rn} glyph, and @code{cflags}
9370 @cindex @code{ru} glyph, and @code{cflags}
9371 @cindex @code{radicalex} glyph, and @code{cflags}
9372 @cindex @code{sqrtex} glyph, and @code{cflags}
9373 The character overlaps horizontally if used as a horizontal line
9374 building element.  Initially the symbols @samp{\[ul]}, @samp{\[rn]},
9375 @samp{\[ru]}, @samp{\[radicalex]}, and @samp{\[sqrtex]} have this
9376 property.
9378 @item 16
9379 @cindex @code{br} glyph, and @code{cflags}
9380 The character overlaps vertically if used as vertical line building
9381 element.  Initially symbol @samp{\[br]} has this property.
9383 @item 32
9384 @cindex transparent characters
9385 @cindex character, transparent
9386 @cindex @code{"}, at end of sentence
9387 @cindex @code{'}, at end of sentence
9388 @cindex @code{)}, at end of sentence
9389 @cindex @code{]}, at end of sentence
9390 @cindex @code{*}, at end of sentence
9391 @cindex @code{dg} glyph, at end of sentence
9392 @cindex @code{rq} glyph, at end of sentence
9393 An end-of-sentence character followed by any number of characters with
9394 this property is treated as the end of a sentence if followed by a
9395 newline or two spaces; in other words the character is @dfn{transparent}
9396 for the purposes of end-of-sentence recognition -- this is the same as
9397 having a zero space factor in @TeX{} (initially characters @samp{"')]*}
9398 and the symbols @samp{\[dg]} and @samp{\[rq]} have this property).
9400 @item 64
9401 Ignore hyphenation code values of the surrounding characters.  Use this
9402 in combination with values 2 and@tie{}4 (initially no characters have
9403 this property).  For example, if you need an automatic break point after
9404 the hyphen in number ranges like `3000-5000', insert
9406 @Example
9407 .cflags 68 -
9408 @endExample
9410 @noindent
9411 into your document.  Note, however, that this can lead to bad layout if
9412 done without thinking; in most situations, a better solution instead of
9413 changing the @code{cflags} value is to insert @code{\:} right after the
9414 hyphen at the places which really need a break point.
9415 @end table
9416 @endDefreq
9418 @DefreqList {char, g [@Var{string}]}
9419 @DefreqItem {fchar, g [@Var{string}]}
9420 @DefreqItem {fschar, f g [@Var{string}]}
9421 @DefreqListEnd {schar, g [@Var{string}]}
9422 @cindex defining character (@code{char})
9423 @cindex defining fallback character (@code{fchar}, @code{fschar}, @code{schar})
9424 @cindex character, defining (@code{char})
9425 @cindex character, defining fallback (@code{fchar}, @code{fschar}, @code{schar})
9426 @cindex fallback character, defining (@code{fchar}, @code{fschar}, @code{schar})
9427 @cindex creating new characters (@code{char})
9428 @cindex defining symbol (@code{char})
9429 @cindex symbol, defining (@code{char})
9430 @cindex defining glyph (@code{char})
9431 @cindex glyph, defining (@code{char})
9432 @cindex escape character, while defining glyph
9433 @cindex character, escape, while defining glyph
9434 @cindex @code{tr} request, and glyph definitions
9435 @cindex @code{cp} request, and glyph definitions
9436 @cindex @code{rc} request, and glyph definitions
9437 @cindex @code{lc} request, and glyph definitions
9438 @cindex @code{\l}, and glyph definitions
9439 @cindex @code{\L}, and glyph definitions
9440 @cindex @code{\&}, and glyph definitions
9441 @cindex @code{\e}, and glyph definitions
9442 @cindex @code{hcode} request, and glyph definitions
9443 Define a new glyph@tie{}@var{g} to be @var{string} (which can be
9444 empty).@footnote{@code{char} is a misnomer since an output glyph is
9445 defined.}  Every time glyph@tie{}@var{g} needs to be printed,
9446 @var{string} is processed in a temporary environment and the result is
9447 wrapped up into a single object.  Compatibility mode is turned off and
9448 the escape character is set to @samp{\} while @var{string} is being
9449 processed.  Any emboldening, constant spacing or track kerning is
9450 applied to this object rather than to individual characters in
9451 @var{string}.
9453 A glyph defined by these requests can be used just like a normal glyph
9454 provided by the output device.  In particular, other characters can be
9455 translated to it with the @code{tr} or @code{trin} requests; it can be
9456 made the leader character by the @code{lc} request; repeated patterns
9457 can be drawn with the glyph using the @code{\l} and @code{\L} escape
9458 sequences; words containing the glyph can be hyphenated correctly if the
9459 @code{hcode} request is used to give the glyph's symbol a hyphenation
9460 code.
9462 There is a special anti-recursion feature: Use of @code{g} within the
9463 glyph's definition is handled like normal characters and symbols not
9464 defined with @code{char}.
9466 Note that the @code{tr} and @code{trin} requests take precedence if
9467 @code{char} accesses the same symbol.
9469 @Example
9470 .tr XY
9472     @result{} Y
9473 .char X Z
9475     @result{} Y
9476 .tr XX
9478     @result{} Z
9479 @endExample
9481 The @code{fchar} request defines a fallback glyph: @code{gtroff} only
9482 checks for glyphs defined with @code{fchar} if it cannot find the glyph
9483 in the current font.  @code{gtroff} carries out this test before
9484 checking special fonts.
9486 @code{fschar} defines a fallback glyph for font@tie{}@var{f}:
9487 @code{gtroff} checks for glyphs defined with @code{fschar} after the
9488 list of fonts declared as font-specific special fonts with the
9489 @code{fspecial} request, but before the list of fonts declared as global
9490 special fonts with the @code{special} request.
9492 Finally, the @code{schar} request defines a global fallback glyph:
9493 @code{gtroff} checks for glyphs defined with @code{schar} after the list
9494 of fonts declared as global special fonts with the @code{special}
9495 request, but before the already mounted special fonts.
9497 @xref{Using Symbols}, for a detailed description of the glyph searching
9498 mechanism in @code{gtroff}.
9499 @endDefreq
9501 @DefreqList {rchar, c1 c2 @dots{}}
9502 @DefreqListEnd {rfschar, f c1 c2 @dots{}}
9503 @cindex removing glyph definition (@code{rchar}, @code{rfschar})
9504 @cindex glyph, removing definition (@code{rchar}, @code{rfschar})
9505 @cindex fallback glyph, removing definition (@code{rchar}, @code{rfschar})
9506 Remove the definitions of glyphs @var{c1}, @var{c2},@tie{}@enddots{}
9507 This undoes the effect of a @code{char}, @code{fchar}, or @code{schar}
9508 request.
9510 It is possible to omit the whitespace between arguments.
9512 The request @code{rfschar} removes glyph definitions defined with
9513 @code{fschar} for glyph@tie{}f.
9514 @endDefreq
9516 @xref{Special Characters}.
9518 @c ---------------------------------------------------------------------
9520 @node Special Fonts, Artificial Fonts, Using Symbols, Fonts and Symbols
9521 @subsection Special Fonts
9522 @cindex special fonts
9523 @cindex fonts, special
9525 Special fonts are those that @code{gtroff} searches when it cannot find
9526 the requested glyph in the current font.  The Symbol font is usually a
9527 special font.
9529 @code{gtroff} provides the following two requests to add more special
9530 fonts.  @xref{Using Symbols}, for a detailed description of the glyph
9531 searching mechanism in @code{gtroff}.
9533 Usually, only non-TTY devices have special fonts.
9535 @DefreqList {special, [@Var{s1} @Var{s2} @dots{}]}
9536 @DefreqListEnd {fspecial, f [@Var{s1} @Var{s2} @dots{}]}
9537 @kindex fonts
9538 @pindex DESC
9539 Use the @code{special} request to define special fonts.  Initially, this
9540 list is empty.
9542 Use the @code{fspecial} request to designate special fonts only when
9543 font@tie{}@var{f} is active.  Initially, this list is empty.
9545 Previous calls to @code{special} or @code{fspecial} are overwritten;
9546 without arguments, the particular list of special fonts is set to empty.
9547 Special fonts are searched in the order they appear as arguments.
9549 All fonts which appear in a call to @code{special} or @code{fspecial}
9550 are loaded.
9552 @xref{Using Symbols}, for the exact search order of glyphs.
9553 @endDefreq
9555 @c ---------------------------------------------------------------------
9557 @node Artificial Fonts, Ligatures and Kerning, Special Fonts, Fonts and Symbols
9558 @subsection Artificial Fonts
9559 @cindex artificial fonts
9560 @cindex fonts, artificial
9562 There are a number of requests and escapes for artificially creating
9563 fonts.  These are largely vestiges of the days when output devices did
9564 not have a wide variety of fonts, and when @code{nroff} and @code{troff}
9565 were separate programs.  Most of them are no longer necessary in GNU
9566 @code{troff}.  Nevertheless, they are supported.
9568 @DefescList {\\H, ', height, '}
9569 @DefescItem {\\H, ', @t{+}height, '}
9570 @DefescItem {\\H, ', @t{-}height, '}
9571 @DefregListEnd {.height}
9572 @cindex changing the font height (@code{\H})
9573 @cindex font height, changing (@code{\H})
9574 @cindex height, font, changing (@code{\H})
9575 Change (increment, decrement) the height of the current font, but not
9576 the width.  If @var{height} is zero, restore the original height.
9577 Default scaling indicator is @samp{z}.
9579 The read-only number register @code{.height} contains the font height as
9580 set by @code{\H}.
9582 Currently, only the @option{-Tps} device supports this feature.
9584 Note that @code{\H} doesn't produce an input token in @code{gtroff}.  As
9585 a consequence, it can be used in requests like @code{mc} (which expects
9586 a single character as an argument) to change the font on the fly:
9588 @Example
9589 .mc \H'+5z'x\H'0'
9590 @endExample
9592 In compatibility mode, @code{gtroff} behaves differently: If an
9593 increment or decrement is used, it is always taken relative to the
9594 current point size and not relative to the previously selected font
9595 height.  Thus,
9597 @Example
9598 .cp 1
9599 \H'+5'test \H'+5'test
9600 @endExample
9602 @noindent
9603 prints the word @samp{test} twice with the same font height (five points
9604 larger than the current font size).
9605 @endDefesc
9607 @DefescList {\\S, ', slant, '}
9608 @DefregListEnd {.slant}
9609 @cindex changing the font slant (@code{\S})
9610 @cindex font slant, changing (@code{\S})
9611 @cindex slant, font, changing (@code{\S})
9612 Slant the current font by @var{slant} degrees.  Positive values slant to
9613 the right.  Only integer values are possible.
9615 The read-only number register @code{.slant} contains the font slant as
9616 set by @code{\S}.
9618 Currently, only the @option{-Tps} device supports this feature.
9620 Note that @code{\S} doesn't produce an input token in @code{gtroff}.  As
9621 a consequence, it can be used in requests like @code{mc} (which expects
9622 a single character as an argument) to change the font on the fly:
9624 @Example
9625 .mc \S'20'x\S'0'
9626 @endExample
9628 This request is incorrectly documented in the original @acronym{UNIX}
9629 troff manual; the slant is always set to an absolute value.
9630 @endDefesc
9632 @Defreq {ul, [@Var{lines}]}
9633 @cindex underlining (@code{ul})
9634 The @code{ul} request normally underlines subsequent lines if a TTY
9635 output device is used.  Otherwise, the lines are printed in italics
9636 (only the term `underlined' is used in the following).  The single
9637 argument is the number of input lines to be underlined; with no
9638 argument, the next line is underlined.  If @var{lines} is zero or
9639 negative, stop the effects of @code{ul} (if it was active).  Requests
9640 and empty lines do not count for computing the number of underlined
9641 input lines, even if they produce some output like @code{tl}.  Lines
9642 inserted by macros (e.g.@: invoked by a trap) do count.
9644 At the beginning of @code{ul}, the current font is stored and the
9645 underline font is activated.  Within the span of a @code{ul} request, it
9646 is possible to change fonts, but after the last line affected by
9647 @code{ul} the saved font is restored.
9649 This number of lines still to be underlined is associated with the
9650 current environment (@pxref{Environments}).  The underline font can be
9651 changed with the @code{uf} request.
9653 @c XXX @xref should be changed to grotty
9655 @c @xref{Troff and Nroff Mode}, for a discussion how underlining is
9656 @c implemented in for TTY output devices, and which problems can arise.
9658 The @code{ul} request does not underline spaces.
9659 @endDefreq
9661 @Defreq {cu, [@Var{lines}]}
9662 @cindex continuous underlining (@code{cu})
9663 @cindex underlining, continuous (@code{cu})
9664 The @code{cu} request is similar to @code{ul} but underlines spaces as
9665 well (if a TTY output device is used).
9666 @endDefreq
9668 @Defreq {uf, font}
9669 @cindex underline font (@code{uf})
9670 @cindex font for underlining (@code{uf})
9671 Set the underline font (globally) used by @code{ul} and @code{cu}.  By
9672 default, this is the font at position@tie{}2.  @var{font} can be either
9673 a non-negative font position or the name of a font.
9674 @endDefreq
9676 @DefreqList {bd, font [@Var{offset}]}
9677 @DefreqItem {bd, font1 font2 [@Var{offset}]}
9678 @DefregListEnd {.b}
9679 @cindex imitating bold face (@code{bd})
9680 @cindex bold face, imitating (@code{bd})
9681 Artificially create a bold font by printing each glyph twice, slightly
9682 offset.
9684 Two syntax forms are available.
9686 @itemize @bullet
9687 @item
9688 Imitate a bold font unconditionally.  The first argument specifies the
9689 font to embolden, and the second is the number of basic units, minus
9690 one, by which the two glyphs are offset.  If the second argument is
9691 missing, emboldening is turned off.
9693 @var{font} can be either a non-negative font position or the name of a
9694 font.
9696 @var{offset} is available in the @code{.b} read-only register if a
9697 special font is active; in the @code{bd} request, its default unit is
9698 @samp{u}.
9700 @cindex @code{fspecial} request, and imitating bold
9701 @kindex special
9702 @cindex embolding of special fonts
9703 @cindex special fonts, emboldening
9704 @item
9705 Imitate a bold form conditionally.  Embolden @var{font1} by @var{offset}
9706 only if font @var{font2} is the current font.  This command can be
9707 issued repeatedly to set up different emboldening values for different
9708 current fonts.  If the second argument is missing, emboldening is turned
9709 off for this particular current font.
9711 This affects special fonts only (either set up with the @code{special}
9712 command in font files or with the @code{fspecial} request).
9713 @end itemize
9714 @endDefreq
9716 @Defreq {cs, font [@Var{width} [@Var{em-size}]]}
9717 @cindex constant glyph space mode (@code{cs})
9718 @cindex mode for constant glyph space (@code{cs})
9719 @cindex glyph, constant space
9720 @cindex @code{ps} request, and constant glyph space mode
9721 Switch to and from @dfn{constant glyph space mode}.  If activated, the
9722 width of every glyph is @math{@var{width}/36} ems.  The em size is given
9723 absolutely by @var{em-size}; if this argument is missing, the em value
9724 is taken from the current font size (as set with the @code{ps} request)
9725 when the font is effectively in use.  Without second and third argument,
9726 constant glyph space mode is deactivated.
9728 Default scaling indicator for @var{em-size} is @samp{z}; @var{width} is
9729 an integer.
9730 @endDefreq
9732 @c ---------------------------------------------------------------------
9734 @node Ligatures and Kerning,  , Artificial Fonts, Fonts and Symbols
9735 @subsection Ligatures and Kerning
9736 @cindex ligatures and kerning
9737 @cindex kerning and ligatures
9739 Ligatures are groups of characters that are run together, i.e, producing
9740 a single glyph.  For example, the letters `f' and `i' can form a
9741 ligature `fi' as in the word `file'.  This produces a cleaner look
9742 (albeit subtle) to the printed output.  Usually, ligatures are not
9743 available in fonts for TTY output devices.
9745 Most @sc{PostScript} fonts support the fi and fl ligatures.  The C/A/T
9746 typesetter that was the target of @acronym{AT&T} @code{troff} also
9747 supported `ff', `ffi', and `ffl' ligatures.  Advanced typesetters or
9748 `expert' fonts may include ligatures for `ft' and `ct', although GNU
9749 @code{troff} does not support these (yet).
9751 Only the current font is checked for ligatures and kerns; neither
9752 special fonts nor entities defined with the @code{char} request (and its
9753 siblings) are taken into account.
9755 @DefreqList {lg, [@Var{flag}]}
9756 @DefregListEnd {.lg}
9757 @cindex activating ligatures (@code{lg})
9758 @cindex ligatures, activating (@code{lg})
9759 @cindex ligatures enabled register (@code{.lg})
9760 Switch the ligature mechanism on or off; if the parameter is non-zero or
9761 missing, ligatures are enabled, otherwise disabled.  Default is on.  The
9762 current ligature mode can be found in the read-only number register
9763 @code{.lg} (set to 1 or@tie{}2 if ligatures are enabled,
9764 0@tie{}otherwise).
9766 Setting the ligature mode to@tie{}2 enables the two-character ligatures
9767 (fi, fl, and ff) and disables the three-character ligatures (ffi and
9768 ffl).
9769 @endDefreq
9771 @dfn{Pairwise kerning} is another subtle typesetting mechanism that
9772 modifies the distance between a glyph pair to improve readability.  In
9773 most cases (but not always) the distance is decreased.
9774 @iftex
9775 For example, compare the combination of the letters `V' and `A'.  With
9776 kerning, `VA' is printed.  Without kerning it appears as `V@w{}A'.
9777 @end iftex
9778 Typewriter-like fonts and fonts for terminals where all glyphs have the
9779 same width don't use kerning.
9781 @DefreqList {kern, [@Var{flag}]}
9782 @DefregListEnd {.kern}
9783 @cindex activating kerning (@code{kern})
9784 @cindex kerning, activating (@code{kern})
9785 @cindex kerning enabled register (@code{.kern})
9786 Switch kerning on or off.  If the parameter is non-zero or missing,
9787 enable pairwise kerning, otherwise disable it.  The read-only number
9788 register @code{.kern} is set to@tie{}1 if pairwise kerning is enabled,
9789 0@tie{}otherwise.
9791 @cindex zero width space character (@code{\&})
9792 @cindex character, zero width space (@code{\&})
9793 @cindex space character, zero width (@code{\&})
9794 If the font description file contains pairwise kerning information,
9795 glyphs from that font are kerned.  Kerning between two glyphs can be
9796 inhibited by placing @code{\&} between them: @samp{V\&A}.
9798 @xref{Font File Format}.
9799 @endDefreq
9801 @cindex track kerning
9802 @cindex kerning, track
9803 @dfn{Track kerning} expands or reduces the space between glyphs.  This
9804 can be handy, for example, if you need to squeeze a long word onto a
9805 single line or spread some text to fill a narrow column.  It must be
9806 used with great care since it is usually considered bad typography if
9807 the reader notices the effect.
9809 @Defreq {tkf, f s1 n1 s2 n2}
9810 @cindex activating track kerning (@code{tkf})
9811 @cindex track kerning, activating (@code{tkf})
9812 Enable track kerning for font@tie{}@var{f}.  If the current font
9813 is@tie{}@var{f} the width of every glyph is increased by an amount
9814 between @var{n1} and @var{n2} (@var{n1}, @var{n2} can be negative); if
9815 the current point size is less than or equal to @var{s1} the width is
9816 increased by @var{n1}; if it is greater than or equal to @var{s2} the
9817 width is increased by @var{n2}; if the point size is greater than or
9818 equal to @var{s1} and less than or equal to @var{s2} the increase in
9819 width is a linear function of the point size.
9821 The default scaling indicator is @samp{z} for @var{s1} and @var{s2},
9822 @samp{p} for @var{n1} and @var{n2}.
9824 Note that the track kerning amount is added even to the rightmost glyph
9825 in a line; for large values it is thus recommended to increase the line
9826 length by the same amount to compensate it.
9827 @endDefreq
9829 Sometimes, when typesetting letters of different fonts, more or less
9830 space at such boundaries are needed.  There are two escapes to help with
9831 this.
9833 @Defesc {\\/, , , }
9834 @cindex italic correction (@code{\/})
9835 @cindex correction, italic (@code{\/})
9836 @cindex correction between italic and roman glyph (@code{\/}, @code{\,})
9837 @cindex roman glyph, correction after italic glyph (@code{\/})
9838 @cindex italic glyph, correction before roman glyph (@code{\/})
9839 @cindex glyph, italic correction (@code{\/})
9840 Increase the width of the preceding glyph so that the spacing between
9841 that glyph and the following glyph is correct if the following glyph is
9842 a roman glyph.  For example, if an italic@tie{}@code{f} is immediately
9843 followed by a roman right parenthesis, then in many fonts the top right
9844 portion of the@tie{}@code{f} overlaps the top left of the right
9845 parenthesis.  Use this escape sequence whenever an italic glyph is
9846 immediately followed by a roman glyph without any intervening space.
9847 This small amount of space is also called @dfn{italic correction}.
9849 @iftex
9850 @c can't use @Example...@endExample here
9851 @example
9852 @group
9853 \f[I]f\f[R])
9854     @result{} {@it f}@r{)}
9855 \f[I]f\/\f[R])
9856     @result{} @i{f}@r{)}
9857 @end group
9858 @end example
9859 @end iftex
9860 @endDefesc
9862 @Defesc {\\\,, , , }
9863 @cindex left italic correction (@code{\,})
9864 @cindex correction, left italic (@code{\,})
9865 @cindex glyph, left italic correction (@code{\,})
9866 @cindex roman glyph, correction before italic glyph (@code{\,})
9867 @cindex italic glyph, correction after roman glyph (@code{\,})
9868 Modify the spacing of the following glyph so that the spacing between
9869 that glyph and the preceding glyph is correct if the preceding glyph is
9870 a roman glyph.  Use this escape sequence whenever a roman glyph is
9871 immediately followed by an italic glyph without any intervening space.
9872 In analogy to above, this space could be called @dfn{left italic
9873 correction}, but this term isn't used widely.
9875 @iftex
9876 @c can't use @Example...@endExample here
9877 @example
9878 @group
9879 q\f[I]f
9880     @result{} @r{q}@i{f}
9881 q\,\f[I]f
9882     @result{} @r{q}@math{@ptexcomma}@i{f}
9883 @end group
9884 @end example
9885 @end iftex
9886 @endDefesc
9888 @Defesc {\\&, , , }
9889 Insert a zero-width character, which is invisible.  Its intended use is
9890 to stop interaction of a character with its surrounding.
9892 @itemize @bullet
9893 @item
9894 It prevents the insertion of extra space after an end-of-sentence
9895 character.
9897 @Example
9898 Test.
9899 Test.
9900     @result{} Test.  Test.
9901 Test.\&
9902 Test.
9903     @result{} Test. Test.
9904 @endExample
9906 @item
9907 It prevents interpretation of a control character at the beginning of an
9908 input line.
9910 @Example
9911 .Test
9912     @result{} warning: `Test' not defined
9913 \&.Test
9914     @result{} .Test
9915 @endExample
9917 @item
9918 It prevents kerning between two glyphs.
9920 @iftex
9921 @c can't use @Example...@endExample here
9922 @example
9923 @group
9925     @result{} @r{VA}
9926 V\&A
9927     @result{} @r{V@w{}A}
9928 @end group
9929 @end example
9930 @end iftex
9932 @item
9933 It is needed to map an arbitrary character to nothing in the @code{tr}
9934 request (@pxref{Character Translations}).
9935 @end itemize
9936 @endDefesc
9938 @Defesc {\\), , , }
9939 This escape is similar to @code{\&} except that it behaves like a
9940 character declared with the @code{cflags} request to be transparent for
9941 the purposes of an end-of-sentence character.
9943 Its main usage is in macro definitions to protect against arguments
9944 starting with a control character.
9946 @Example
9947 .de xxx
9948 \)\\$1
9950 .de yyy
9951 \&\\$1
9953 This is a test.\c
9954 .xxx '
9955 This is a test.
9956     @result{}This is a test.'  This is a test.
9957 This is a test.\c
9958 .yyy '
9959 This is a test.
9960     @result{}This is a test.' This is a test.
9961 @endExample
9962 @endDefesc
9965 @c =====================================================================
9967 @node Sizes, Strings, Fonts and Symbols, gtroff Reference
9968 @section Sizes
9969 @cindex sizes
9971 @cindex baseline
9972 @cindex type size
9973 @cindex size of type
9974 @cindex vertical spacing
9975 @cindex spacing, vertical
9976 @code{gtroff} uses two dimensions with each line of text, type size and
9977 vertical spacing.  The @dfn{type size} is approximately the height of
9978 the tallest glyph.@footnote{This is usually the parenthesis.  Note that
9979 in most cases the real dimensions of the glyphs in a font are @emph{not}
9980 related to its type size!  For example, the standard @sc{PostScript}
9981 font families `Times Roman', `Helvetica', and `Courier' can't be used
9982 together at 10@dmn{pt}; to get acceptable output, the size of
9983 `Helvetica' has to be reduced by one point, and the size of `Courier'
9984 must be increased by one point.}  @dfn{Vertical spacing} is the amount
9985 of space @code{gtroff} allows for a line of text; normally, this is
9986 about 20%@tie{}larger than the current type size.  Ratios smaller than
9987 this can result in hard-to-read text; larger than this, it spreads the
9988 text out more vertically (useful for term papers).  By default,
9989 @code{gtroff} uses 10@tie{}point type on 12@tie{}point spacing.
9991 @cindex leading
9992 The difference between type size and vertical spacing is known, by
9993 typesetters, as @dfn{leading} (this is pronounced `ledding').
9995 @menu
9996 * Changing Type Sizes::
9997 * Fractional Type Sizes::
9998 @end menu
10000 @c ---------------------------------------------------------------------
10002 @node Changing Type Sizes, Fractional Type Sizes, Sizes, Sizes
10003 @subsection Changing Type Sizes
10005 @DefreqList {ps, [@Var{size}]}
10006 @DefreqItem {ps, @t{+}@Var{size}}
10007 @DefreqItem {ps, @t{-}@Var{size}}
10008 @DefescItem {\\s, , size, }
10009 @DefregListEnd {.s}
10010 @cindex changing type sizes (@code{ps}, @code{\s})
10011 @cindex type sizes, changing (@code{ps}, @code{\s})
10012 @cindex point sizes, changing (@code{ps}, @code{\s})
10013 Use the @code{ps} request or the @code{\s} escape to change (increase,
10014 decrease) the type size (in points).  Specify @var{size} as either an
10015 absolute point size, or as a relative change from the current size.  The
10016 size@tie{}0, or no argument, goes back to the previous size.
10018 Default scaling indicator of @code{size} is @samp{z}.  If @code{size} is
10019 zero or negative, it is set to 1@dmn{u}.
10021 @cindex type size registers (@code{.s}, @code{.ps})
10022 @cindex point size registers (@code{.s}, @code{.ps})
10023 The read-only number register @code{.s} returns the point size in points
10024 as a decimal fraction.  This is a string.  To get the point size in
10025 scaled points, use the @code{.ps} register instead.
10027 @code{.s} is associated with the current environment
10028 (@pxref{Environments}).
10030 @Example
10031 snap, snap,
10032 .ps +2
10033 grin, grin,
10034 .ps +2
10035 wink, wink, \s+2nudge, nudge,\s+8 say no more!
10036 .ps 10
10037 @endExample
10039 The @code{\s} escape may be called in a variety of ways.  Much like
10040 other escapes there must be a way to determine where the argument ends
10041 and the text begins.  Any of the following forms are valid:
10043 @table @code
10044 @item \s@var{n}
10045 Set the point size to @var{n}@tie{}points.  @var{n}@tie{}must be either
10046 0 or in the range 4 to@tie{}39.
10048 @item \s+@var{n}
10049 @itemx \s-@var{n}
10050 Increase or decrease the point size by @var{n}@tie{}points.
10051 @var{n}@tie{}must be exactly one digit.
10053 @item \s(@var{nn}
10054 Set the point size to @var{nn}@tie{}points.  @var{nn} must be exactly
10055 two digits.
10057 @item \s+(@var{nn}
10058 @itemx \s-(@var{nn}
10059 @itemx \s(+@var{nn}
10060 @itemx \s(-@var{nn}
10061 Increase or decrease the point size by @var{nn}@tie{}points.  @var{nn}
10062 must be exactly two digits.
10063 @end table
10065 Note that @code{\s} doesn't produce an input token in @code{gtroff}.  As
10066 a consequence, it can be used in requests like @code{mc} (which expects
10067 a single character as an argument) to change the font on the fly:
10069 @Example
10070 .mc \s[20]x\s[0]
10071 @endExample
10073 @xref{Fractional Type Sizes}, for yet another syntactical form of using
10074 the @code{\s} escape.
10075 @endDefreq
10077 @Defreq {sizes, s1 s2 @dots{} sn [0]}
10078 Some devices may only have certain permissible sizes, in which case
10079 @code{gtroff} rounds to the nearest permissible size.  The @file{DESC}
10080 file specifies which sizes are permissible for the device.
10082 Use the @code{sizes} request to change the permissible sizes for the
10083 current output device.  Arguments are in scaled points; the
10084 @code{sizescale} line in the @file{DESC} file for the output device
10085 provides the scaling factor.  For example, if the scaling factor is
10086 1000, then the value 12000 is 12@tie{}points.
10088 Each argument can be a single point size (such as @samp{12000}), or a
10089 range of sizes (such as @samp{4000-72000}).  You can optionally end the
10090 list with a zero.
10091 @endDefreq
10093 @DefreqList {vs, [@Var{space}]}
10094 @DefreqItem {vs, @t{+}@Var{space}}
10095 @DefreqItem {vs, @t{-}@Var{space}}
10096 @DefregListEnd {.v}
10097 @cindex changing vertical line spacing (@code{vs})
10098 @cindex vertical line spacing, changing (@code{vs})
10099 @cindex vertical line spacing register (@code{.v})
10100 Change (increase, decrease) the vertical spacing by @var{space}.  The
10101 default scaling indicator is @samp{p}.
10103 If @code{vs} is called without an argument, the vertical spacing is
10104 reset to the previous value before the last call to @code{vs}.
10106 @cindex @code{.V} register, and @code{vs}
10107 @code{gtroff} creates a warning of type @samp{range} if @var{space} is
10108 negative; the vertical spacing is then set to smallest positive value,
10109 the vertical resolution (as given in the @code{.V} register).
10111 Note that @w{@samp{.vs 0}} isn't saved in a diversion since it doesn't
10112 result in a vertical motion.  You explicitly have to repeat this command
10113 before inserting the diversion.
10115 The read-only number register @code{.v} contains the current vertical
10116 spacing; it is associated with the current environment
10117 (@pxref{Environments}).
10118 @endDefreq
10120 @cindex vertical line spacing, effective value
10121 The effective vertical line spacing consists of four components.
10122 Breaking a line causes the following actions (in the given order).
10124 @itemize @bullet
10125 @item
10126 @cindex extra pre-vertical line space (@code{\x})
10127 @cindex line space, extra pre-vertical (@code{\x})
10128 Move the current point vertically by the @dfn{extra pre-vertical line
10129 space}.  This is the minimum value of all @code{\x} escapes with a
10130 negative argument in the current output line.
10132 @item
10133 Move the current point vertically by the vertical line spacing as set
10134 with the @code{vs} request.
10136 @item
10137 Output the current line.
10139 @item
10140 @cindex extra post-vertical line space (@code{\x})
10141 @cindex line space, extra post-vertical (@code{\x})
10142 Move the current point vertically by the @dfn{extra post-vertical line
10143 space}.  This is the maximum value of all @code{\x} escapes with a
10144 positive argument in the line which has just been output.
10146 @item
10147 @cindex post-vertical line spacing
10148 @cindex line spacing, post-vertical (@code{pvs})
10149 Move the current point vertically by the @dfn{post-vertical line
10150 spacing} as set with the @code{pvs} request.
10151 @end itemize
10153 @cindex double-spacing (@code{vs}, @code{pvs})
10154 It is usually better to use @code{vs} or @code{pvs} instead of @code{ls}
10155 to produce double-spaced documents: @code{vs} and @code{pvs} have a
10156 finer granularity for the inserted vertical space compared to @code{ls};
10157 furthermore, certain preprocessors assume single-spacing.
10159 @xref{Manipulating Spacing}, for more details on the @code{\x} escape
10160 and the @code{ls} request.
10162 @DefreqList {pvs, [@Var{space}]}
10163 @DefreqItem {pvs, @t{+}@Var{space}}
10164 @DefreqItem {pvs, @t{-}@Var{space}}
10165 @DefregListEnd {.pvs}
10166 @cindex @code{ls} request, alternative to (@code{pvs})
10167 @cindex post-vertical line spacing, changing (@code{pvs})
10168 @cindex post-vertical line spacing register (@code{.pvs})
10169 Change (increase, decrease) the post-vertical spacing by @var{space}.
10170 The default scaling indicator is @samp{p}.
10172 If @code{pvs} is called without an argument, the post-vertical spacing
10173 is reset to the previous value before the last call to @code{pvs}.
10175 @code{gtroff} creates a warning of type @samp{range} if @var{space} is
10176 zero or negative; the vertical spacing is then set to zero.
10178 The read-only number register @code{.pvs} contains the current
10179 post-vertical spacing; it is associated with the current environment
10180 (@pxref{Environments}).
10181 @endDefreq
10183 @c ---------------------------------------------------------------------
10185 @node Fractional Type Sizes,  , Changing Type Sizes, Sizes
10186 @subsection Fractional Type Sizes
10187 @cindex fractional type sizes
10188 @cindex fractional point sizes
10189 @cindex type sizes, fractional
10190 @cindex point sizes, fractional
10191 @cindex sizes, fractional
10193 @cindex @code{s} unit
10194 @cindex unit, @code{s}
10195 @cindex @code{z} unit
10196 @cindex unit, @code{z}
10197 @cindex @code{ps} request, with fractional type sizes
10198 @cindex @code{cs} request, with fractional type sizes
10199 @cindex @code{tkf} request, with fractional type sizes
10200 @cindex @code{\H}, with fractional type sizes
10201 @cindex @code{\s}, with fractional type sizes
10202 A @dfn{scaled point} is equal to @math{1/@var{sizescale}} points, where
10203 @var{sizescale} is specified in the @file{DESC} file (1@tie{}by
10204 default).  There is a new scale indicator @samp{z} which has the effect
10205 of multiplying by @var{sizescale}.  Requests and escape sequences in
10206 @code{gtroff} interpret arguments that represent a point size as being
10207 in units of scaled points, but they evaluate each such argument using a
10208 default scale indicator of @samp{z}.  Arguments treated in this way are
10209 the argument to the @code{ps} request, the third argument to the
10210 @code{cs} request, the second and fourth arguments to the @code{tkf}
10211 request, the argument to the @code{\H} escape sequence, and those
10212 variants of the @code{\s} escape sequence that take a numeric expression
10213 as their argument (see below).
10215 For example, suppose @var{sizescale} is@tie{}1000; then a scaled point
10216 is equivalent to a millipoint; the request @w{@samp{.ps 10.25}} is
10217 equivalent to @w{@samp{.ps 10.25z}} and thus sets the point size to
10218 10250@tie{}scaled points, which is equal to 10.25@tie{}points.
10220 @code{gtroff} disallows the use of the @samp{z} scale indicator in
10221 instances where it would make no sense, such as a numeric expression
10222 whose default scale indicator was neither @samp{u} nor @samp{z}.
10223 Similarly it would make no sense to use a scaling indicator other than
10224 @samp{z} or @samp{u} in a numeric expression whose default scale
10225 indicator was @samp{z}, and so @code{gtroff} disallows this as well.
10227 There is also new scale indicator @samp{s} which multiplies by the
10228 number of units in a scaled point.  So, for example, @samp{\n[.ps]s} is
10229 equal to @samp{1m}.  Be sure not to confuse the @samp{s} and @samp{z}
10230 scale indicators.
10232 @Defreg {.ps}
10233 A read-only number register returning the point size in scaled points.
10235 @code{.ps} is associated with the current environment
10236 (@pxref{Environments}).
10237 @endDefreg
10239 @DefregList {.psr}
10240 @DefregListEnd {.sr}
10241 @cindex last-requested point size registers (@code{.psr}, @code{.sr})
10242 @cindex point size registers, last-requested (@code{.psr}, @code{.sr})
10243 @cindex @code{.ps} register, in comparison with @code{.psr}
10244 @cindex @code{.s} register, in comparison with @code{.sr}
10245 The last-requested point size in scaled points is contained in the
10246 @code{.psr} read-only number register.  The last requested point size in
10247 points as a decimal fraction can be found in @code{.sr}.  This is a
10248 string-valued read-only number register.
10250 Note that the requested point sizes are device-independent, whereas the
10251 values returned by the @code{.ps} and @code{.s} registers are not.  For
10252 example, if a point size of 11@dmn{pt} is requested, and a @code{sizes}
10253 request (or a @code{sizescale} line in a @file{DESC} file) specifies
10254 10.95@dmn{pt} instead, this value is actually used.
10256 Both registers are associated with the current environment
10257 (@pxref{Environments}).
10258 @endDefreg
10260 The @code{\s} escape has the following syntax for working with
10261 fractional type sizes:
10263 @table @code
10264 @item \s[@var{n}]
10265 @itemx \s'@var{n}'
10266 Set the point size to @var{n}@tie{}scaled points; @var{n}@tie{}is a
10267 numeric expression with a default scale indicator of @samp{z}.
10269 @item \s[+@var{n}]
10270 @itemx \s[-@var{n}]
10271 @itemx \s+[@var{n}]
10272 @itemx \s-[@var{n}]
10273 @itemx \s'+@var{n}'
10274 @itemx \s'-@var{n}'
10275 @itemx \s+'@var{n}'
10276 @itemx \s-'@var{n}'
10277 Increase or or decrease the point size by @var{n}@tie{}scaled points;
10278 @var{n}@tie{}is a numeric expression (which may start with a minus sign)
10279 with a default scale indicator of @samp{z}.
10280 @end table
10282 @xref{Font Files}.
10285 @c =====================================================================
10287 @node Strings, Conditionals and Loops, Sizes, gtroff Reference
10288 @section Strings
10289 @cindex strings
10291 @code{gtroff} has string variables, which are entirely for user
10292 convenience (i.e.@: there are no built-in strings exept @code{.T}, but
10293 even this is a read-write string variable).
10295 @DefreqList {ds, name [@Var{string}]}
10296 @DefreqItem {ds1, name [@Var{string}]}
10297 @DefescItem {\\*, , n, }
10298 @DefescItem {\\*, @Lparen{}, nm, }
10299 @DefescListEnd {\\*, @Lbrack{}, name arg1 arg2 @dots{}, @Rbrack{}}
10300 @cindex string interpolation (@code{\*})
10301 @cindex string expansion (@code{\*})
10302 @cindex interpolation of strings (@code{\*})
10303 @cindex expansion of strings (@code{\*})
10304 @cindex string arguments
10305 @cindex arguments, of strings
10306 Define and access a string variable @var{name} (one-character
10307 name@tie{}@var{n}, two-character name @var{nm}).  If @var{name} already
10308 exists, @code{ds} overwrites the previous definition.  Only the syntax
10309 form using brackets can take arguments which are handled identically to
10310 macro arguments; the single exception is that a closing bracket as an
10311 argument must be enclosed in double quotes.  @xref{Request and Macro
10312 Arguments}, and @ref{Parameters}.
10314 Example:
10316 @Example
10317 .ds foo a \\$1 test
10319 This is \*[foo nice].
10320     @result{} This is a nice test.
10321 @endExample
10323 The @code{\*} escape @dfn{interpolates} (expands in-place) a
10324 previously-defined string variable.  To be more precise, the stored
10325 string is pushed onto the input stack which is then parsed by
10326 @code{gtroff}.  Similar to number registers, it is possible to nest
10327 strings, i.e. string variables can be called within string variables.
10329 If the string named by the @code{\*} escape does not exist, it is
10330 defined as empty, and a warning of type @samp{mac} is emitted (see
10331 @ref{Debugging}, for more details).
10333 @cindex comments, with @code{ds}
10334 @cindex @code{ds} request, and comments
10335 @strong{Caution:} Unlike other requests, the second argument to the
10336 @code{ds} request takes up the entire line including trailing spaces.
10337 This means that comments on a line with such a request can introduce
10338 unwanted space into a string.
10340 @Example
10341 .ds UX \s-1UNIX\s0\u\s-3tm\s0\d \" UNIX trademark
10342 @endExample
10344 @noindent
10345 Instead the comment should be put on another line or have the comment
10346 escape adjacent with the end of the string.
10348 @Example
10349 .ds UX \s-1UNIX\s0\u\s-3tm\s0\d\"  UNIX trademark
10350 @endExample
10352 @cindex trailing quotes
10353 @cindex quotes, trailing
10354 @cindex leading spaces with @code{ds}
10355 @cindex spaces with @code{ds}
10356 @cindex @code{ds} request, and leading spaces
10357 To produce leading space the string can be started with a double quote.
10358 No trailing quote is needed; in fact, any trailing quote is included in
10359 your string.
10361 @Example
10362 .ds sign "           Yours in a white wine sauce,
10363 @endExample
10365 @cindex multi-line strings
10366 @cindex strings, multi-line
10367 @cindex newline character, in strings, escaping
10368 @cindex escaping newline characters, in strings
10369 Strings are not limited to a single line of text.  A string can span
10370 several lines by escaping the newlines with a backslash.  The resulting
10371 string is stored @emph{without} the newlines.
10373 @Example
10374 .ds foo lots and lots \
10375 of text are on these \
10376 next several lines
10377 @endExample
10379 It is not possible to have real newlines in a string.  To put a single
10380 double quote character into a string, use two consecutive double quote
10381 characters.
10383 The @code{ds1} request turns off compatibility mode while interpreting a
10384 string.  To be more precise, a @dfn{compatibility save} input token is
10385 inserted at the beginning of the string, and a @dfn{compatibility
10386 restore} input token at the end.
10388 @Example
10389 .nr xxx 12345
10390 .ds aa The value of xxx is \\n[xxx].
10391 .ds1 bb The value of xxx ix \\n[xxx].
10393 .cp 1
10395 \*(aa
10396     @result{} warning: number register `[' not defined
10397     @result{} The value of xxx is 0xxx].
10398 \*(bb
10399     @result{} The value of xxx ix 12345.
10400 @endExample
10402 @cindex name space, common, of macros, diversions, and strings
10403 @cindex common name space of macros, diversions, and strings
10404 @cindex macros, shared name space with strings and diversions
10405 @cindex strings, shared name space with macros and diversions
10406 @cindex diversions, shared name space with macros and strings
10407 Strings, macros, and diversions (and boxes) share the same name space.
10408 Internally, even the same mechanism is used to store them.  This has
10409 some interesting consequences.  For example, it is possible to call a
10410 macro with string syntax and vice versa.
10412 @Example
10413 .de xxx
10414 a funny test.
10416 This is \*[xxx]
10417     @result{} This is a funny test.
10419 .ds yyy a funny test
10420 This is
10421 .yyy
10422     @result{} This is a funny test.
10423 @endExample
10425 In particular, interpolating a string does not hide existing macro
10426 arguments.  Thus in a macro, a more efficient way of doing
10428 @Example
10429 .xx \\$@@
10430 @endExample
10432 @noindent
10435 @Example
10436 \\*[xx]\\
10437 @endExample
10439 @noindent
10440 Note that the latter calling syntax doesn't change the value of
10441 @code{\$0}, which is then inherited from the calling macro.
10443 Diversions and boxes can be also called with string syntax.
10445 Another consequence is that you can copy one-line diversions or boxes to
10446 a string.
10448 @Example
10449 .di xxx
10450 a \fItest\fR
10453 .ds yyy This is \*[xxx]\c
10454 \*[yyy].
10455     @result{} @r{This is a }@i{test}.
10456 @endExample
10458 @noindent
10459 As the previous example shows, it is possible to store formatted output
10460 in strings.  The @code{\c} escape prevents the insertion of an
10461 additional blank line in the output.
10463 Copying diversions longer than a single output line produces unexpected
10464 results.
10466 @Example
10467 .di xxx
10468 a funny
10470 test
10473 .ds yyy This is \*[xxx]\c
10474 \*[yyy].
10475     @result{} test This is a funny.
10476 @endExample
10478 Usually, it is not predictable whether a diversion contains one or more
10479 output lines, so this mechanism should be avoided.  With @acronym{UNIX}
10480 @code{troff}, this was the only solution to strip off a final newline
10481 from a diversion.  Another disadvantage is that the spaces in the copied
10482 string are already formatted, making them unstretchable.  This can cause
10483 ugly results.
10485 @cindex stripping final newline in diversions
10486 @cindex diversion, stripping final newline
10487 @cindex final newline, stripping in diversions
10488 @cindex newline, final, stripping in diversions
10489 @cindex horizontal space, unformatting
10490 @cindex space, horizontal, unformatting
10491 @cindex unformatting horizontal space
10492 A clean solution to this problem is available in GNU @code{troff}, using
10493 the requests @code{chop} to remove the final newline of a diversion, and
10494 @code{unformat} to make the horizontal spaces stretchable again.
10496 @Example
10497 .box xxx
10498 a funny
10500 test
10502 .box
10503 .chop xxx
10504 .unformat xxx
10505 This is \*[xxx].
10506     @result{} This is a funny test.
10507 @endExample
10509 @xref{Gtroff Internals}, for more information.
10510 @endDefreq
10512 @DefreqList {as, name [@Var{string}]}
10513 @DefreqListEnd {as1, name [@Var{string}]}
10514 @cindex appending to a string (@code{as})
10515 @cindex string, appending (@code{as})
10516 The @code{as} request is similar to @code{ds} but appends @var{string}
10517 to the string stored as @var{name} instead of redefining it.  If
10518 @var{name} doesn't exist yet, it is created.
10520 @Example
10521 .as sign " with shallots, onions and garlic,
10522 @endExample
10524 The @code{as1} request is similar to @code{as}, but compatibility mode
10525 is switched off while the appended string is interpreted.  To be more
10526 precise, a @dfn{compatibility save} input token is inserted at the
10527 beginning of the appended string, and a @dfn{compatibility restore}
10528 input token at the end.
10529 @endDefreq
10531 Rudimentary string manipulation routines are given with the next two
10532 requests.
10534 @Defreq {substring, str n1 [@Var{n2}]}
10535 @cindex substring (@code{substring})
10536 Replace the string named @var{str} with the substring defined by the
10537 indices @var{n1} and@tie{}@var{n2}.  The first character in the string
10538 has index@tie{}0.  If @var{n2} is omitted, it is taken to be equal to
10539 the string's length.  If the index value @var{n1} or @var{n2} is
10540 negative, it is counted from the end of the string, going backwards: The
10541 last character has index@tie{}@minus{}1, the character before the last
10542 character has index@tie{}@minus{}2, etc.
10544 @Example
10545 .ds xxx abcdefgh
10546 .substring xxx 1 -4
10547 \*[xxx]
10548     @result{} bcde
10549 @endExample
10550 @endDefreq
10552 @Defreq {length, reg str}
10553 @cindex length of a string (@code{length})
10554 @cindex string, length of (@code{length})
10555 @cindex @code{length} request, and copy-in mode
10556 @cindex copy-in mode, and @code{length} request
10557 @cindex mode, copy-in, and @code{length} request
10558 Compute the number of characters of @var{str} and return it in the
10559 number register @var{reg}.  If @var{reg} doesn't exist, it is created.
10560 @code{str} is read in copy mode.
10562 @Example
10563 .ds xxx abcd\h'3i'efgh
10564 .length yyy \*[xxx]
10565 \n[yyy]
10566     @result{} 14
10567 @endExample
10568 @endDefreq
10570 @Defreq {rn, xx yy}
10571 @cindex renaming request (@code{rn})
10572 @cindex request, renaming (@code{rn})
10573 @cindex renaming macro (@code{rn})
10574 @cindex macro, renaming (@code{rn})
10575 @cindex renaming string (@code{rn})
10576 @cindex string, renaming (@code{rn})
10577 @cindex renaming diversion (@code{rn})
10578 @cindex diversion, renaming (@code{rn})
10579 Rename the request, macro, diversion, or string @var{xx} to @var{yy}.
10580 @endDefreq
10582 @Defreq {rm, xx}
10583 @cindex removing request (@code{rm})
10584 @cindex request, removing (@code{rm})
10585 @cindex removing macro (@code{rm})
10586 @cindex macro, removing (@code{rm})
10587 @cindex removing string (@code{rm})
10588 @cindex string, removing (@code{rm})
10589 @cindex removing diversion (@code{rm})
10590 @cindex diversion, removing (@code{rm})
10591 Remove the request, macro, diversion, or string @var{xx}.  @code{gtroff}
10592 treats subsequent invocations as if the object had never been defined.
10593 @endDefreq
10595 @Defreq {als, new old}
10596 @cindex alias, string, creating (@code{als})
10597 @cindex alias, macro, creating (@code{als})
10598 @cindex alias, diversion, creating (@code{als})
10599 @cindex creating alias, for string (@code{als})
10600 @cindex creating alias, for macro (@code{als})
10601 @cindex creating alias, for diversion (@code{als})
10602 @cindex string, creating alias (@code{als})
10603 @cindex macro, creating alias (@code{als})
10604 @cindex diversion, creating alias (@code{als})
10605 Create an alias named @var{new} for the request, string, macro, or
10606 diversion object named @var{old}.  The new name and the old name are
10607 exactly equivalent (it is similar to a hard rather than a soft link). If
10608 @var{old} is undefined, @code{gtroff} generates a warning of type
10609 @samp{mac} and ignores the request.
10610 @endDefreq
10612 @Defreq {chop, xx}
10613 Remove (chop) the last character from the macro, string, or diversion
10614 named @var{xx}.  This is useful for removing the newline from the end of
10615 diversions that are to be interpolated as strings.  This command can be
10616 used repeatedly; see @ref{Gtroff Internals}, for details on nodes
10617 inserted additionally by @code{gtroff}.
10618 @endDefreq
10620 @xref{Identifiers}, and @ref{Comments}.
10623 @c =====================================================================
10625 @node Conditionals and Loops, Writing Macros, Strings, gtroff Reference
10626 @section Conditionals and Loops
10627 @cindex conditionals and loops
10628 @cindex loops and conditionals
10630 @menu
10631 * Operators in Conditionals::
10632 * if-else::
10633 * while::
10634 @end menu
10636 @c ---------------------------------------------------------------------
10638 @node Operators in Conditionals, if-else, Conditionals and Loops, Conditionals and Loops
10639 @subsection Operators in Conditionals
10641 @cindex @code{if} request, operators to use with
10642 @cindex @code{ie} request, operators to use with
10643 @cindex @code{while} request, operators to use with
10644 In @code{if}, @code{ie}, and @code{while} requests, there are several
10645 more operators available:
10647 @table @code
10648 @item e
10649 @itemx o
10650 True if the current page is even or odd numbered (respectively).
10652 @item n
10653 @cindex conditional output for terminal (TTY)
10654 @cindex TTY, conditional output for
10655 @cindex terminal, conditional output for
10656 True if the document is being processed in nroff mode (i.e., the
10657 @code{.nroff} command has been issued).  @xref{Troff and Nroff Mode}.
10659 @item t
10660 True if the document is being processed in troff mode (i.e., the
10661 @code{.troff} command has been issued).  @xref{Troff and Nroff Mode}.
10663 @item v
10664 Always false.  This condition is for compatibility with other
10665 @code{troff} versions only (identifying a @code{-Tversatec} device).
10667 @item '@var{xxx}'@var{yyy}'
10668 True if the output produced by @var{xxx} is equal to the output produced
10669 by @var{yyy}.  Other characters can be used in place of the single
10670 quotes; the same set of delimiters as for the @code{\D} escape is used
10671 (@pxref{Escapes}).  @code{gtroff} formats @var{xxx} and @var{yyy} in
10672 separate environments; after the comparison the resulting data is
10673 discarded.
10675 @Example
10676 .ie "|"\fR|\fP" \
10677 true
10678 .el \
10679 false
10680     @result{} true
10681 @endExample
10683 @noindent
10684 The resulting motions, glyph sizes, and fonts have to
10685 match,@footnote{The created output nodes must be identical.
10686 @xref{Gtroff Internals}.} and not the individual motion, size, and font
10687 requests.  In the previous example, @samp{|} and @samp{\fR|\fP} both
10688 result in a roman @samp{|} glyph with the same point size and at the
10689 same location on the page, so the strings are equal.  If
10690 @samp{.ft@tie{}I} had been added before the @samp{.ie}, the result would
10691 be ``false'' because (the first) @samp{|} produces an italic @samp{|}
10692 rather than a roman one.
10694 @cindex string comparison
10695 @cindex comparison of strings
10696 To compare strings without processing, surround the data with @code{\?}.
10698 @Example
10699 .ie "\?|\?"\?\fR|\fP\?" \
10700 true
10701 .el \
10702 false
10703     @result{} false
10704 @endExample
10706 @cindex @code{\?}, and copy-in mode
10707 @cindex copy-in mode, and @code{\?}
10708 @cindex mode, copy-in, and @code{\?}
10709 @noindent
10710 Since data protected with @code{\?} is read in copy-in mode it is even
10711 possible to use incomplete input without causing an error.
10713 @Example
10714 .ds a \[
10715 .ds b \[
10716 .ie '\?\*a\?'\?\*b\?' \
10717 true
10718 .el \
10719 false
10720     @result{} true
10721 @endExample
10723 @item r @var{xxx}
10724 True if there is a number register named @var{xxx}.
10726 @item d @var{xxx}
10727 True if there is a string, macro, diversion, or request named @var{xxx}.
10729 @item m @var{xxx}
10730 True if there is a color named @var{xxx}.
10732 @item c @var{g}
10733 True if there is a glyph @var{g} available@footnote{The name of this
10734 conditional operator is a misnomer since it tests names of output
10735 glyphs.}; @var{g} is either an @acronym{ASCII} character or a special
10736 character (@code{\N'@var{xxx}'}, @code{\(@var{gg}} or
10737 @code{\[@var{ggg}]}); the condition is also true if @var{g} has been
10738 defined by the @code{char} request.
10740 @item F @var{font}
10741 True if a font named @var{font} exists.  @var{font} is handled as if it
10742 was opened with the @code{ft} request (this is, font translation and
10743 styles are applied), without actually mounting it.
10745 This test doesn't load the complete font but only its header to verify
10746 its validity.
10748 @item S @var{style}
10749 True if style @var{style} has been registered.  Font translation is
10750 applied.
10751 @end table
10753 Note that these operators can't be combined with other operators like
10754 @samp{:} or @samp{&}; only a leading @samp{!} (without whitespace
10755 between the exclamation mark and the operator) can be used to negate the
10756 result.
10758 @Example
10759 .nr xxx 1
10760 .ie !r xxx \
10761 true
10762 .el \
10763 false
10764     @result{} false
10765 @endExample
10767 A whitespace after @samp{!} always evaluates to zero (this bizarre
10768 behaviour is due to compatibility with @acronym{UNIX} @code{troff}).
10770 @Example
10771 .nr xxx 1
10772 .ie ! r xxx \
10773 true
10774 .el \
10775 false
10776     @result{} r xxx true
10777 @endExample
10779 It is possible to omit the whitespace before the argument to the
10780 @samp{r}, @samp{d}, and @samp{c} operators.
10782 @xref{Expressions}.
10784 @c ---------------------------------------------------------------------
10786 @node if-else, while, Operators in Conditionals, Conditionals and Loops
10787 @subsection if-else
10788 @cindex if-else
10790 @code{gtroff} has if-then-else constructs like other languages, although
10791 the formatting can be painful.
10793 @Defreq {if, expr anything}
10795 Evaluate the expression @var{expr}, and executes @var{anything} (the
10796 remainder of the line) if @var{expr} evaluates to a value greater than
10797 zero (true).  @var{anything} is interpreted as though it was on a line
10798 by itself (except that leading spaces are swallowed).
10799 @xref{Expressions}, for more info.
10801 @Example
10802 .nr xxx 1
10803 .nr yyy 2
10804 .if ((\n[xxx] == 1) & (\n[yyy] == 2)) true
10805     @result{} true
10806 @endExample
10807 @endDefreq
10809 @Defreq {nop, anything}
10810 Executes @var{anything}.  This is similar to @code{.if@tie{}1}.
10811 @endDefreq
10813 @DefreqList {ie, expr anything}
10814 @DefreqListEnd {el, anything}
10815 Use the @code{ie} and @code{el} requests to write an if-then-else.  The
10816 first request is the `if' part and the latter is the `else' part.
10818 @Example
10819 .ie n .ls 2 \" double-spacing in nroff
10820 .el   .ls 1 \" single-spacing in troff
10821 @endExample
10822 @endDefreq
10824 @c there is a bug in makeinfo <= 4.1a: you can't have `@{' as an argument
10825 @c to @deffn
10827 @c and in 4.2 you still can't use @{ in macros.
10829 @c @DefescList {\@{, , , }
10830 @c @DefescListEnd {\@}, , , }
10831 @deffn Escape @t{\@{}
10832 @deffnx Escape @t{\@}}
10833 @esindex \@{
10834 @esindex \@}
10835 @cindex begin of conditional block (@code{\@{})
10836 @cindex end of conditional block (@code{\@}})
10837 @cindex conditional block, begin (@code{\@{})
10838 @cindex conditional block, end (@code{\@}})
10839 @cindex block, conditional, begin (@code{\@{})
10840 @cindex block, condititional, end (@code{\@}})
10841 In many cases, an if (or if-else) construct needs to execute more than
10842 one request.  This can be done using the @code{\@{} and @code{\@}}
10843 escapes.  The following example shows the possible ways to use these
10844 escapes (note the position of the opening and closing braces).
10846 @Example
10847 .ie t \@{\
10848 .    ds lq ``
10849 .    ds rq ''
10850 .\@}
10851 .el \
10852 .\@{\
10853 .    ds lq "
10854 .    ds rq "\@}
10855 @endExample
10856 @c @endDefesc
10857 @end deffn
10859 @xref{Expressions}.
10861 @c ---------------------------------------------------------------------
10863 @node while,  , if-else, Conditionals and Loops
10864 @subsection while
10865 @cindex while
10867 @code{gtroff} provides a looping construct using the @code{while}
10868 request, which is used much like the @code{if} (and related) requests.
10870 @Defreq {while, expr anything}
10871 Evaluate the expression @var{expr}, and repeatedly execute
10872 @var{anything} (the remainder of the line) until @var{expr} evaluates
10873 to@tie{}0.
10875 @Example
10876 .nr a 0 1
10877 .while (\na < 9) \@{\
10878 \n+a,
10879 .\@}
10880 \n+a
10881     @result{} 1, 2, 3, 4, 5, 6, 7, 8, 9, 10
10882 @endExample
10884 Some remarks.
10886 @cindex @code{de} request, and @code{while}
10887 @itemize @bullet
10888 @item
10889 The body of a @code{while} request is treated like the body of a
10890 @code{de} request: @code{gtroff} temporarily stores it in a macro which
10891 is deleted after the loop has been exited.  It can considerably slow
10892 down a macro if the body of the @code{while} request (within the macro)
10893 is large.  Each time the macro is executed, the @code{while} body is
10894 parsed and stored again as a temporary macro.
10896 @Example
10897 .de xxx
10898 .  nr num 10
10899 .  while (\\n[num] > 0) \@{\
10900 .    \" many lines of code
10901 .    nr num -1
10902 .  \@}
10904 @endExample
10906 @cindex recursive macros
10907 @cindex macros, recursive
10908 @noindent
10909 The traditional and ofter better solution (@acronym{UNIX} @code{troff}
10910 doesn't have the @code{while} request) is to use a recursive macro
10911 instead which is parsed only once during its definition.
10913 @Example
10914 .de yyy
10915 .  if (\\n[num] > 0) \@{\
10916 .    \" many lines of code
10917 .    nr num -1
10918 .    yyy
10919 .  \@}
10922 .de xxx
10923 .  nr num 10
10924 .  yyy
10926 @endExample
10928 @noindent
10929 Note that the number of available recursion levels is set to@tie{}1000
10930 (this is a compile-time constant value of @code{gtroff}).
10932 @item
10933 The closing brace of a @code{while} body must end a line.
10935 @Example
10936 .if 1 \@{\
10937 .  nr a 0 1
10938 .  while (\n[a] < 10) \@{\
10939 .    nop \n+[a]
10940 .\@}\@}
10941     @result{} unbalanced \@{ \@}
10942 @endExample
10943 @end itemize
10944 @endDefreq
10946 @Defreq {break, }
10947 @cindex @code{while} request, confusing with @code{br}
10948 @cindex @code{break} request, in a @code{while} loop
10949 @cindex @code{continue} request, in a @code{while} loop
10950 Break out of a @code{while} loop.  Be sure not to confuse this with the
10951 @code{br} request (causing a line break).
10952 @endDefreq
10954 @Defreq {continue, }
10955 Finish the current iteration of a @code{while} loop, immediately
10956 restarting the next iteration.
10957 @endDefreq
10959 @xref{Expressions}.
10962 @c =====================================================================
10964 @node Writing Macros, Page Motions, Conditionals and Loops, gtroff Reference
10965 @section Writing Macros
10966 @cindex writing macros
10967 @cindex macros, writing
10969 A @dfn{macro} is a collection of text and embedded commands which can be
10970 invoked multiple times.  Use macros to define common operations.
10971 @xref{Strings}, for a (limited) alternative syntax to call macros.
10973 @DefreqList {de, name [@Var{end}]}
10974 @DefreqItem {de1, name [@Var{end}]}
10975 @DefreqItem {dei, name [@Var{end}]}
10976 @DefreqListEnd {dei1, name [@Var{end}]}
10977 Define a new macro named @var{name}.  @code{gtroff} copies subsequent
10978 lines (starting with the next one) into an internal buffer until it
10979 encounters the line @samp{..} (two dots).  The optional second argument
10980 to @code{de} changes this to a macro to @samp{.@var{end}}.
10982 There can be whitespace after the first dot in the line containing the
10983 ending token (either @samp{.} or macro @samp{@var{end}}).  Don't insert
10984 a tab character immediately after the @samp{..}, otherwise it isn't
10985 recognized as the end-of-macro symbol.@footnote{While it is possible to
10986 define and call a macro @samp{.} with
10988 @Example
10989 .de .
10990 .  tm foo
10993 ..    \" This calls macro `.'!
10994 @endExample
10996 @noindent
10997 you can't use this as the end-of-macro macro: during a macro definition,
10998 @samp{..} is never handled as a call to @samp{.}, even if you say
10999 @samp{.de foo .} explicitly.}
11001 Here a small example macro called @samp{P} which causes a break and
11002 inserts some vertical space.  It could be used to separate paragraphs.
11004 @Example
11005 .de P
11006 .  br
11007 .  sp .8v
11009 @endExample
11011 The following example defines a macro within another.  Remember that
11012 expansion must be protected twice; once for reading the macro and once
11013 for executing.
11015 @Example
11016 \# a dummy macro to avoid a warning
11017 .de end
11020 .de foo
11021 .  de bar end
11022 .    nop \f[B]Hallo \\\\$1!\f[]
11023 .  end
11026 .foo
11027 .bar Joe
11028     @result{} @b{Hallo Joe!}
11029 @endExample
11031 @noindent
11032 Since @code{\f} has no expansion, it isn't necessary to protect its
11033 backslash.  Had we defined another macro within @code{bar} which takes a
11034 parameter, eight backslashes would be necessary before @samp{$1}.
11036 The @code{de1} request turns off compatibility mode while executing the
11037 macro.  On entry, the current compatibility mode is saved and restored
11038 at exit.
11040 @Example
11041 .nr xxx 12345
11043 .de aa
11044 The value of xxx is \\n[xxx].
11046 .de1 bb
11047 The value of xxx ix \\n[xxx].
11050 .cp 1
11053     @result{} warning: number register `[' not defined
11054     @result{} The value of xxx is 0xxx].
11056     @result{} The value of xxx ix 12345.
11057 @endExample
11059 The @code{dei} request defines a macro indirectly.  That is, it expands
11060 strings whose names are @var{name} or @var{end} before performing the
11061 append.
11063 This:
11065 @Example
11066 .ds xx aa
11067 .ds yy bb
11068 .dei xx yy
11069 @endExample
11071 @noindent
11072 is equivalent to:
11074 @Example
11075 .de aa bb
11076 @endExample
11078 The @code{dei1} request is similar to @code{dei} but with compatibility
11079 mode switched off during execution of the defined macro.
11081 If compatibility mode is on, @code{de} (and @code{dei}) behave similar
11082 to @code{de1} (and @code{dei1}): A `compatibility save' token is
11083 inserted at the beginning, and a `compatibility restore' token at the
11084 end, with compatibility mode switched on during execution.  @xref{Gtroff
11085 Internals}, for more information on switching compatibility mode on and
11086 off in a single document.
11088 @pindex trace.tmac
11089 Using @file{trace.tmac}, you can trace calls to @code{de} and
11090 @code{de1}.
11092 Note that macro identifiers are shared with identifiers for strings and
11093 diversions.
11094 @endDefreq
11096 @DefreqList {am, name [@Var{end}]}
11097 @DefreqItem {am1, name [@Var{end}]}
11098 @DefreqItem {ami, name [@Var{end}]}
11099 @DefreqListEnd {ami1, name [@Var{end}]}
11100 @cindex appending to a macro (@code{am})
11101 @cindex macro, appending (@code{am})
11102 Works similarly to @code{de} except it appends onto the macro named
11103 @var{name}.  So, to make the previously defined @samp{P} macro actually
11104 do indented instead of block paragraphs, add the necessary code to the
11105 existing macro like this:
11107 @Example
11108 .am P
11109 .ti +5n
11111 @endExample
11113 The @code{am1} request turns off compatibility mode while executing the
11114 appended macro piece.  To be more precise, a @dfn{compatibility save}
11115 input token is inserted at the beginning of the appended code, and a
11116 @dfn{compatibility restore} input token at the end.
11118 The @code{ami} request appends indirectly, meaning that @code{gtroff}
11119 expands strings whose names are @var{name} or @var{end} before
11120 performing the append.
11122 The @code{ami1} request is similar to @code{ami} but compatibility mode
11123 is switched off during execution of the defined macro.
11125 @pindex trace.tmac
11126 Using @file{trace.tmac}, you can trace calls to @code{am} and
11127 @code{am1}.
11128 @endDefreq
11130 @xref{Strings}, for the @code{als} request to rename a macro.
11132 The @code{de}, @code{am}, @code{di}, @code{da}, @code{ds}, and @code{as}
11133 requests (together with its variants) only create a new object if the
11134 name of the macro, diversion or string diversion is currently undefined
11135 or if it is defined to be a request; normally they modify the value of
11136 an existing object.
11138 @Defreq {return, [@Var{anything}]}
11139 Exit a macro, immediately returning to the caller.
11141 If called with an argument, exit twice, namely the current macro and the
11142 macro one level higher.  This is used to define a wrapper macro for
11143 @code{return} in @file{trace.tmac}.
11144 @endDefreq
11146 @menu
11147 * Copy-in Mode::
11148 * Parameters::
11149 @end menu
11151 @c ---------------------------------------------------------------------
11153 @node Copy-in Mode, Parameters, Writing Macros, Writing Macros
11154 @subsection Copy-in Mode
11155 @cindex copy mode
11156 @cindex copy-in mode
11157 @cindex mode, copy
11158 @cindex mode, copy-in
11160 @cindex @code{\n}, when reading text for a macro
11161 @cindex @code{\$}, when reading text for a macro
11162 @cindex @code{\*}, when reading text for a macro
11163 @cindex @code{\\}, when reading text for a macro
11164 @cindex \@key{RET}, when reading text for a macro
11165 When @code{gtroff} reads in the text for a macro, string, or diversion,
11166 it copies the text (including request lines, but excluding escapes) into
11167 an internal buffer.  Escapes are converted into an internal form, except
11168 for @code{\n}, @code{\$}, @code{\*}, @code{\\} and @code{\@key{RET}}
11169 which are evaluated and inserted into the text where the escape was
11170 located.  This is known as @dfn{copy-in} mode or @dfn{copy} mode.
11172 What this means is that you can specify when these escapes are to be
11173 evaluated (either at copy-in time or at the time of use) by insulating
11174 the escapes with an extra backslash.  Compare this to the @code{\def}
11175 and @code{\edef} commands in @TeX{}.
11177 The following example prints the numbers 20 and@tie{}10:
11179 @Example
11180 .nr x 20
11181 .de y
11182 .nr x 10
11183 \&\nx
11184 \&\\nx
11187 @endExample
11189 @c ---------------------------------------------------------------------
11191 @node Parameters,  , Copy-in Mode, Writing Macros
11192 @subsection Parameters
11193 @cindex parameters
11195 The arguments to a macro or string can be examined using a variety of
11196 escapes.
11198 @Defreg {.$}
11199 @cindex number of arguments register (@code{.$})
11200 The number of arguments passed to a macro or string.  This is a
11201 read-only number register.
11203 Note that the @code{shift} request can change its value.
11204 @endDefreg
11206 Any individual argument can be retrieved with one of the following
11207 escapes:
11209 @DefescList {\\$, , n, }
11210 @DefescItem {\\$, @Lparen{}, nn, }
11211 @DefescListEnd {\\$, @Lbrack{}, nnn, @Rbrack{}}
11212 @cindex copy-in mode, and macro arguments
11213 @cindex mode, copy-in, and macro arguments
11214 @cindex macro, arguments (@code{\$})
11215 @cindex arguments, macro (@code{\$})
11216 Retrieve the @var{n}@dmn{th}, @var{nn}@dmn{th} or @var{nnn}@dmn{th}
11217 argument.  As usual, the first form only accepts a single number (larger
11218 than zero), the second a two-digit number (larger or equal to@tie{}10),
11219 and the third any positive integer value (larger than zero).  Macros and
11220 strings can have an unlimited number of arguments.  Note that due to
11221 copy-in mode, use two backslashes on these in actual use to prevent
11222 interpolation until the macro is actually invoked.
11223 @endDefesc
11225 @Defreq {shift, [@Var{n}]}
11226 Shift the arguments 1@tie{}position, or as many positions as specified
11227 by its argument.  After executing this request, argument@tie{}@var{i}
11228 becomes argument @math{@var{i}-@var{n}}; arguments 1 to@tie{}@var{n} are
11229 no longer available.  Shifting by negative amounts is currently
11230 undefined.
11232 The register @code{.$} is adjusted accordingly.
11233 @endDefreq
11235 @DefescList {\\$*, , , }
11236 @DefescListEnd {\\$@@, , , }
11237 In some cases it is convenient to use all of the arguments at once (for
11238 example, to pass the arguments along to another macro).  The @code{\$*}
11239 escape concatenates all the arguments separated by spaces.  A similar
11240 escape is @code{\$@@}, which concatenates all the arguments with each
11241 surrounded by double quotes, and separated by spaces.  If not in
11242 compatibility mode, the input level of double quotes is preserved (see
11243 @ref{Request and Macro Arguments}).
11244 @endDefesc
11246 @Defesc {\\$^, , , }
11247 Handle the parameters of a macro as if they were an argument to the
11248 @code{ds} or similar requests.
11250 @Example
11251 .de foo
11252 .  tm $1=`\\$1'
11253 .  tm $2=`\\$2'
11254 .  tm $*=`\\$*'
11255 .  tm $@@=`\\$@@'
11256 .  tm $^=`\\$^'
11258 .foo " This is a "test"
11259     @result{} $1=` This is a '
11260     @result{} $2=`test"'
11261     @result{} $*=` This is a  test"'
11262     @result{} $@@=`" This is a " "test""'
11263     @result{} $^=`" This is a "test"'
11264 @endExample
11266 This escape is useful mainly for macro packages like @file{trace.tmac}
11267 which redefines some requests and macros for debugging purposes.
11268 @endDefesc
11270 @Defesc {\\$0, , , }
11271 @cindex macro name register (@code{\$0})
11272 @cindex @code{als} request, and @code{\$0}
11273 The name used to invoke the current macro.  The @code{als} request can
11274 make a macro have more than one name.
11276 If a macro is called as a string (within another macro), the value of
11277 @code{\$0} isn't changed.
11279 @Example
11280 .de foo
11281 .  tm \\$0
11283 .als foo bar
11285 @endExample
11286 @Example
11287 .de aaa
11288 .  foo
11290 .de bbb
11291 .  bar
11293 .de ccc
11294 \\*[foo]\\
11296 .de ddd
11297 \\*[bar]\\
11300 @endExample
11301 @Example
11302 .aaa
11303     @result{} foo
11304 .bbb
11305     @result{} bar
11306 .ccc
11307     @result{} ccc
11308 .ddd
11309     @result{} ddd
11310 @endExample
11311 @endDefesc
11313 @xref{Request and Macro Arguments}.
11316 @c =====================================================================
11318 @node Page Motions, Drawing Requests, Writing Macros, gtroff Reference
11319 @section Page Motions
11320 @cindex page motions
11321 @cindex motions, page
11323 @xref{Manipulating Spacing}, for a discussion of the main request for
11324 vertical motion, @code{sp}.
11326 @DefreqList {mk, [@Var{reg}]}
11327 @DefreqListEnd {rt, [@Var{dist}]}
11328 @cindex marking vertical page location (@code{mk})
11329 @cindex page location, vertical, marking (@code{mk})
11330 @cindex location, vertical, page, marking (@code{mk})
11331 @cindex vertical page location, marking (@code{mk})
11332 @cindex returning to marked vertical page location (@code{rt})
11333 @cindex page location, vertical, returning to marked (@code{rt})
11334 @cindex location, vertical, page, returning to marked (@code{rt})
11335 @cindex vertical page location, returning to marked (@code{rt})
11336 The request @code{mk} can be used to mark a location on a page, for
11337 movement to later.  This request takes a register name as an argument in
11338 which to store the current page location.  With no argument it stores
11339 the location in an internal register.  The results of this can be used
11340 later by the @code{rt} or the @code{sp} request (or the @code{\v}
11341 escape).
11343 The @code{rt} request returns @emph{upwards} to the location marked with
11344 the last @code{mk} request.  If used with an argument, return to a
11345 position which distance from the top of the page is @var{dist} (no
11346 previous call to @code{mk} is necessary in this case).  Default scaling
11347 indicator is @samp{v}.
11349 Here a primitive solution for a two-column macro.
11351 @Example
11352 .nr column-length 1.5i
11353 .nr column-gap 4m
11354 .nr bottom-margin 1m
11356 @endExample
11357 @Example
11358 .de 2c
11359 .  br
11360 .  mk
11361 .  ll \\n[column-length]u
11362 .  wh -\\n[bottom-margin]u 2c-trap
11363 .  nr right-side 0
11366 @endExample
11367 @Example
11368 .de 2c-trap
11369 .  ie \\n[right-side] \@{\
11370 .    nr right-side 0
11371 .    po -(\\n[column-length]u + \\n[column-gap]u)
11372 .    \" remove trap
11373 .    wh -\\n[bottom-margin]u
11374 .  \@}
11375 .  el \@{\
11376 .    \" switch to right side
11377 .    nr right-side 1
11378 .    po +(\\n[column-length]u + \\n[column-gap]u)
11379 .    rt
11380 .  \@}
11383 @endExample
11384 @Example
11385 .pl 1.5i
11386 .ll 4i
11387 This is a small test which shows how the
11388 rt request works in combination with mk.
11391 Starting here, text is typeset in two columns.
11392 Note that this implementation isn't robust
11393 and thus not suited for a real two-column
11394 macro.
11395 @endExample
11397 Result:
11399 @Example
11400 This is a small test which shows how the
11401 rt request works in combination with mk.
11403 Starting  here,    isn't    robust
11404 text is typeset    and   thus  not
11405 in two columns.    suited  for   a
11406 Note that  this    real two-column
11407 implementation     macro.
11408 @endExample
11409 @endDefreq
11411 The following escapes give fine control of movements about the page.
11413 @Defesc {\\v, ', e, '}
11414 @cindex vertical motion (@code{\v})
11415 @cindex motion, vertical (@code{\v})
11416 Move vertically, usually from the current location on the page (if no
11417 absolute position operator @samp{|} is used).  The argument@tie{}@var{e}
11418 specifies the distance to move; positive is downwards and negative
11419 upwards.  The default scaling indicator for this escape is @samp{v}.
11420 Beware, however, that @code{gtroff} continues text processing at the
11421 point where the motion ends, so you should always balance motions to
11422 avoid interference with text processing.
11424 @code{\v} doesn't trigger a trap.  This can be quite useful; for
11425 example, consider a page bottom trap macro which prints a marker in the
11426 margin to indicate continuation of a footnote or something similar.
11427 @endDefesc
11429 There are some special-case escapes for vertical motion.
11431 @Defesc {\\r, , , }
11432 Move upwards@tie{}1@dmn{v}.
11433 @endDefesc
11435 @Defesc {\\u, , , }
11436 Move upwards@tie{}.5@dmn{v}.
11437 @endDefesc
11439 @Defesc {\\d, , , }
11440 Move down@tie{}.5@dmn{v}.
11441 @endDefesc
11443 @Defesc {\\h, ', e, '}
11444 @cindex inserting horizontal space (@code{\h})
11445 @cindex horizontal space (@code{\h})
11446 @cindex space, horizontal (@code{\h})
11447 @cindex horizontal motion (@code{\h})
11448 @cindex motion, horizontal (@code{\h})
11449 Move horizontally, usually from the current location (if no absolute
11450 position operator @samp{|} is used).  The expression@tie{}@var{e}
11451 indicates how far to move: positive is rightwards and negative
11452 leftwards.  The default scaling indicator for this escape is @samp{m}.
11454 This horizontal space is not discarded at the end of a line.  To insert
11455 discardable space of a certain length use the @code{ss} request.
11456 @endDefesc
11458 There are a number of special-case escapes for horizontal motion.
11460 @Defesc {\\@key{SP}, , , }
11461 @cindex space, unbreakable
11462 @cindex unbreakable space
11463 An unbreakable and unpaddable (i.e.@: not expanded during filling)
11464 space.  (Note: This is a backslash followed by a space.)
11465 @endDefesc
11467 @Defesc {\\~, , , }
11468 An unbreakable space that stretches like a normal inter-word space when
11469 a line is adjusted.
11470 @endDefesc
11472 @Defesc {\\|, , , }
11473 A 1/6@dmn{th} em space.  Ignored for TTY output devices (rounded to
11474 zero).
11476 However, if there is a glyph defined in the current font file with name
11477 @code{\|} (note the leading backslash), the width of this glyph is used
11478 instead (even for TTYs).
11479 @endDefesc
11481 @Defesc {\\^, , , }
11482 A 1/12@dmn{th} em space.  Ignored for TTY output devices (rounded to
11483 zero).
11485 However, if there is a glyph defined in the current font file with name
11486 @code{\^} (note the leading backslash), the width of this glyph is used
11487 instead (even for TTYs).
11488 @endDefesc
11490 @Defesc {\\0, , , }
11491 @cindex space, width of a digit (@code{\0})
11492 @cindex digit width space (@code{\0})
11493 A space the size of a digit.
11494 @endDefesc
11496 The following string sets the @TeX{} logo:
11498 @Example
11499 .ds TeX T\h'-.1667m'\v'.224m'E\v'-.224m'\h'-.125m'X
11500 @endExample
11502 @DefescList {\\w, ', text, '}
11503 @DefregItem {st}
11504 @DefregItem {sb}
11505 @DefregItem {rst}
11506 @DefregItem {rsb}
11507 @DefregItem {ct}
11508 @DefregItem {ssc}
11509 @DefregListEnd {skw}
11510 @cindex width escape (@code{\w})
11511 Return the width of the specified @var{text} in basic units.  This
11512 allows horizontal movement based on the width of some arbitrary text
11513 (e.g.@: given as an argument to a macro).
11515 @Example
11516 The length of the string `abc' is \w'abc'u.
11517     @result{} The length of the string `abc' is 72u.
11518 @endExample
11520 Font changes may occur in @var{text} which don't affect current
11521 settings.
11523 After use, @code{\w} sets several registers:
11525 @table @code
11526 @item st
11527 @itemx sb
11528 The highest and lowest point of the baseline, respectively, in
11529 @var{text}.
11531 @item rst
11532 @itemx rsb
11533 Like the @code{st} and @code{sb} registers, but takes account of the
11534 heights and depths of glyphs.  With other words, this gives the highest
11535 and lowest point of @var{text}.  Values below the baseline are negative.
11537 @item ct
11538 Defines the kinds of glyphs occurring in @var{text}:
11540 @table @asis
11541 @item 0
11542 only short glyphs, no descenders or tall glyphs.
11544 @item 1
11545 at least one descender.
11547 @item 2
11548 at least one tall glyph.
11550 @item 3
11551 at least one each of a descender and a tall glyph.
11552 @end table
11554 @item ssc
11555 The amount of horizontal space (possibly negative) that should be added
11556 to the last glyph before a subscript.
11558 @item skw
11559 How far to right of the center of the last glyph in the @code{\w}
11560 argument, the center of an accent from a roman font should be placed
11561 over that glyph.
11562 @end table
11563 @endDefesc
11565 @DefescList {\\k, , p, }
11566 @DefescItem {\\k, @Lparen{}, ps, }
11567 @DefescListEnd {\\k, @Lbrack{}, position, @Rbrack{}}
11568 @cindex saving horizontal input line position (@code{\k})
11569 @cindex horizontal input line position, saving (@code{\k})
11570 @cindex input line position, horizontal, saving (@code{\k})
11571 @cindex position, horizontal input line, saving (@code{\k})
11572 @cindex line, input, horizontal position, saving (@code{\k})
11573 Store the current horizontal position in the @emph{input} line in number
11574 register with name @var{position} (one-character name@tie{}@var{p},
11575 two-character name @var{ps}).  Use this, for example, to return to the
11576 beginning of a string for highlighting or other decoration.
11577 @endDefesc
11579 @Defreg {hp}
11580 @cindex horizontal input line position register (@code{hp})
11581 @cindex input line, horizontal position, register (@code{hp})
11582 @cindex position, horizontal, in input line, register (@code{hp})
11583 @cindex line, input, horizontal position, register (@code{hp})
11584 The current horizontal position at the input line.
11585 @endDefreg
11587 @Defreg {.k}
11588 @cindex horizontal output line position register (@code{.k})
11589 @cindex output line, horizontal position, register (@code{.k})
11590 @cindex position, horizontal, in output line, register (@code{.k})
11591 @cindex line, output, horizontal position, register (@code{.k})
11592 A read-only number register containing the current horizontal output
11593 position (relative to the current indentation).
11594 @endDefreg
11596 @Defesc {\\o, ', abc, '}
11597 @cindex overstriking glyphs (@code{\o})
11598 @cindex glyphs, overstriking (@code{\o})
11599 Overstrike glyphs @var{a}, @var{b}, @var{c}, @dots{}; the glyphs are
11600 centered, and the resulting spacing is the largest width of the affected
11601 glyphs.
11602 @endDefesc
11604 @Defesc {\\z, , g, , }
11605 @cindex zero-width printing (@code{\z}, @code{\Z})
11606 @cindex printing, zero-width (@code{\z}, @code{\Z})
11607 Print glyph @var{g} with zero width, i.e., without spacing.  Use this to
11608 overstrike glyphs left-aligned.
11609 @endDefesc
11611 @Defesc {\\Z, ', anything, '}
11612 @cindex zero-width printing (@code{\z}, @code{\Z})
11613 @cindex printing, zero-width (@code{\z}, @code{\Z})
11614 Print @var{anything}, then restore the horizontal and vertical position.
11615 The argument may not contain tabs or leaders.
11617 The following is an example of a strike-through macro:
11619 @Example
11620 .de ST
11621 .nr ww \w'\\$1'
11622 \Z@@\v'-.25m'\l'\\n[ww]u'@@\\$1
11625 This is
11626 .ST "a test"
11627 an actual emergency!
11628 @endExample
11629 @endDefesc
11632 @c =====================================================================
11634 @node Drawing Requests, Traps, Page Motions, gtroff Reference
11635 @section Drawing Requests
11636 @cindex drawing requests
11637 @cindex requests for drawing
11639 @code{gtroff} provides a number of ways to draw lines and other figures
11640 on the page.  Used in combination with the page motion commands (see
11641 @ref{Page Motions}, for more info), a wide variety of figures can be
11642 drawn.  However, for complex drawings these operations can be quite
11643 cumbersome, and it may be wise to use graphic preprocessors like
11644 @code{gpic} or @code{ggrn}.  @xref{gpic}, and @ref{ggrn}, for more
11645 information.
11647 All drawing is done via escapes.
11649 @DefescList {\\l, ', l, '}
11650 @DefescListEnd {\\l, ', lg, '}
11651 @cindex drawing horizontal lines (@code{\l})
11652 @cindex horizontal line, drawing (@code{\l})
11653 @cindex line, horizontal, drawing (@code{\l})
11654 Draw a line horizontally.  @var{l} is the length of the line to be
11655 drawn.  If it is positive, start the line at the current location and
11656 draw to the right; its end point is the new current location.  Negative
11657 values are handled differently: The line starts at the current location
11658 and draws to the left, but the current location doesn't move.
11660 @var{l} can also be specified absolutely (i.e.@: with a leading
11661 @samp{|}) which draws back to the beginning of the input line.  Default
11662 scaling indicator is @samp{m}.
11664 @cindex underscore glyph (@code{\[ru]})
11665 @cindex glyph, underscore (@code{\[ru]})
11666 @cindex line drawing glyph
11667 @cindex glyph, for line drawing
11668 The optional second parameter@tie{}@var{g} is a glyph to draw the line
11669 with.  If this second argument is not specified, @code{gtroff} uses the
11670 underscore glyph, @code{\[ru]}.
11672 @cindex zero width space character (@code{\&})
11673 @cindex character, zero width space (@code{\&})
11674 @cindex space character, zero width (@code{\&})
11675 To separate the two arguments (to prevent @code{gtroff} from
11676 interpreting a drawing glyph as a scaling indicator if the glyph is
11677 represented by a single character) use @code{\&}.
11679 Here a small useful example:
11681 @Example
11682 .de box
11683 \[br]\\$*\[br]\l'|0\[rn]'\l'|0\[ul]'
11685 @endExample
11687 @noindent
11688 Note that this works by outputting a box rule (a vertical line), then
11689 the text given as an argument and then another box rule.  Finally, the
11690 line drawing escapes both draw from the current location to the
11691 beginning of the @emph{input} line -- this works because the line length
11692 is negative, not moving the current point.
11693 @endDefesc
11695 @DefescList {\\L, ', l, '}
11696 @DefescListEnd {\\L, ', lg, '}
11697 @cindex drawing vertical lines (@code{\L})
11698 @cindex vertical line drawing (@code{\L})
11699 @cindex line, vertical, drawing (@code{\L})
11700 @cindex line drawing glyph
11701 @cindex glyph for line drawing
11702 @cindex box rule glyph (@code{\[br]})
11703 @cindex glyph, box rule (@code{\[br]})
11704 Draw vertical lines.  Its parameters are similar to the @code{\l}
11705 escape, except that the default scaling indicator is @samp{v}.  The
11706 movement is downwards for positive values, and upwards for negative
11707 values.  The default glyph is the box rule glyph, @code{\[br]}.  As with
11708 the vertical motion escapes, text processing blindly continues where the
11709 line ends.
11711 @Example
11712 This is a \L'3v'test.
11713 @endExample
11715 @noindent
11716 Here the result, produced with @code{grotty}.
11718 @Example
11719 This is a
11720           |
11721           |
11722           |test.
11723 @endExample
11724 @endDefesc
11726 @Defesc {\\D, ', command arg @dots{}, '}
11727 The @code{\D} escape provides a variety of drawing functions.  Note that
11728 on character devices, only vertical and horizontal lines are supported
11729 within @code{grotty}; other devices may only support a subset of the
11730 available drawing functions.
11732 The default scaling indicator for all subcommands of @code{\D} is
11733 @samp{m} for horizontal distances and @samp{v} for vertical ones.
11734 Exceptions are @w{@code{\D'f @dots{}'}} and @w{@code{\D't @dots{}'}}
11735 which use @code{u} as the default, and @w{@code{\D'F@var{x} @dots{}'}}
11736 which arguments are treated similar to the @code{defcolor} request.
11738 @table @code
11739 @item \D'l @var{dx} @var{dy}'
11740 @cindex line, drawing (@w{@code{\D'l @dots{}'}})
11741 @cindex drawing a line (@w{@code{\D'l @dots{}'}})
11742 Draw a line from the current location to the relative point specified by
11743 (@var{dx},@var{dy}), where positive values mean down and right,
11744 respectively.  The end point of the line is the new current location.
11746 The following example is a macro for creating a box around a text
11747 string; for simplicity, the box margin is taken as a fixed value,
11748 0.2@dmn{m}.
11750 @Example
11751 .de BOX
11752 .  nr @@wd \w'\\$1'
11753 \h'.2m'\
11754 \h'-.2m'\v'(.2m - \\n[rsb]u)'\
11755 \D'l 0 -(\\n[rst]u - \\n[rsb]u + .4m)'\
11756 \D'l (\\n[@@wd]u + .4m) 0'\
11757 \D'l 0 (\\n[rst]u - \\n[rsb]u + .4m)'\
11758 \D'l -(\\n[@@wd]u + .4m) 0'\
11759 \h'.2m'\v'-(.2m - \\n[rsb]u)'\
11760 \\$1\
11761 \h'.2m'
11763 @endExample
11765 @noindent
11766 First, the width of the string is stored in register @code{@@wd}.  Then,
11767 four lines are drawn to form a box, properly offset by the box margin.
11768 The registers @code{rst} and @code{rsb} are set by the @code{\w} escape,
11769 containing the largest height and depth of the whole string.
11771 @item \D'c @var{d}'
11772 @cindex circle, drawing (@w{@code{\D'c @dots{}'}})
11773 @cindex drawing a circle (@w{@code{\D'c @dots{}'}})
11774 Draw a circle with a diameter of@tie{}@var{d} with the leftmost point at
11775 the current position.  After drawing, the current location is positioned
11776 at the rightmost point of the circle.
11778 @item \D'C @var{d}'
11779 @cindex circle, solid, drawing (@w{@code{\D'C @dots{}'}})
11780 @cindex drawing a solid circle (@w{@code{\D'C @dots{}'}})
11781 @cindex solid circle, drawing (@w{@code{\D'C @dots{}'}})
11782 Draw a solid circle with the same parameters and behaviour as an
11783 outlined circle.  No outline is drawn.
11785 @item \D'e @var{x} @var{y}'
11786 @cindex drawing an ellipse (@w{@code{\D'e @dots{}'}})
11787 @cindex ellipse, drawing (@w{@code{\D'e @dots{}'}})
11788 Draw an ellipse with a horizontal diameter of @var{x} and a vertical
11789 diameter of @var{y} with the leftmost point at the current position.
11790 After drawing, the current location is positioned at the rightmost point
11791 of the ellipse.
11793 @item \D'E @var{x} @var{y}'
11794 @cindex ellipse, solid, drawing (@w{@code{\D'E @dots{}'}})
11795 @cindex drawing a solid ellipse (@w{@code{\D'E @dots{}'}})
11796 @cindex solid ellipse, drawing (@w{@code{\D'E @dots{}'}})
11797 Draw a solid ellipse with the same parameters and behaviour as an
11798 outlined ellipse.  No outline is drawn.
11800 @item \D'a @var{dx1} @var{dy1} @var{dx2} @var{dy2}'
11801 @cindex arc, drawing (@w{@code{\D'a @dots{}'}})
11802 @cindex drawing an arc (@w{@code{\D'a @dots{}'}})
11803 Draw an arc clockwise from the current location through the two
11804 specified relative locations (@var{dx1},@var{dy1}) and
11805 (@var{dx2},@var{dy2}).  The coordinates of the first point are relative
11806 to the current position, and the coordinates of the second point are
11807 relative to the first point.  After drawing, the current position is
11808 moved to the final point of the arc.
11810 @item \D'~ @var{dx1} @var{dy1} @var{dx2} @var{dy2} @dots{}'
11811 @cindex drawing a spline (@w{@code{\D'~ @dots{}'}})
11812 @cindex spline, drawing (@w{@code{\D'~ @dots{}'}})
11813 Draw a spline from the current location to the relative point
11814 (@var{dx1},@var{dy1}) and then to (@var{dx2},@var{dy2}), and so on.  The
11815 current position is moved to the terminal point of the drawn curve.
11817 @item \D'f @var{n}'
11818 @cindex gray shading (@w{@code{\D'f @dots{}'}})
11819 @cindex shading filled objects (@w{@code{\D'f @dots{}'}})
11820 Set the shade of gray to be used for filling solid objects
11821 to@tie{}@var{n}; @var{n}@tie{}must be an integer between 0
11822 and@tie{}1000, where 0 corresponds solid white and 1000 to solid black,
11823 and values in between correspond to intermediate shades of gray.  This
11824 applies only to solid circles, solid ellipses, and solid polygons.  By
11825 default, a level of 1000 is used.
11827 Despite of being silly, the current point is moved horizontally to the
11828 right by@tie{}@var{n}.
11830 @cindex @w{@code{\D'f @dots{}'}} and horizontal resolution
11831 Don't use this command!  It has the serious drawback that it is always
11832 rounded to the next integer multiple of the horizontal resolution (the
11833 value of the @code{hor} keyword in the @file{DESC} file).  Use @code{\M}
11834 (@pxref{Colors}) or @w{@code{\D'Fg @dots{}'}} instead.
11836 @item \D'p @var{dx1} @var{dy1} @var{dx2} @var{dy2} @dots{}'
11837 @cindex drawing a polygon (@w{@code{\D'p @dots{}'}})
11838 @cindex polygon, drawing (@w{@code{\D'p @dots{}'}})
11839 Draw a polygon from the current location to the relative position
11840 (@var{dx1},@var{dy1}) and then to (@var{dx2},@var{dy2}) and so on.  When
11841 the specified data points are exhausted, a line is drawn back to the
11842 starting point.  The current position is changed by adding the sum of
11843 all arguments with odd index to the actual horizontal position and the
11844 even ones to the vertical position.
11846 @item \D'P @var{dx1} @var{dy1} @var{dx2} @var{dy2} @dots{}'
11847 @cindex polygon, solid, drawing (@w{@code{\D'P @dots{}'}})
11848 @cindex drawing a solid polygon (@w{@code{\D'P @dots{}'}})
11849 @cindex solid polygon, drawing (@w{@code{\D'P @dots{}'}})
11850 Draw a solid polygon with the same parameters and behaviour as an
11851 outlined polygon.  No outline is drawn.
11853 Here a better variant of the box macro to fill the box with some color.
11854 Note that the box must be drawn before the text since colors in
11855 @code{gtroff} are not transparent; the filled polygon would hide the
11856 text completely.
11858 @Example
11859 .de BOX
11860 .  nr @@wd \w'\\$1'
11861 \h'.2m'\
11862 \h'-.2m'\v'(.2m - \\n[rsb]u)'\
11863 \M[lightcyan]\
11864 \D'P 0 -(\\n[rst]u - \\n[rsb]u + .4m) \
11865      (\\n[@@wd]u + .4m) 0 \
11866      0 (\\n[rst]u - \\n[rsb]u + .4m) \
11867      -(\\n[@@wd]u + .4m) 0'\
11868 \h'.2m'\v'-(.2m - \\n[rsb]u)'\
11869 \M[]\
11870 \\$1\
11871 \h'.2m'
11873 @endExample
11875 If you want a filled polygon which has exactly the same size as an
11876 unfilled one, you must draw both an unfilled and a filled polygon.  A
11877 filled polygon is always smaller than an unfilled one because the latter
11878 uses straight lines with a given line thickness to connect the polygon's
11879 corners, while the former simply fills the area defined by the
11880 coordinates.
11882 @Example
11883 \h'1i'\v'1i'\
11884 \# increase line thickness
11885 \Z'\D't 5p''\
11886 \# draw unfilled polygon
11887 \Z'\D'p 3 3 -6 0''\
11888 \# draw filled polygon
11889 \Z'\D'P 3 3 -6 0''
11890 @endExample
11892 @item \D't @var{n}'
11893 @cindex line thickness (@w{@code{\D't @dots{}'}})
11894 @cindex thickness of lines (@w{@code{\D't @dots{}'}})
11895 Set the current line thickness to @var{n}@tie{}machine units.  A value
11896 of zero selects the smallest available line thickness.  A negative value
11897 makes the line thickness proportional to the current point size (this is
11898 the default behaviour of @acronym{AT&T} @code{troff}).
11900 Despite of being silly, the current point is moved horizontally to the
11901 right by@tie{}@var{n}.
11903 @item \D'F@var{scheme} @var{color_components}'
11904 @cindex unnamed fill colors (@code{\D'F@dots{}'})
11905 @cindex fill colors, unnamed (@code{\D'F@dots{}'})
11906 @cindex colors, fill, unnamed (@code{\D'F@dots{}'})
11907 Change current fill color.  @var{scheme} is a single letter denoting the
11908 color scheme: @samp{r} (rgb), @samp{c} (cmy), @samp{k} (cmyk), @samp{g}
11909 (gray), or @samp{d} (default color).  The color components use exactly
11910 the same syntax as in the @code{defcolor} request (@pxref{Colors}); the
11911 command @code{\D'Fd'} doesn't take an argument.
11913 @emph{No} position changing!
11915 Examples:
11917 @Example
11918 @endExample
11919 \D'Fg .3'      \" same gray as \D'f 700'
11920 \D'Fr #0000ff' \" blue
11921 @end table
11922 @endDefesc
11924 @xref{Graphics Commands}.
11926 @Defesc {\\b, ', string, '}
11927 @cindex pile, glyph (@code{\b})
11928 @cindex glyph pile (@code{\b})
11929 @cindex stacking glyphs (@code{\b})
11930 @dfn{Pile} a sequence of glyphs vertically, and center it vertically on
11931 the current line.  Use it to build large brackets and braces.
11933 Here an example how to create a large opening brace:
11935 @Example
11936 \b'\[lt]\[bv]\[lk]\[bv]\[lb]'
11937 @endExample
11939 @cindex @code{\b}, limitations
11940 @cindex limitations of @code{\b} escape
11941 The first glyph is on the top, the last glyph in @var{string} is at the
11942 bottom.  Note that @code{gtroff} separates the glyphs vertically by
11943 1@dmn{m}, and the whole object is centered 0.5@dmn{m} above the current
11944 baseline; the largest glyph width is used as the width for the whole
11945 object.  This rather unflexible positioning algorithm doesn't work with
11946 @option{-Tdvi} since the bracket pieces vary in height for this device.
11947 Instead, use the @code{eqn} preprocessor.
11949 @xref{Manipulating Spacing}, how to adjust the vertical spacing with the
11950 @code{\x} escape.
11951 @endDefesc
11954 @c =====================================================================
11956 @node Traps, Diversions, Drawing Requests, gtroff Reference
11957 @section Traps
11958 @cindex traps
11960 @dfn{Traps} are locations, which, when reached, call a specified macro.
11961 These traps can occur at a given location on the page, at a given
11962 location in the current diversion, at a blank line, after a certain
11963 number of input lines, or at the end of input.
11965 @cindex planting a trap
11966 @cindex trap, planting
11967 Setting a trap is also called @dfn{planting}.
11968 @cindex trap, springing
11969 @cindex springing a trap
11970 It is also said that a trap is @dfn{sprung} if the associated macro is
11971 executed.
11973 @menu
11974 * Page Location Traps::
11975 * Diversion Traps::
11976 * Input Line Traps::
11977 * Blank Line Traps::
11978 * End-of-input Traps::
11979 @end menu
11981 @c ---------------------------------------------------------------------
11983 @node Page Location Traps, Diversion Traps, Traps, Traps
11984 @subsection Page Location Traps
11985 @cindex page location traps
11986 @cindex traps, page location
11988 @dfn{Page location traps} perform an action when @code{gtroff} reaches
11989 or passes a certain vertical location on the page.  Page location traps
11990 have a variety of purposes, including:
11992 @itemize
11993 @item
11994 setting headers and footers
11996 @item
11997 setting body text in multiple columns
11999 @item
12000 setting footnotes
12001 @end itemize
12003 @DefreqList {vpt, flag}
12004 @DefregListEnd {.vpt}
12005 @cindex enabling vertical position traps (@code{vpt})
12006 @cindex vertical position traps, enabling (@code{vpt})
12007 @cindex vertical position trap enable register (@code{.vpt})
12008 Enable vertical position traps if @var{flag} is non-zero, or disables
12009 them otherwise.  Vertical position traps are traps set by the @code{wh}
12010 or @code{dt} requests.  Traps set by the @code{it} request are not
12011 vertical position traps.  The parameter that controls whether vertical
12012 position traps are enabled is global.  Initially vertical position traps
12013 are enabled.  The current setting of this is available in the
12014 @code{.vpt} read-only number register.
12016 Note that a page can't be ejected if @code{vpt} is set to zero.
12017 @endDefreq
12019 @Defreq {wh, dist [@Var{macro}]}
12020 Set a page location trap.  Non-negative values for @var{dist} set the
12021 trap relative to the top of the page; negative values set the trap
12022 relative to the bottom of the page.  Default scaling indicator is
12023 @samp{v}; values of @var{dist} are always rounded to be multiples of the
12024 vertical resolution (as given in register @code{.V}).
12026 @var{macro} is the name of the macro to execute when the trap is sprung.
12027 If @var{macro} is missing, remove the first trap (if any) at @var{dist}.
12029 @cindex page headers
12030 @cindex page footers
12031 @cindex headers
12032 @cindex footers
12033 The following is a simple example of how many macro packages set headers
12034 and footers.
12036 @Example
12037 .de hd                \" Page header
12038 '  sp .5i
12039 .  tl 'Title''date'
12040 '  sp .3i
12043 .de fo                \" Page footer
12044 '  sp 1v
12045 .  tl ''%''
12046 '  bp
12049 .wh 0   hd            \" trap at top of the page
12050 .wh -1i fo            \" trap one inch from bottom
12051 @endExample
12053 A trap at or below the bottom of the page is ignored; it can be made
12054 active by either moving it up or increasing the page length so that the
12055 trap is on the page.
12057 Negative trap values always use the @emph{current} page length; they are
12058 not converted to an absolute vertical position:
12060 @Example
12061 .pl 5i
12062 .wh -1i xx
12063 .ptr
12064     @result{} xx      -240
12065 .pl 100i
12066 .ptr
12067     @result{} xx      -240
12068 @endExample
12070 It is possible to have more than one trap at the same location; to do
12071 so, the traps must be defined at different locations, then moved
12072 together with the @code{ch} request; otherwise the second trap would
12073 replace the first one.  Earlier defined traps hide later defined traps
12074 if moved to the same position (the many empty lines caused by the
12075 @code{bp} request are omitted in the following example):
12077 @Example
12078 .de a
12079 .  nop a
12081 .de b
12082 .  nop b
12084 .de c
12085 .  nop c
12088 .wh 1i a
12089 .wh 2i b
12090 .wh 3i c
12092     @result{} a b c
12093 @endExample
12094 @Example
12095 .ch b 1i
12096 .ch c 1i
12098     @result{} a
12099 @endExample
12100 @Example
12101 .ch a 0.5i
12103     @result{} a b
12104 @endExample
12105 @endDefreq
12107 @Defreg {.t}
12108 @cindex distance to next trap register (@code{.t})
12109 @cindex trap, distance, register (@code{.t})
12110 A read-only number register holding the distance to the next trap.
12112 If there are no traps between the current position and the bottom of the
12113 page, it contains the distance to the page bottom.  In a diversion, the
12114 distance to the page bottom is infinite (the returned value is the
12115 biggest integer which can be represented in @code{groff}) if there are
12116 no diversion traps.
12117 @endDefreg
12119 @Defreq {ch, macro [@Var{dist}]}
12120 @cindex changing trap location (@code{ch})
12121 @cindex trap, changing location (@code{ch})
12122 Change the location of a trap.  The first argument is the name of the
12123 macro to be invoked at the trap, and the second argument is the new
12124 location for the trap (note that the parameters are specified in
12125 opposite order as in the @code{wh} request).  This is useful for
12126 building up footnotes in a diversion to allow more space at the bottom
12127 of the page for them.
12129 Default scaling indicator for @var{dist} is @samp{v}.  If @var{dist} is
12130 missing, the trap is removed.
12132 @c XXX
12134 @ignore
12135 @Example
12136 ... (simplified) footnote example ...
12137 @endExample
12138 @end ignore
12139 @endDefreq
12141 @Defreg {.ne}
12142 The read-only number register @code{.ne} contains the amount of space
12143 that was needed in the last @code{ne} request that caused a trap to be
12144 sprung.  Useful in conjunction with the @code{.trunc} register.
12145 @xref{Page Control}, for more information.
12147 Since the @code{.ne} register is only set by traps it doesn't make much
12148 sense to use it outside of trap macros.
12149 @endDefreg
12151 @Defreg {.trunc}
12152 @cindex @code{ne} request, and the @code{.trunc} register
12153 @cindex truncated vertical space register (@code{.trunc})
12154 A read-only register containing the amount of vertical space truncated
12155 by the most recently sprung vertical position trap, or, if the trap was
12156 sprung by an @code{ne} request, minus the amount of vertical motion
12157 produced by the @code{ne} request.  In other words, at the point a trap
12158 is sprung, it represents the difference of what the vertical position
12159 would have been but for the trap, and what the vertical position
12160 actually is.
12162 Since the @code{.trunc} register is only set by traps it doesn't make
12163 much sense to use it outside of trap macros.
12164 @endDefreg
12166 @Defreg {.pe}
12167 @cindex @code{bp} request, and traps (@code{.pe})
12168 @cindex traps, sprung by @code{bp} request (@code{.pe})
12169 @cindex page ejecting register (@code{.pe})
12170 A read-only register which is set to@tie{}1 while a page is ejected with
12171 the @code{bp} request (or by the end of input).
12173 Outside of traps this register is always zero.  In the following
12174 example, only the second call to@tie{}@code{x} is caused by @code{bp}.
12176 @Example
12177 .de x
12178 \&.pe=\\n[.pe]
12181 .wh 1v x
12182 .wh 4v x
12183 A line.
12185 Another line.
12187     @result{} A line.
12188        .pe=0
12189        Another line.
12191        .pe=1
12192 @endExample
12193 @endDefreg
12195 @cindex diversions, and traps
12196 @cindex traps, and diversions
12197 An important fact to consider while designing macros is that diversions
12198 and traps do not interact normally.  For example, if a trap invokes a
12199 header macro (while outputting a diversion) which tries to change the
12200 font on the current page, the effect is not visible before the diversion
12201 has completely been printed (except for input protected with @code{\!}
12202 or @code{\?}) since the data in the diversion is already formatted.  In
12203 most cases, this is not the expected behaviour.
12205 @c ---------------------------------------------------------------------
12207 @node Diversion Traps, Input Line Traps, Page Location Traps, Traps
12208 @subsection Diversion Traps
12209 @cindex diversion traps
12210 @cindex traps, diversion
12212 @Defreq {dt, [@Var{dist} @Var{macro}]}
12213 @cindex @code{.t} register, and diversions
12214 @cindex setting diversion trap (@code{dt})
12215 @cindex diversion trap, setting (@code{dt})
12216 @cindex trap, diversion, setting (@code{dt})
12217 Set a trap @emph{within} a diversion.  @var{dist} is the location of the
12218 trap (identical to the @code{wh} request; default scaling indicator is
12219 @samp{v}) and @var{macro} is the name of the macro to be invoked.  If
12220 called without arguments, the diversion trap is removed.
12222 Note that there exists only a single diversion trap.
12224 The number register @code{.t} still works within diversions.
12225 @xref{Diversions}, for more information.
12226 @endDefreq
12228 @c ---------------------------------------------------------------------
12230 @node Input Line Traps, Blank Line Traps, Diversion Traps, Traps
12231 @subsection Input Line Traps
12232 @cindex input line traps
12233 @cindex traps, input line
12235 @DefreqList {it, n macro}
12236 @DefreqItem {itc, n macro}
12237 @cindex setting input line trap (@code{it})
12238 @cindex input line trap, setting (@code{it})
12239 @cindex trap, input line, setting (@code{it})
12240 Set an input line trap.  @var{n}@tie{}is the number of lines of input
12241 which may be read before springing the trap, @var{macro} is the macro to
12242 be invoked.  Request lines are not counted as input lines.
12244 For example, one possible use is to have a macro which prints the next
12245 @var{n}@tie{}lines in a bold font.
12247 @Example
12248 .de B
12249 .  it \\$1 B-end
12250 .  ft B
12253 .de B-end
12254 .  ft R
12256 @endExample
12258 @cindex input line traps and interrupted lines (@code{itc})
12259 @cindex interrupted lines and input line traps (@code{itc})
12260 @cindex traps, input line, and interrupted lines (@code{itc})
12261 @cindex lines, interrupted, and input line traps (@code{itc})
12262 The @code{itc} request is identical except that an interrupted text line
12263 (ending with @code{\c}) is not counted as a separate line.
12265 Both requests are associated with the current environment
12266 (@pxref{Environments}); switching to another environment disables the
12267 current input trap, and going back reactivates it, restoring the number
12268 of already processed lines.
12269 @endDefreq
12271 @c ---------------------------------------------------------------------
12273 @node Blank Line Traps, End-of-input Traps, Input Line Traps, Traps
12274 @subsection Blank Line Traps
12275 @cindex blank line traps
12276 @cindex traps, blank line
12278 @Defreq {blm, macro}
12279 @cindex blank line macro (@code{blm})
12280 Set a blank line trap.  @code{gtroff} executes @var{macro} when it
12281 encounters a blank line in the input file.
12282 @endDefreq
12284 @c ---------------------------------------------------------------------
12286 @node End-of-input Traps,  , Blank Line Traps, Traps
12287 @subsection End-of-input Traps
12288 @cindex end-of-input traps
12289 @cindex traps, end-of-input
12291 @Defreq {em, macro}
12292 @cindex setting end-of-input trap (@code{em})
12293 @cindex end-of-input trap, setting (@code{em})
12294 @cindex trap, end-of-input, setting (@code{em})
12295 @cindex end-of-input macro (@code{em})
12296 @cindex macro, end-of-input (@code{em})
12297 Set a trap at the end of input.  @var{macro} is executed after the last
12298 line of the input file has been processed.
12300 For example, if the document had to have a section at the bottom of the
12301 last page for someone to approve it, the @code{em} request could be
12302 used.
12304 @Example
12305 .de approval
12306 .  ne 5v
12307 .  sp |(\\n[.t] - 6v)
12308 .  in +4i
12309 .  lc _
12310 .  br
12311 Approved:\t\a
12312 .  sp
12313 Date:\t\t\a
12316 .em approval
12317 @endExample
12318 @endDefreq
12321 @c =====================================================================
12323 @node Diversions, Environments, Traps, gtroff Reference
12324 @section Diversions
12325 @cindex diversions
12327 In @code{gtroff} it is possible to @dfn{divert} text into a named
12328 storage area.  Due to the similarity to defining macros it is sometimes
12329 said to be stored in a macro.  This is used for saving text for output
12330 at a later time, which is useful for keeping blocks of text on the same
12331 page, footnotes, tables of contents, and indices.
12333 @cindex top-level diversion
12334 @cindex diversion, top-level
12335 For orthogonality it is said that @code{gtroff} is in the @dfn{top-level
12336 diversion} if no diversion is active (i.e., the data is diverted to the
12337 output device).
12339 @DefreqList {di, macro}
12340 @DefreqListEnd {da, macro}
12341 @cindex beginning diversion (@code{di})
12342 @cindex diversion, beginning (@code{di})
12343 @cindex ending diversion (@code{di})
12344 @cindex diversion, ending (@code{di})
12345 @cindex appending to a diversion (@code{da})
12346 @cindex diversion, appending (@code{da})
12347 Begin a diversion.  Like the @code{de} request, it takes an argument of
12348 a macro name to divert subsequent text into.  The @code{da} macro
12349 appends to an existing diversion.
12351 @code{di} or @code{da} without an argument ends the diversion.
12353 The current partially-filled line is included into the diversion.  See
12354 the @code{box} request below for an example.  Note that switching to
12355 another (empty) environment (with the @code{ev} request) avoids the
12356 inclusion of the current partially-filled line.
12357 @endDefreq
12359 @DefreqList {box, macro}
12360 @DefreqListEnd {boxa, macro}
12361 Begin (or append to) a diversion like the @code{di} and @code{da}
12362 requests.  The difference is that @code{box} and @code{boxa} do not
12363 include a partially-filled line in the diversion.
12365 Compare this:
12367 @Example
12368 Before the box.
12369 .box xxx
12370 In the box.
12372 .box
12373 After the box.
12375     @result{} Before the box.  After the box.
12376 .xxx
12377     @result{} In the box.
12378 @endExample
12380 @noindent
12381 with this:
12383 @Example
12384 Before the diversion.
12385 .di yyy
12386 In the diversion.
12389 After the diversion.
12391     @result{} After the diversion.
12392 .yyy
12393     @result{} Before the diversion.  In the diversion.
12394 @endExample
12396 @code{box} or @code{boxa} without an argument ends the diversion.
12397 @endDefreq
12399 @DefregList {.z}
12400 @DefregListEnd {.d}
12401 @cindex @code{nl} register, and @code{.d}
12402 @cindex nested diversions
12403 @cindex diversion, nested
12404 @cindex diversion name register (@code{.z})
12405 @cindex vertical position in diversion register (@code{.d})
12406 @cindex position, vertical, in diversion, register (@code{.d})
12407 @cindex diversion, vertical position in, register (@code{.d})
12408 Diversions may be nested.  The read-only number register @code{.z}
12409 contains the name of the current diversion (this is a string-valued
12410 register).  The read-only number register @code{.d} contains the current
12411 vertical place in the diversion.  If not in a diversion it is the same
12412 as register @code{nl}.
12413 @endDefreg
12415 @Defreg {.h}
12416 @cindex high-water mark register (@code{.h})
12417 @cindex mark, high-water, register (@code{.h})
12418 @cindex position of lowest text line (@code{.h})
12419 @cindex text line, position of lowest (@code{.h})
12420 The @dfn{high-water mark} on the current page.  It corresponds to the
12421 text baseline of the lowest line on the page.  This is a read-only
12422 register.
12424 @Example
12425 .tm .h==\n[.h], nl==\n[nl]
12426     @result{} .h==0, nl==-1
12427 This is a test.
12429 .sp 2
12430 .tm .h==\n[.h], nl==\n[nl]
12431     @result{} .h==40, nl==120
12432 @endExample
12434 @cindex @code{.h} register, difference to @code{nl}
12435 @cindex @code{nl} register, difference to @code{.h}
12436 @noindent
12437 As can be seen in the previous example, empty lines are not considered
12438 in the return value of the @code{.h} register.
12439 @endDefreg
12441 @DefregList {dn}
12442 @DefregListEnd {dl}
12443 @cindex @code{dn} register, and @code{da} (@code{boxa})
12444 @cindex @code{dl} register, and @code{da} (@code{boxa})
12445 @cindex @code{da} request, and @code{dn} (@code{dl})
12446 @cindex @code{boxa} request, and @code{dn} (@code{dl})
12447 After completing a diversion, the read-write number registers @code{dn}
12448 and @code{dl} contain the vertical and horizontal size of the diversion.
12449 Note that only the just processed lines are counted: For the computation
12450 of @code{dn} and @code{dl}, the requests @code{da} and @code{boxa} are
12451 handled as if @code{di} and @code{box} had been used -- lines which have
12452 been already stored in a macro are not taken into account.
12454 @Example
12455 .\" Center text both horizontally & vertically
12457 .\" Enclose macro definitions in .eo and .ec
12458 .\" to avoid the doubling of the backslash
12460 .\" macro .(c starts centering mode
12461 .de (c
12462 .  br
12463 .  ev (c
12464 .  evc 0
12465 .  in 0
12466 .  nf
12467 .  di @@c
12469 @endExample
12470 @Example
12471 .\" macro .)c terminates centering mode
12472 .de )c
12473 .  br
12474 .  ev
12475 .  di
12476 .  nr @@s (((\n[.t]u - \n[dn]u) / 2u) - 1v)
12477 .  sp \n[@@s]u
12478 .  ce 1000
12479 .  @@c
12480 .  ce 0
12481 .  sp \n[@@s]u
12482 .  br
12483 .  fi
12484 .  rr @@s
12485 .  rm @@s
12486 .  rm @@c
12488 .\" End of macro definitions, restore escape mechanism
12490 @endExample
12491 @endDefreg
12493 @DefescList {\\!, , , }
12494 @DefescListEnd {\\?, , anything, \\?}
12495 @cindex transparent output (@code{\!}, @code{\?})
12496 @cindex output, transparent (@code{\!}, @code{\?})
12497 Prevent requests, macros, and escapes from being interpreted when read
12498 into a diversion.  Both escapes take the given text and
12499 @dfn{transparently} embed it into the diversion.  This is useful for
12500 macros which shouldn't be invoked until the diverted text is actually
12501 output.
12503 The @code{\!} escape transparently embeds text up to and including the
12504 end of the line.  The @code{\?} escape transparently embeds text until
12505 the next occurrence of the @code{\?} escape.  Example:
12507 @Example
12508 \?@var{anything}\?
12509 @endExample
12511 @cindex @code{\?}, and copy-in mode
12512 @cindex copy-in mode, and @code{\?}
12513 @cindex mode, copy-in, and @code{\?}
12514 @cindex @code{\!}, and copy-in mode
12515 @cindex copy-in mode, and @code{\!}
12516 @cindex mode, copy-in, and @code{\!}
12517 @noindent
12518 @var{anything} may not contain newlines; use @code{\!}  to embed
12519 newlines in a diversion.  The escape sequence @code{\?} is also
12520 recognized in copy mode and turned into a single internal code; it is
12521 this code that terminates @var{anything}.  Thus the following example
12522 prints@tie{}4.
12524 @Example
12525 .nr x 1
12527 .di d
12528 \?\\?\\\\?\\\\\\\\nx\\\\?\\?\?
12530 .nr x 2
12531 .di e
12534 .nr x 3
12535 .di f
12538 .nr x 4
12540 @endExample
12542 Both escapes read the data in copy mode.
12544 @cindex @code{\!}, in top-level diversion
12545 @cindex top-level diversion, and @code{\!}
12546 @cindex diversion, top-level, and @code{\!}
12547 If @code{\!} is used in the top-level diversion, its argument is
12548 directly embedded into the @code{gtroff} intermediate output.  This can
12549 be used for example to control a postprocessor which processes the data
12550 before it is sent to the device driver.
12552 @cindex @code{\?}, in top-level diversion
12553 @cindex top-level diversion, and @code{\?}
12554 @cindex diversion, top-level, and @code{\?}
12555 The @code{\?} escape used in the top-level diversion produces no output
12556 at all; its argument is simply ignored.
12557 @endDefesc
12559 @cindex @code{\!}, and @code{output} request
12560 @cindex @code{output} request, and @code{\!}
12561 @cindex @code{output} request, and copy-in mode
12562 @cindex copy-in mode, and @code{output} request
12563 @cindex mode, copy-in, and @code{output} request
12564 @Defreq {output, string}
12565 Emit @var{string} directly to the @code{gtroff} intermediate output
12566 (subject to copy mode interpretation); this is similar to @code{\!} used
12567 at the top level.  An initial double quote in @var{string} is stripped
12568 off to allow initial blanks.
12570 This request can't be used before the first page has started -- if you
12571 get an error, simply insert @code{.br} before the @code{output} request.
12573 Without argument, @code{output} is ignored.
12575 Use with caution!  It is normally only needed for mark-up used by a
12576 postprocessor which does something with the output before sending it to
12577 the output device, filtering out @var{string} again.
12578 @endDefreq
12580 @Defreq {asciify, div}
12581 @cindex unformatting diversions (@code{asciify})
12582 @cindex diversion, unformatting (@code{asciify})
12583 @cindex @code{trin} request, and @code{asciify}
12584 @dfn{Unformat} the diversion specified by @var{div} in such a way that
12585 @acronym{ASCII} characters, characters translated with the @code{trin}
12586 request, space characters, and some escape sequences that were formatted
12587 and diverted are treated like ordinary input characters when the
12588 diversion is reread.  It can be also used for gross hacks; for example,
12589 the following sets register@tie{}@code{n} to@tie{}1.
12591 @Example
12592 .tr @@.
12593 .di x
12594 @@nr n 1
12597 .tr @@@@
12598 .asciify x
12600 @endExample
12602 @xref{Copy-in Mode}.
12603 @endDefreq
12605 @Defreq {unformat, div}
12606 Like @code{asciify}, unformat the specified diversion.  However,
12607 @code{unformat} only unformats spaces and tabs between words.
12608 Unformatted tabs are treated as input tokens, and spaces are stretchable
12609 again.
12611 The vertical size of lines is not preserved; glyph information (font,
12612 font size, space width, etc.)@: is retained.
12613 @endDefreq
12616 @c =====================================================================
12618 @node Environments, Suppressing output, Diversions, gtroff Reference
12619 @section Environments
12620 @cindex environments
12622 It happens frequently that some text should be printed in a certain
12623 format regardless of what may be in effect at the time, for example, in
12624 a trap invoked macro to print headers and footers.  To solve this
12625 @code{gtroff} processes text in @dfn{environments}.  An environment
12626 contains most of the parameters that control text processing.  It is
12627 possible to switch amongst these environments; by default @code{gtroff}
12628 processes text in environment@tie{}0.  The following is the information
12629 kept in an environment.
12631 @itemize @bullet
12632 @item
12633 font parameters (size, family, style, glyph height and slant, space and
12634 sentence space size)
12636 @item
12637 page parameters (line length, title length, vertical spacing, line
12638 spacing, indentation, line numbering, centering, right-justifying,
12639 underlining, hyphenation data)
12641 @item
12642 fill and adjust mode
12644 @item
12645 tab stops, tab and leader characters, escape character, no-break and
12646 hyphen indicators, margin character data
12648 @item
12649 partially collected lines
12651 @item
12652 input traps
12654 @item
12655 drawing and fill colours
12656 @end itemize
12658 These environments may be given arbitrary names (see @ref{Identifiers},
12659 for more info).  Old versions of @code{troff} only had environments
12660 named @samp{0}, @samp{1}, and @samp{2}.
12662 @DefreqList {ev, [@Var{env}]}
12663 @DefregListEnd {.ev}
12664 @cindex switching environments (@code{ev})
12665 @cindex environment, switching (@code{ev})
12666 @cindex environment number/name register (@code{.ev})
12667 Switch to another environment.  The argument @var{env} is the name of
12668 the environment to switch to.  With no argument, @code{gtroff} switches
12669 back to the previous environment.  There is no limit on the number of
12670 named environments; they are created the first time that they are
12671 referenced.  The @code{.ev} read-only register contains the name or
12672 number of the current environment.  This is a string-valued register.
12674 Note that a call to @code{ev} (with argument) pushes the previously
12675 active environment onto a stack.  If, say, environments @samp{foo},
12676 @samp{bar}, and @samp{zap} are called (in that order), the first
12677 @code{ev} request without parameter switches back to environment
12678 @samp{bar} (which is popped off the stack), and a second call switches
12679 back to environment @samp{foo}.
12681 Here is an example:
12683 @Example
12684 .ev footnote-env
12685 .fam N
12686 .ps 6
12687 .vs 8
12688 .ll -.5i
12693 .ev footnote-env
12694 \(dg Note the large, friendly letters.
12696 @endExample
12697 @endDefreq
12699 @Defreq {evc, env}
12700 @cindex copying environment (@code{evc})
12701 @cindex environment, copying (@code{evc})
12702 Copy the environment @var{env} into the current environment.
12704 The following environment data is not copied:
12706 @itemize @bullet
12707 @item
12708 Partially filled lines.
12710 @item
12711 The status whether the previous line was interrupted.
12713 @item
12714 The number of lines still to center, or to right-justify, or to
12715 underline (with or without underlined spaces); they are set to zero.
12717 @item
12718 The status whether a temporary indentation is active.
12720 @item
12721 Input traps and its associated data.
12723 @item
12724 Line numbering mode is disabled; it can be reactivated with @w{@samp{.nm
12725 +0}}.
12727 @item
12728 The number of consecutive hyphenated lines (set to zero).
12729 @end itemize
12730 @endDefreq
12732 @DefregList {.w}
12733 @DefregItem {.cht}
12734 @DefregItem {.cdp}
12735 @DefregListEnd {.csk}
12736 @cindex environment, dimensions of last glyph (@code{.w}, @code{.cht}, @code{.cdp}, @code{.csk})
12737 @cindex width, of last glyph (@code{.w})
12738 @cindex height, of last glyph (@code{.cht})
12739 @cindex depth, of last glyph (@code{.cdp})
12740 @cindex skew, of last glyph (@code{.csk})
12741 @cindex last glyph, dimensions (@code{.w}, @code{.cht}, @code{.cdp}, @code{.csk})
12742 @cindex glyph, last, dimensions (@code{.w}, @code{.cht}, @code{.cdp}, @code{.csk})
12743 The @code{\n[.w]} register contains the width of the last glyph added to
12744 the current environment.
12746 The @code{\n[.cht]} register contains the height of the last glyph added
12747 to the current environment.
12749 The @code{\n[.cdp]} register contains the depth of the last glyph added
12750 to the current environment.  It is positive for glyphs extending below
12751 the baseline.
12753 The @code{\n[.csk]} register contains the @dfn{skew} (how far to the
12754 right of the glyph's center that @code{gtroff} should place an accent)
12755 of the last glyph added to the current environment.
12756 @endDefreg
12758 @Defreg {.n}
12759 @cindex environment, previous line length (@code{.n})
12760 @cindex line length, previous (@code{.n})
12761 @cindex length of previous line (@code{.n})
12762 @cindex previous line length (@code{.n})
12763 The @code{\n[.n]} register contains the length of the previous output
12764 line in the current environment.
12765 @endDefreg
12768 @c =====================================================================
12770 @node Suppressing output, Colors, Environments, gtroff Reference
12771 @section Suppressing output
12773 @Defesc {\\O, , num, }
12774 @cindex suppressing output (@code{\O})
12775 @cindex output, suppressing (@code{\O})
12776 Disable or enable output depending on the value of @var{num}:
12778 @table @samp
12779 @item \O0
12780 Disable any glyphs from being emitted to the device driver, provided
12781 that the escape occurs at the outer level (see @code{\O[3]} and
12782 @code{\O[4]}).  Motion is not suppressed so effectively @code{\O[0]}
12783 means @emph{pen up}.
12785 @item \O1
12786 Enable output of glyphs, provided that the escape occurs at the outer
12787 level.
12788 @end table
12790 @vindex opminx
12791 @vindex opminy
12792 @vindex opmaxx
12793 @vindex opmaxy
12794 @code{\O0} and @code{\O1} also reset the four registers @samp{opminx},
12795 @samp{opminy}, @samp{opmaxx}, and @samp{opmaxy} to @minus{}1.
12796 @xref{Register Index}.  These four registers mark the top left and
12797 bottom right hand corners of a box which encompasses all written glyphs.
12799 For example the input text:
12801 @Example
12802 Hello \O[0]world \O[1]this is a test.
12803 @endExample
12805 @noindent
12806 produces the following output:
12808 @Example
12809 Hello       this is a test.
12810 @endExample
12812 @table @samp
12813 @item \O2
12814 Provided that the escape occurs at the outer level, enable output of
12815 glyphs and also write out to @code{stderr} the page number and four
12816 registers encompassing the glyphs previously written since the last call
12817 to @code{\O}.
12819 @item \O3
12820 Begin a nesting level.  At start-up, @code{gtroff} is at outer level.
12821 The current level is contained within the read-only register @code{.O}.
12822 @xref{Built-in Registers}.
12824 @item \O4
12825 End a nesting level.  The current level is contained within the
12826 read-only register @code{.O}.  @xref{Built-in Registers}.
12828 @item \O[5@var{P}@var{filename}]
12829 This escape is @code{grohtml} specific.  Provided that this escape
12830 occurs at the outer nesting level write the @code{filename} to
12831 @code{stderr}.  The position of the image, @var{P}, must be specified
12832 and must be one of @code{l}, @code{r}, @code{c}, or@tie{}@code{i} (left,
12833 right, centered, inline).  @var{filename} is associated with the
12834 production of the next inline image.
12835 @end table
12836 @endDefesc
12839 @c =====================================================================
12841 @node Colors, I/O, Suppressing output, gtroff Reference
12842 @section Colors
12843 @cindex colors
12845 @DefreqList {color, [@Var{n}]}
12846 @DefregListEnd {.color}
12847 If @var{n} is missing or non-zero, activate colors (this is the
12848 default); otherwise, turn it off.
12850 The read-only number register @code{.color} is@tie{}1 if colors are
12851 active, 0@tie{}otherwise.
12853 Internally, @code{color} sets a global flag; it does not produce a
12854 token.  Similar to the @code{cp} request, you should use it at the
12855 beginning of your document to control color output.
12857 Colors can be also turned off with the @option{-c} command line option.
12858 @endDefreq
12860 @Defreq {defcolor, ident scheme color_components}
12861 Define color with name @var{ident}.  @var{scheme} can be one of the
12862 following values: @code{rgb} (three components), @code{cmy} (three
12863 components), @code{cmyk} (four components), and @code{gray} or
12864 @code{grey} (one component).
12866 @cindex default color
12867 @cindex color, default
12868 Color components can be given either as a hexadecimal string or as
12869 positive decimal integers in the range 0--65535.  A hexadecimal string
12870 contains all color components concatenated.  It must start with either
12871 @code{#} or @code{##}; the former specifies hex values in the range
12872 0--255 (which are internally multiplied by@tie{}257), the latter in the
12873 range 0--65535.  Examples: @code{#FFC0CB} (pink), @code{##ffff0000ffff}
12874 (magenta).  The default color name @c{default} can't be redefined; its
12875 value is device-specific (usually black).  It is possible that the
12876 default color for @code{\m} and @code{\M} is not identical.
12878 @cindex @code{f} unit, and colors
12879 @cindex unit, @code{f}, and colors
12880 A new scaling indicator@tie{}@code{f} has been introduced which
12881 multiplies its value by 65536; this makes it convenient to specify color
12882 components as fractions in the range 0 to@tie{}1 (1f equals 65536u).
12883 Example:
12885 @Example
12886 .defcolor darkgreen rgb 0.1f 0.5f 0.2f
12887 @endExample
12889 Note that @code{f} is the default scaling indicator for the
12890 @code{defcolor} request, thus the above statement is equivalent to
12892 @Example
12893 .defcolor darkgreen rgb 0.1 0.5 0.2
12894 @endExample
12895 @endDefreq
12897 @DefreqList {gcolor, [@Var{color}]}
12898 @DefescItem {\\m, , c, }
12899 @DefescItem {\\m, @Lparen{}, co, }
12900 @DefescItem {\\m, @Lbrack{}, color, @Rbrack{}}
12901 @DefregListEnd {.m}
12902 Set (glyph) drawing color.  The following examples show how to turn the
12903 next four words red.
12905 @Example
12906 .gcolor red
12907 these are in red
12908 .gcolor
12909 and these words are in black.
12910 @endExample
12912 @Example
12913 \m[red]these are in red\m[] and these words are in black.
12914 @endExample
12916 The escape @code{\m[]} returns to the previous color, as does a call to
12917 @code{gcolor} without an argument.
12919 @cindex drawing color name register (@code{.m})
12920 @cindex name, drawing color, register (@code{.m})
12921 @cindex color name, drawing, register (@code{.m})
12922 The name of the current drawing color is available in the read-only,
12923 string-valued number register @samp{.m}.
12925 The drawing color is associated with the current environment
12926 (@pxref{Environments}).
12928 Note that @code{\m} doesn't produce an input token in @code{gtroff}.  As
12929 a consequence, it can be used in requests like @code{mc} (which expects
12930 a single character as an argument) to change the color on the fly:
12932 @Example
12933 .mc \m[red]x\m[]
12934 @endExample
12935 @endDefesc
12937 @DefreqList {fcolor, [@Var{color}]}
12938 @DefescItem {\\M, , c, }
12939 @DefescItem {\\M, @Lparen{}, co, }
12940 @DefescItem {\\M, @Lbrack{}, color, @Rbrack{}}
12941 @DefregListEnd {.M}
12942 Set fill (background) color for filled objects drawn with the
12943 @code{\D'@dots{}'} commands.
12945 A red ellipse can be created with the following code:
12947 @Example
12948 \M[red]\h'0.5i'\D'E 2i 1i'\M[]
12949 @endExample
12951 The escape @code{\M[]} returns to the previous fill color, as does a
12952 call to @code{fcolor} without an argument.
12954 @cindex background color name register (@code{.M})
12955 @cindex name, background color, register (@code{.M})
12956 @cindex color name, background, register (@code{.M})
12957 @cindex fill color name register (@code{.M})
12958 @cindex name, fill color, register (@code{.M})
12959 @cindex color name, fill, register (@code{.M})
12960 The name of the current fill (background) color is available in the
12961 read-only, string-valued number register @samp{.M}.
12963 The fill color is associated with the current environment
12964 (@pxref{Environments}).
12966 Note that @code{\M} doesn't produce an input token in @code{gtroff}.
12967 @endDefesc
12970 @c =====================================================================
12972 @node I/O, Postprocessor Access, Colors, gtroff Reference
12973 @section I/O
12974 @cindex i/o
12975 @cindex input and output requests
12976 @cindex requests for input and output
12977 @cindex output and input requests
12979 @code{gtroff} has several requests for including files:
12981 @Defreq {so, file}
12982 @cindex including a file (@code{so})
12983 @cindex file, inclusion (@code{so})
12984 Read in the specified @var{file} and includes it in place of the
12985 @code{so} request.  This is quite useful for large documents, e.g.@:
12986 keeping each chapter in a separate file.  @xref{gsoelim}, for more
12987 information.
12989 Since @code{gtroff} replaces the @code{so} request with the contents of
12990 @code{file}, it makes a difference whether the data is terminated with a
12991 newline or not: Assuming that file @file{xxx} contains the word
12992 @samp{foo} without a final newline, this
12994 @Example
12995 This is
12996 .so xxx
12998 @endExample
13000 @noindent
13001 yields @samp{This is foobar}.
13003 The search path for @var{file} can be controlled with the @option{-I}
13004 command line option.
13005 @endDefreq
13007 @Defreq {pso, command}
13008 Read the standard output from the specified @var{command} and includes
13009 it in place of the @code{pso} request.
13011 @cindex safer mode
13012 @cindex mode, safer
13013 @cindex unsafe mode
13014 @cindex mode, unsafe
13015 This request causes an error if used in safer mode (which is the
13016 default).  Use @code{groff}'s or @code{troff}'s @option{-U} option to
13017 activate unsafe mode.
13019 The comment regarding a final newline for the @code{so} request is valid
13020 for @code{pso} also.
13021 @endDefreq
13023 @Defreq {mso, file}
13024 Identical to the @code{so} request except that @code{gtroff} searches
13025 for the specified @var{file} in the same directories as macro files for
13026 the the @option{-m} command line option.  If the file name to be
13027 included has the form @file{@var{name}.tmac} and it isn't found,
13028 @code{mso} tries to include @file{tmac.@var{name}} and vice versa.
13029 @endDefreq
13031 @DefreqList {trf, file}
13032 @DefreqListEnd {cf, file}
13033 @cindex transparent output (@code{cf}, @code{trf})
13034 @cindex output, transparent (@code{cf}, @code{trf})
13035 @cindex @code{cf} request, and copy-in mode
13036 @cindex copy-in mode, and @code{cf} request
13037 @cindex mode, copy-in, and @code{cf} request
13038 @cindex @code{trf} request, and copy-in mode
13039 @cindex copy-in mode, and @code{trf} request
13040 @cindex mode, copy-in, and @code{trf} request
13041 Transparently output the contents of @var{file}.  Each line is output as
13042 if it were preceded by @code{\!}; however, the lines are @emph{not}
13043 subject to copy mode interpretation.  If the file does not end with a
13044 newline, then a newline is added (@code{trf} only).  For example, to
13045 define a macro@tie{}@code{x} containing the contents of
13046 file@tie{}@file{f}, use
13048 @Example
13049 .ev 1
13050 .di x
13051 .trf f
13054 @endExample
13056 @noindent
13057 The calls to @code{ev} prevent that the current partial input line
13058 becomes part of the diversion.
13060 Both @code{trf} and @code{cf}, when used in a diversion, embeds an
13061 object in the diversion which, when reread, causes the contents of
13062 @var{file} to be transparently copied through to the output.  In
13063 @acronym{UNIX} @code{troff}, the contents of @var{file} is immediately
13064 copied through to the output regardless of whether there is a current
13065 diversion; this behaviour is so anomalous that it must be considered a
13066 bug.
13068 @cindex @code{trf} request, and invalid characters
13069 @cindex characters, invalid for @code{trf} request
13070 @cindex invalid characters for @code{trf} request
13072 While @code{cf} copies the contents of @var{file} completely
13073 unprocessed, @code{trf} disallows characters such as NUL that are not
13074 valid @code{gtroff} input characters (@pxref{Identifiers}).
13076 For @code{cf}, within a diversion, `completely unprocessed' means that
13077 each line of a file to be inserted is handled as if it were preceded by
13078 @code{\!\\!}.
13080 Both requests cause a line break.
13081 @endDefreq
13083 @Defreq {nx, [@Var{file}]}
13084 @cindex processing next file (@code{nx})
13085 @cindex file, processing next (@code{nx})
13086 @cindex next file, processing (@code{nx})
13087 Force @code{gtroff} to continue processing of the file specified as an
13088 argument.  If no argument is given, immediately jump to the end of file.
13089 @endDefreq
13091 @Defreq {rd, [@Var{prompt} [@Var{arg1} @Var{arg2} @dots{}]]}
13092 @cindex reading from standard input (@code{rd})
13093 @cindex standard input, reading from (@code{rd})
13094 @cindex input, standard, reading from (@code{rd})
13095 Read from standard input, and include what is read as though it were
13096 part of the input file.  Text is read until a blank line is encountered.
13098 If standard input is a TTY input device (keyboard), write @var{prompt}
13099 to standard error, followed by a colon (or send BEL for a beep if no
13100 argument is given).
13102 Arguments after @var{prompt} are available for the input.  For example,
13103 the line
13105 @Example
13106 .rd data foo bar
13107 @endExample
13109 with the input @w{@samp{This is \$2.}} prints
13111 @Example
13112 This is bar.
13113 @endExample
13114 @endDefreq
13116 @cindex form letters
13117 @cindex letters, form
13118 Using the @code{nx} and @code{rd} requests, it is easy to set up form
13119 letters.  The form letter template is constructed like this, putting the
13120 following lines into a file called @file{repeat.let}:
13122 @Example
13124 \*(td
13125 .sp 2
13131 Body of letter.
13133 .nx repeat.let
13134 @endExample
13136 @cindex @code{ex} request, used with @code{nx} and @code{rd}
13137 @noindent
13138 When this is run, a file containing the following lines should be
13139 redirected in.  Note that requests included in this file are executed as
13140 though they were part of the form letter.  The last block of input is
13141 the @code{ex} request which tells @code{groff} to stop processing.  If
13142 this was not there, @code{groff} would not know when to stop.
13144 @Example
13145 Trent A. Fisher
13146 708 NW 19th Av., #202
13147 Portland, OR  97209
13149 Dear Trent,
13151 Len Adollar
13152 4315 Sierra Vista
13153 San Diego, CA  92103
13155 Dear Mr. Adollar,
13158 @endExample
13160 @Defreq {pi, pipe}
13161 Pipe the output of @code{gtroff} to the shell command(s) specified by
13162 @var{pipe}.  This request must occur before @code{gtroff} has a chance
13163 to print anything.
13165 @cindex safer mode
13166 @cindex mode, safer
13167 @cindex unsafe mode
13168 @cindex mode, unsafe
13169 @code{pi} causes an error if used in safer mode (which is the default).
13170 Use @code{groff}'s or @code{troff}'s @option{-U} option to activate
13171 unsafe mode.
13173 Multiple calls to @code{pi} are allowed, acting as a chain.  For
13174 example,
13176 @Example
13177 .pi foo
13178 .pi bar
13180 @endExample
13182 is the same as @w{@samp{.pi foo | bar}}.
13184 @cindex @code{groff}, and @code{pi} request
13185 @cindex @code{pi} request, and @code{groff}
13186 Note that the intermediate output format of @code{gtroff} is piped to
13187 the specified commands.  Consequently, calling @code{groff} without the
13188 @option{-Z} option normally causes a fatal error.
13189 @endDefreq
13191 @DefreqList {sy, cmds}
13192 @DefregListEnd {systat}
13193 Execute the shell command(s) specified by @var{cmds}.  The output is not
13194 saved anyplace, so it is up to the user to do so.
13196 @cindex safer mode
13197 @cindex mode, safer
13198 @cindex unsafe mode
13199 @cindex mode, unsafe
13200 This request causes an error if used in safer mode (which is the
13201 default).  Use @code{groff}'s or @code{troff}'s @option{-U} option to
13202 activate unsafe mode.
13204 For example, the following code fragment introduces the current time
13205 into a document:
13207 @cindex time, current
13208 @cindex current time
13209 @pindex perl
13210 @Example
13211 .sy perl -e 'printf ".nr H %d\\n.nr M %d\\n.nr S %d\\n",\
13212              (localtime(time))[2,1,0]' > /tmp/x\n[$$]
13213 .so /tmp/x\n[$$]
13214 .sy rm /tmp/x\n[$$]
13215 \nH:\nM:\nS
13216 @endExample
13218 @noindent
13219 Note that this works by having the @code{perl} script (run by @code{sy})
13220 print out the @code{nr} requests which set the number registers
13221 @code{H}, @code{M}, and @code{S}, and then reads those commands in with
13222 the @code{so} request.
13224 For most practical purposes, the number registers @code{seconds},
13225 @code{minutes}, and @code{hours} which are initialized at start-up of
13226 @code{gtroff} should be sufficient.  Use the @code{af} request to get a
13227 formatted output:
13229 @Example
13230 .af hours 00
13231 .af minutes 00
13232 .af seconds 00
13233 \n[hours]:\n[minutes]:\n[seconds]
13234 @endExample
13236 @cindex @code{system()} return value register (@code{systat})
13237 The @code{systat} read-write number register contains the return value
13238 of the @code{system()} function executed by the last @code{sy} request.
13239 @endDefreq
13241 @DefreqList {open, stream file}
13242 @DefreqListEnd {opena, stream file}
13243 @cindex opening file (@code{open})
13244 @cindex file, opening (@code{open})
13245 @cindex appending to a file (@code{opena})
13246 @cindex file, appending to (@code{opena})
13247 Open the specified @var{file} for writing and associates the specified
13248 @var{stream} with it.
13250 The @code{opena} request is like @code{open}, but if the file exists,
13251 append to it instead of truncating it.
13253 @cindex safer mode
13254 @cindex mode, safer
13255 @cindex unsafe mode
13256 @cindex mode, unsafe
13257 Both @code{open} and @code{opena} cause an error if used in safer mode
13258 (which is the default).  Use @code{groff}'s or @code{troff}'s
13259 @option{-U} option to activate unsafe mode.
13260 @endDefreq
13262 @DefreqList {write, stream data}
13263 @DefreqListEnd {writec, stream data}
13264 @cindex copy-in mode, and @code{write} request
13265 @cindex @code{write} request, and copy-in mode
13266 @cindex mode, copy-in, and @code{write} request
13267 @cindex copy-in mode, and @code{writec} request
13268 @cindex @code{writec} request, and copy-in mode
13269 @cindex mode, copy-in, and @code{writec} request
13270 @cindex writing to file (@code{write}, @code{writec})
13271 @cindex file, writing to (@code{write}, @code{writec})
13272 Write to the file associated with the specified @var{stream}.  The
13273 stream must previously have been the subject of an open request.  The
13274 remainder of the line is interpreted as the @code{ds} request reads its
13275 second argument: A leading @samp{"} is stripped, and it is read in
13276 copy-in mode.
13278 The @code{writec} request is like @code{write}, but only @code{write}
13279 appends a newline to the data.
13280 @endDefreq
13282 @Defreq {writem, stream xx}
13283 @cindex @code{asciify} request, and @code{writem}
13284 Write the contents of the macro or string @var{xx} to the file
13285 associated with the specified @var{stream}.
13287 @cindex @code{writem} request, and copy-in mode
13288 @cindex copy-in mode, and @code{writem} request
13289 @cindex mode, copy-in, and @code{writem} request
13290 @var{xx} is read in copy mode, i.e., already formatted elements are
13291 ignored.  Consequently, diversions must be unformatted with the
13292 @code{asciify} request before calling @code{writem}.  Usually, this
13293 means a loss of information.
13294 @endDefreq
13296 @Defreq {close, stream}
13297 @cindex closing file (@code{close})
13298 @cindex file, closing (@code{close})
13299 Close the specified @var{stream}; the stream is no longer an acceptable
13300 argument to the @code{write} request.
13302 Here a simple macro to write an index entry.
13304 @Example
13305 .open idx test.idx
13307 .de IX
13308 .  write idx \\n[%] \\$*
13311 .IX test entry
13313 .close idx
13314 @endExample
13315 @endDefreq
13317 @DefescList {\\V, , e, }
13318 @DefescItem {\\V, @Lparen{}, ev, }
13319 @DefescListEnd {\\V, @Lbrack{}, env, @Rbrack{}}
13320 @cindex @code{\V}, and copy-in mode
13321 @cindex copy-in mode, and @code{\V}
13322 @cindex mode, copy-in, and @code{\V}
13323 Interpolate the contents of the specified environment variable @var{env}
13324 (one-character name@tie{}@var{e}, two-character name @var{ev}) as
13325 returned by the function @code{getenv}.  @code{\V} is interpreted in
13326 copy-in mode.
13327 @endDefesc
13330 @c =====================================================================
13332 @node Postprocessor Access, Miscellaneous, I/O, gtroff Reference
13333 @section Postprocessor Access
13334 @cindex postprocessor access
13335 @cindex access of postprocessor
13337 There are two escapes which give information directly to the
13338 postprocessor.  This is particularly useful for embedding
13339 @sc{PostScript} into the final document.
13341 @DefreqList {device, xxx}
13342 @DefescListEnd {\\X, ', xxx, '}
13343 Embeds its argument into the @code{gtroff} output preceded with
13344 @w{@samp{x X}}.
13346 @cindex @code{\&}, in @code{\X}
13347 @cindex @code{\)}, in @code{\X}
13348 @cindex @code{\%}, in @code{\X}
13349 @ifnotinfo
13350 @cindex @code{\:}, in @code{\X}
13351 @end ifnotinfo
13352 @ifinfo
13353 @cindex @code{\@r{<colon>}}, in @code{\X}
13354 @end ifinfo
13355 The escapes @code{\&}, @code{\)}, @code{\%}, and @code{\:} are ignored
13356 within @code{\X}, @w{@samp{\ }} and @code{\~} are converted to single
13357 space characters.  All other escapes (except @code{\\} which produces a
13358 backslash) cause an error.
13360 @cindex @code{device} request, and copy-in mode
13361 @cindex copy-in mode, and @code{device} request
13362 @cindex mode, copy-in, and @code{device} request
13363 Contrary to @code{\X}, the @code{device} request simply processes its
13364 argument in copy mode (@pxref{Copy-in Mode}).
13366 @kindex use_charnames_in_special
13367 @pindex DESC@r{, and @code{use_charnames_in_special}}
13368 @cindex @code{\X}, and special characters
13369 If the @samp{use_charnames_in_special} keyword is set in the @file{DESC}
13370 file, special characters no longer cause an error; they are simply
13371 output verbatim.  Additionally, the backslash is represented as
13372 @code{\\}.
13374 @samp{use_charnames_in_special} is currently used by @code{grohtml}
13375 only.
13376 @endDefesc
13378 @DefreqList {devicem, xx}
13379 @DefescItem {\\Y, , n, }
13380 @DefescItem {\\Y, @Lparen{}, nm, }
13381 @DefescListEnd {\\Y, @Lbrack{}, name, @Rbrack{}}
13382 This is approximately equivalent to @samp{\X'\*[@var{name}]'}
13383 (one-character name@tie{}@var{n}, two-character name @var{nm}).
13384 However, the contents of the string or macro @var{name} are not
13385 interpreted; also it is permitted for @var{name} to have been defined as
13386 a macro and thus contain newlines (it is not permitted for the argument
13387 to @code{\X} to contain newlines).  The inclusion of newlines requires
13388 an extension to the @acronym{UNIX} @code{troff} output format, and
13389 confuses drivers that do not know about this extension (@pxref{Device
13390 Control Commands}).
13391 @endDefesc
13393 @xref{Output Devices}.
13396 @c =====================================================================
13398 @node Miscellaneous, Gtroff Internals, Postprocessor Access, gtroff Reference
13399 @section Miscellaneous
13401 This section documents parts of @code{gtroff} which cannot (yet) be
13402 categorized elsewhere in this manual.
13404 @Defreq {nm, [@Var{start} [@Var{inc} [@Var{space} [@Var{indent}]]]]}
13405 @cindex printing line numbers (@code{nm})
13406 @cindex line numbers, printing (@code{nm})
13407 @cindex numbers, line, printing (@code{nm})
13408 Print line numbers.  @var{start} is the line number of the @emph{next}
13409 output line.  @var{inc} indicates which line numbers are printed.  For
13410 example, the value@tie{}5 means to emit only line numbers which are
13411 multiples of@tie{}5; this defaults to@tie{}1.  @var{space} is the space
13412 to be left between the number and the text; this defaults to one digit
13413 space.  The fourth argument is the indentation of the line numbers,
13414 defaulting to zero.  Both @var{space} and @var{indent} are given as
13415 multiples of digit spaces; they can be negative also.  Without any
13416 arguments, line numbers are turned off.
13418 @code{gtroff} reserves three digit spaces for the line number (which is
13419 printed right-justified) plus the amount given by @var{indent}; the
13420 output lines are concatenated to the line numbers, separated by
13421 @var{space}, and @emph{without} reducing the line length.  Depending on
13422 the value of the horizontal page offset (as set with the @code{po}
13423 request), line numbers which are longer than the reserved space stick
13424 out to the left, or the whole line is moved to the right.
13426 Parameters corresponding to missing arguments are not changed; any
13427 non-digit argument (to be more precise, any argument starting with a
13428 character valid as a delimiter for identifiers) is also treated as
13429 missing.
13431 If line numbering has been disabled with a call to @code{nm} without an
13432 argument, it can be reactivated with @samp{.nm +0}, using the previously
13433 active line numbering parameters.
13435 The parameters of @code{nm} are associated with the current environment
13436 (@pxref{Environments}).  The current output line number is available in
13437 the number register @code{ln}.
13439 @Example
13440 .po 1m
13441 .ll 2i
13442 This test shows how line numbering works with groff.
13443 .nm 999
13444 This test shows how line numbering works with groff.
13446 .nm xxx 3 2
13447 .ll -\w'0'u
13448 This test shows how line numbering works with groff.
13449 .nn 2
13450 This test shows how line numbering works with groff.
13451 @endExample
13453 @noindent
13454 And here the result:
13456 @Example
13457  This  test shows how
13458  line numbering works
13459  999 with   groff.   This
13460 1000 test shows how  line
13461 1001 numbering works with
13462 1002 groff.
13463       This test shows how
13464       line      numbering
13465  works  with  groff.
13466  This test shows how
13467 1005  line      numbering
13468       works with groff.
13469 @endExample
13470 @endDefreq
13472 @Defreq {nn, [@Var{skip}]}
13473 Temporarily turn off line numbering.  The argument is the number of
13474 lines not to be numbered; this defaults to@tie{}1.
13475 @endDefreq
13477 @Defreq {mc, glyph [@Var{dist}]}
13478 @cindex margin glyph (@code{mc})
13479 @cindex glyph, for margins (@code{mc})
13480 Print a @dfn{margin character} to the right of the
13481 text.@footnote{@dfn{Margin character} is a misnomer since it is an
13482 output glyph.}  The first argument is the glyph to be printed.  The
13483 second argument is the distance away from the right margin.  If missing,
13484 the previously set value is used; default is 10@dmn{pt}).  For text
13485 lines that are too long (that is, longer than the text length plus
13486 @var{dist}), the margin character is directly appended to the lines.
13488 With no arguments the margin character is turned off.  If this occurs
13489 before a break, no margin character is printed.
13491 For compatibility with @acronym{AT&T} @code{troff}, a call to @code{mc}
13492 to set the margin character can't be undone immediately; at least one
13493 line gets a margin character.  Thus
13495 @Example
13496 .ll 1i
13497 .mc \[br]
13502 @endExample
13504 @noindent
13505 produces
13507 @Example
13508 xxx        |
13510 @endExample
13512 @cindex @code{tl} request, and @code{mc}
13513 For empty lines and lines produced by the @code{tl} request no margin
13514 character is emitted.
13516 The margin character is associated with the current environment
13517 (@pxref{Environments}).
13519 @pindex nrchbar
13520 @pindex changebar
13521 This is quite useful for indicating text that has changed, and, in fact,
13522 there are programs available for doing this (they are called
13523 @code{nrchbar} and @code{changebar} and can be found in any
13524 @samp{comp.sources.unix} archive).
13526 @Example
13527 .ll 3i
13528 .mc |
13529 This paragraph is highlighted with a margin
13530 character.
13532 Note that vertical space isn't marked.
13536 But we can fake it with `\&'.
13537 @endExample
13539 Result:
13541 @Example
13542 This  paragraph is highlighted |
13543 with a margin character.       |
13545 Note that vertical space isn't |
13546 marked.                        |
13547                                |
13548 But we can fake it with `\&'.  |
13549 @endExample
13550 @endDefreq
13552 @DefreqList {psbb, filename}
13553 @DefregItem {llx}
13554 @DefregItem {lly}
13555 @DefregItem {urx}
13556 @DefregListEnd {ury}
13557 @cindex PostScript, bounding box
13558 @cindex bounding box
13559 Retrieve the bounding box of the PostScript image found in
13560 @var{filename}.  The file must conform to Adobe's @dfn{Document
13561 Structuring Conventions} (DSC); the command searches for a
13562 @code{%%BoundingBox} comment and extracts the bounding box values into
13563 the number registers @code{llx}, @code{lly}, @code{urx}, and @code{ury}.
13564 If an error occurs (for example, @code{psbb} cannot find the
13565 @code{%%BoundingBox} comment), it sets the four number registers to
13566 zero.
13568 The search path for @var{filename} can be controlled with the
13569 @option{-I} command line option.
13570 @endDefreq
13573 @c =====================================================================
13575 @node Gtroff Internals, Debugging, Miscellaneous, gtroff Reference
13576 @section @code{gtroff} Internals
13578 @cindex input token
13579 @cindex token, input
13580 @cindex output node
13581 @cindex node, output
13582 @code{gtroff} processes input in three steps.  One or more input
13583 characters are converted to an @dfn{input token}.@footnote{Except the
13584 escapes @code{\f}, @code{\F}, @code{\H}, @code{\m}, @code{\M},
13585 @code{\R}, @code{\s}, and @code{\S} which are processed immediately if
13586 not in copy-in mode.}  Then, one or more input tokens are converted to
13587 an @dfn{output node}.  Finally, output nodes are converted to the
13588 intermediate output language understood by all output devices.
13590 Actually, before step one happens, @code{gtroff} converts certain escape
13591 sequences into reserved input characters (not accessible by the user);
13592 such reserved characters are used for other internal processing also --
13593 this is the very reason why not all characters are valid input.
13594 @xref{Identifiers}, for more on this topic.
13596 For example, the input string @samp{fi\[:u]} is converted into a
13597 character token @samp{f}, a character token @samp{i}, and a special
13598 token @samp{:u} (representing u@tie{}umlaut).  Later on, the character
13599 tokens @samp{f} and @samp{i} are merged to a single output node
13600 representing the ligature glyph @samp{fi} (provided the current font has
13601 a glyph for this ligature); the same happens with @samp{:u}.  All output
13602 glyph nodes are `processed' which means that they are invariably
13603 associated with a given font, font size, advance width, etc.  During the
13604 formatting process, @code{gtroff} itself adds various nodes to control
13605 the data flow.
13607 Macros, diversions, and strings collect elements in two chained lists: a
13608 list of input tokens which have been passed unprocessed, and a list of
13609 output nodes.  Consider the following the diversion.
13611 @Example
13612 .di xxx
13618 @endExample
13620 @noindent
13621 It contains these elements.
13623 @multitable {@i{vertical size node}} {token list} {element number}
13624 @item node list               @tab token list @tab element number
13626 @item @i{line start node}     @tab ---        @tab 1
13627 @item @i{glyph node @code{a}} @tab ---        @tab 2
13628 @item @i{word space node}     @tab ---        @tab 3
13629 @item ---                     @tab @code{b}   @tab 4
13630 @item ---                     @tab @code{\n}  @tab 5
13631 @item @i{glyph node @code{c}} @tab ---        @tab 6
13632 @item @i{vertical size node}  @tab ---        @tab 7
13633 @item @i{vertical size node}  @tab ---        @tab 8
13634 @item ---                     @tab @code{\n}  @tab 9
13635 @end multitable
13637 @cindex @code{\v}, internal representation
13638 @noindent
13639 Elements 1, 7, and@tie{}8 are inserted by @code{gtroff}; the latter two
13640 (which are always present) specify the vertical extent of the last line,
13641 possibly modified by @code{\x}.  The @code{br} request finishes the
13642 current partial line, inserting a newline input token which is
13643 subsequently converted to a space when the diversion is reread.  Note
13644 that the word space node has a fixed width which isn't stretchable
13645 anymore.  To convert horizontal space nodes back to input tokens, use
13646 the @code{unformat} request.
13648 Macros only contain elements in the token list (and the node list is
13649 empty); diversions and strings can contain elements in both lists.
13651 Note that the @code{chop} request simply reduces the number of elements
13652 in a macro, string, or diversion by one.  Exceptions are
13653 @dfn{compatibility save} and @dfn{compatibility ignore} input tokens
13654 which are ignored.  The @code{substring} request also ignores those
13655 input tokens.
13657 Some requests like @code{tr} or @code{cflags} work on glyph identifiers
13658 only; this means that the associated glyph can be changed without
13659 destroying this association.  This can be very helpful for substituting
13660 glyphs.  In the following example, we assume that glyph @samp{foo} isn't
13661 available by default, so we provide a substitution using the
13662 @code{fchar} request and map it to input character @samp{x}.
13664 @Example
13665 .fchar \[foo] foo
13666 .tr x \[foo]
13667 @endExample
13669 @noindent
13670 Now let us assume that we install an additional special font @samp{bar}
13671 which has glyph @samp{foo}.
13673 @Example
13674 .special bar
13675 .rchar \[foo]
13676 @endExample
13678 @noindent
13679 Since glyphs defined with @code{fchar} are searched before glyphs in
13680 special fonts, we must call @code{rchar} to remove the definition of the
13681 fallback glyph.  Anyway, the translation is still active; @samp{x} now
13682 maps to the real glyph @samp{foo}.
13684 @cindex compatibility mode, and parameters
13685 @cindex mode, compatibility, and parameters
13686 @cindex arguments, and compatibility mode
13687 @cindex parameters, and compatibility mode
13688 @cindex macro arguments, and compatibility mode
13689 @cindex request arguments, and compatibility mode
13690 Macro and request arguments preserve the compatibility mode:
13692 @Example
13693 .cp 1     \" switch to compatibility mode
13694 .de xx
13695 \\$1
13697 .cp 0     \" switch compatibility mode off
13698 .xx caf\['e]
13699     @result{} café
13700 @endExample
13702 @noindent
13703 Since compatibility mode is on while @code{de} is called, the macro
13704 @code{xx} activates compatibility mode while executing.  Argument
13705 @code{$1} can still be handled properly because it inherits the
13706 compatibility mode status which was active at the point where @code{xx}
13707 is called.
13709 After expansion of the parameters, the compatibility save and restore
13710 tokens are removed.
13713 @c =====================================================================
13715 @node Debugging, Implementation Differences, Gtroff Internals, gtroff Reference
13716 @section Debugging
13717 @cindex debugging
13719 @code{gtroff} is not easy to debug, but there are some useful features
13720 and strategies for debugging.
13722 @Defreq {lf, line [@Var{filename}]}
13723 @pindex soelim
13724 @cindex multi-file documents
13725 @cindex documents, multi-file
13726 @cindex setting input line number (@code{lf})
13727 @cindex input line number, setting (@code{lf})
13728 @cindex number, input line, setting (@code{lf})
13729 Change the line number and optionally the file name @code{gtroff} shall
13730 use for error and warning messages.  @var{line} is the input line number
13731 of the @emph{next} line.
13733 Without argument, the request is ignored.
13735 This is a debugging aid for documents which are split into many files,
13736 then put together with @code{soelim} and other preprocessors.  Usually,
13737 it isn't invoked manually.
13739 Note that other @code{troff} implementations (including the original
13740 @acronym{AT&T} version) handle @code{lf} differently.  For them,
13741 @var{line} changes the line number of the @emph{current} line.
13742 @endDefreq
13744 @DefreqList {tm, string}
13745 @DefreqItem {tm1, string}
13746 @DefreqListEnd {tmc, string}
13747 @cindex printing to stderr (@code{tm}, @code{tm1}, @code{tmc})
13748 @cindex stderr, printing to (@code{tm}, @code{tm1}, @code{tmc})
13749 Send @var{string} to the standard error output; this is very useful for
13750 printing debugging messages among other things.
13752 @cindex @code{tm} request, and copy-in mode
13753 @cindex copy-in mode, and @code{tm} request
13754 @cindex mode, copy-in, and @code{tm} request
13755 @cindex @code{tm1} request, and copy-in mode
13756 @cindex copy-in mode, and @code{tm1} request
13757 @cindex mode, copy-in, and @code{tm1} request
13758 @cindex @code{tmc} request, and copy-in mode
13759 @cindex copy-in mode, and @code{tmc} request
13760 @cindex mode, copy-in, and @code{tmc} request
13761 @var{string} is read in copy mode.
13763 The @code{tm} request ignores leading spaces of @var{string}; @code{tm1}
13764 handles its argument similar to the @code{ds} request: a leading double
13765 quote in @var{string} is stripped to allow initial blanks.
13767 The @code{tmc} request is similar to @code{tm1} but does not append a
13768 newline (as is done in @code{tm} and @code{tm1}).
13769 @endDefreq
13771 @Defreq {ab, [@Var{string}]}
13772 @cindex aborting (@code{ab})
13773 Similar to the @code{tm} request, except that it causes @code{gtroff} to
13774 stop processing.  With no argument it prints @samp{User Abort.} to
13775 standard error.
13776 @endDefreq
13778 @Defreq {ex, }
13779 @cindex @code{ex} request, use in debugging
13780 @cindex exiting (@code{ex})
13781 The @code{ex} request also causes @code{gtroff} to stop processing; see
13782 also @ref{I/O}.
13783 @endDefreq
13785 When doing something involved it is useful to leave the debugging
13786 statements in the code and have them turned on by a command line flag.
13788 @Example
13789 .if \n(DB .tm debugging output
13790 @endExample
13792 @noindent
13793 To activate these statements say
13795 @Example
13796 groff -rDB=1 file
13797 @endExample
13799 If it is known in advance that there are many errors and no useful
13800 output, @code{gtroff} can be forced to suppress formatted output with
13801 the @option{-z} flag.
13803 @Defreq {pev, }
13804 @cindex dumping environments (@code{pev})
13805 @cindex environments, dumping (@code{pev})
13806 Print the contents of the current environment and all the currently
13807 defined environments (both named and numbered) on @code{stderr}.
13808 @endDefreq
13810 @Defreq {pm, }
13811 @cindex dumping symbol table (@code{pm})
13812 @cindex symbol table, dumping (@code{pm})
13813 Print the entire symbol table on @code{stderr}.  Names of all defined
13814 macros, strings, and diversions are print together with their size in
13815 bytes.  Since @code{gtroff} sometimes adds nodes by itself, the returned
13816 size can be larger than expected.
13818 This request differs from @acronym{UNIX} @code{troff}: @code{gtroff}
13819 reports the sizes of diversions, ignores an additional argument to print
13820 only the total of the sizes, and the size isn't returned in blocks of
13821 128 characters.
13822 @endDefreq
13824 @Defreq {pnr, }
13825 @cindex dumping number registers (@code{pnr})
13826 @cindex number registers, dumping (@code{pnr})
13827 Print the names and contents of all currently defined number registers
13828 on @code{stderr}.
13829 @endDefreq
13831 @Defreq {ptr, }
13832 @cindex dumping traps (@code{ptr})
13833 @cindex traps, dumping (@code{ptr})
13834 Print the names and positions of all traps (not including input line
13835 traps and diversion traps) on @code{stderr}.  Empty slots in the page
13836 trap list are printed as well, because they can affect the priority of
13837 subsequently planted traps.
13838 @endDefreq
13840 @Defreq {fl, }
13841 @cindex flush output (@code{fl})
13842 @cindex output, flush (@code{fl})
13843 @cindex interactive use of @code{gtroff}
13844 @cindex @code{gtroff}, interactive use
13845 Instruct @code{gtroff} to flush its output immediately.  The intent is
13846 for interactive use, but this behaviour is currently not implemented in
13847 @code{gtroff}.  Contrary to @acronym{UNIX} @code{troff}, TTY output is
13848 sent to a device driver also (@code{grotty}), making it non-trivial to
13849 communicate interactively.
13851 This request causes a line break.
13852 @endDefreq
13854 @Defreq {backtrace, }
13855 @cindex backtrace of input stack (@code{backtrace})
13856 @cindex input stack, backtrace (@code{backtrace})
13857 Print a backtrace of the input stack to the standard error stream.
13859 Consider the following in file @file{test}:
13861 @Example
13862 .de xxx
13863 .  backtrace
13865 .de yyy
13866 .  xxx
13869 .yyy
13870 @endExample
13872 @noindent
13873 On execution, @code{gtroff} prints the following:
13875 @Example
13876 test:2: backtrace: macro `xxx'
13877 test:5: backtrace: macro `yyy'
13878 test:8: backtrace: file `test'
13879 @endExample
13881 The option @option{-b} of @code{gtroff} internally calls a variant of
13882 this request on each error and warning.
13883 @endDefreq
13885 @Defreg {slimit}
13886 @cindex input stack, setting limit
13887 Use the @code{slimit} number register to set the maximum number of
13888 objects on the input stack.  If @code{slimit} is less than or equal
13889 to@tie{}0, there is no limit set.  With no limit, a buggy recursive
13890 macro can exhaust virtual memory.
13892 The default value is 1000; this is a compile-time constant.
13893 @endDefreg
13895 @Defreq {warnscale, si}
13896 Set the scaling indicator used in warnings to @var{si}.  Valid values
13897 for @var{si} are @samp{u}, @samp{i}, @samp{c}, @samp{p}, and @samp{P}.
13898 At startup, it is set to @samp{i}.
13899 @endDefreq
13901 @Defreq {spreadwarn, [@Var{limit}]}
13902 Make @code{gtroff} emit a warning if the additional space inserted for
13903 each space between words in an output line is larger or equal to
13904 @var{limit}.  A negative value is changed to zero; no argument toggles
13905 the warning on and off without changing @var{limit}.  The default
13906 scaling indicator is @samp{m}.  At startup, @code{spreadwarn} is
13907 deactivated, and @var{limit} is set to 3@dmn{m}.
13909 For example,
13911 @Example
13912 .spreadwarn 0.2m
13913 @endExample
13915 @noindent
13916 causes a warning if @code{gtroff} must add 0.2@dmn{m} or more for each
13917 interword space in a line.
13919 This request is active only if text is justified to both margins (using
13920 @w{@samp{.ad b}}).
13921 @endDefreq
13923 @cindex warnings
13924 @code{gtroff} has command line options for printing out more warnings
13925 (@option{-w}) and for printing backtraces (@option{-b}) when a warning
13926 or an error occurs.  The most verbose level of warnings is @option{-ww}.
13928 @DefreqList {warn, [@Var{flags}]}
13929 @DefregListEnd {.warn}
13930 @cindex level of warnings (@code{warn})
13931 @cindex warnings, level (@code{warn})
13932 Control the level of warnings checked for.  The @var{flags} are the sum
13933 of the numbers associated with each warning that is to be enabled; all
13934 other warnings are disabled.  The number associated with each warning is
13935 listed below.  For example, @w{@code{.warn 0}} disables all warnings,
13936 and @w{@code{.warn 1}} disables all warnings except that about missing
13937 glyphs.  If no argument is given, all warnings are enabled.
13939 The read-only number register @code{.warn} contains the current warning
13940 level.
13941 @endDefreq
13943 @menu
13944 * Warnings::
13945 @end menu
13947 @c ---------------------------------------------------------------------
13949 @node Warnings,  , Debugging, Debugging
13950 @subsection Warnings
13951 @cindex warnings
13953 The warnings that can be given to @code{gtroff} are divided into the
13954 following categories.  The name associated with each warning is used by
13955 the @option{-w} and @option{-W} options; the number is used by the
13956 @code{warn} request and by the @code{.warn} register.
13958 @table @samp
13959 @item char
13960 @itemx 1
13961 Non-existent glyphs.@footnote{@code{char} is a misnomer since it reports
13962 missing glyphs -- there aren't missing input characters, only invalid
13963 ones.}  This is enabled by default.
13965 @item number
13966 @itemx 2
13967 Invalid numeric expressions.  This is enabled by default.
13968 @xref{Expressions}.
13970 @item break
13971 @itemx 4
13972 @cindex fill mode
13973 @cindex mode, fill
13974 In fill mode, lines which could not be broken so that their length was
13975 less than the line length.  This is enabled by default.
13977 @item delim
13978 @itemx 8
13979 Missing or mismatched closing delimiters.
13981 @item el
13982 @itemx 16
13983 @cindex @code{ie} request, and warnings
13984 @cindex @code{el} request, and warnings
13985 Use of the @code{el} request with no matching @code{ie} request.
13986 @xref{if-else}.
13988 @item scale
13989 @itemx 32
13990 Meaningless scaling indicators.
13992 @item range
13993 @itemx 64
13994 Out of range arguments.
13996 @item syntax
13997 @itemx 128
13998 Dubious syntax in numeric expressions.
14000 @item di
14001 @itemx 256
14002 @cindex @code{di} request, and warnings
14003 @cindex @code{da} request, and warnings
14004 Use of @code{di} or @code{da} without an argument when there is no
14005 current diversion.
14007 @item mac
14008 @itemx 512
14009 @cindex @code{de}, @code{de1}, @code{dei} requests, and warnings
14010 @cindex @code{am}, @code{am1}, @code{ami} requests, and warnings
14011 @cindex @code{ds}, @code{ds1} requests, and warnings
14012 @cindex @code{as}, @code{as1} requests, and warnings
14013 @cindex @code{di} request, and warnings
14014 @cindex @code{da} request, and warnings
14015 @cindex @code{box}, @code{boxa} requests, and warnings
14016 @cindex @code{\*}, and warnings
14017 Use of undefined strings, macros and diversions.  When an undefined
14018 string, macro, or diversion is used, that string is automatically
14019 defined as empty.  So, in most cases, at most one warning is given for
14020 each name.
14022 @item reg
14023 @itemx 1024
14024 @cindex @code{nr} request, and warnings
14025 @cindex @code{\R}, and warnings
14026 @cindex @code{\n}, and warnings
14027 Use of undefined number registers.  When an undefined number register is
14028 used, that register is automatically defined to have a value of@tie{}0.
14029 So, in most cases, at most one warning is given for use of a particular
14030 name.
14032 @item tab
14033 @itemx 2048
14034 @cindex @code{\t}, and warnings
14035 Use of a tab character where a number was expected.
14037 @item right-brace
14038 @itemx 4096
14039 @cindex @code{\@}}, and warnings
14040 Use of @code{\@}} where a number was expected.
14042 @item missing
14043 @itemx 8192
14044 Requests that are missing non-optional arguments.
14046 @item input
14047 @itemx 16384
14048 Invalid input characters.
14050 @item escape
14051 @itemx 32768
14052 Unrecognized escape sequences.  When an unrecognized escape sequence
14053 @code{\@var{X}} is encountered, the escape character is ignored, and
14054 @var{X} is printed.
14056 @item space
14057 @itemx 65536
14058 @cindex compatibility mode
14059 Missing space between a request or macro and its argument.  This warning
14060 is given when an undefined name longer than two characters is
14061 encountered, and the first two characters of the name make a defined
14062 name.  The request or macro is not invoked.  When this warning is given,
14063 no macro is automatically defined.  This is enabled by default.  This
14064 warning never occurs in compatibility mode.
14066 @item font
14067 @itemx 131072
14068 Non-existent fonts.  This is enabled by default.
14070 @item ig
14071 @itemx 262144
14072 Invalid escapes in text ignored with the @code{ig} request.  These are
14073 conditions that are errors when they do not occur in ignored text.
14075 @item color
14076 @itemx 524288
14077 Color related warnings.
14079 @item all
14080 All warnings except @samp{di}, @samp{mac} and @samp{reg}.  It is
14081 intended that this covers all warnings that are useful with traditional
14082 macro packages.
14084 @item w
14085 All warnings.
14086 @end table
14089 @c =====================================================================
14091 @node Implementation Differences,  , Debugging, gtroff Reference
14092 @section Implementation Differences
14093 @cindex implementation differences
14094 @cindex differences in implementation
14095 @cindex incompatibilities with @acronym{AT&T} @code{troff}
14096 @cindex compatibility mode
14097 @cindex mode, compatibility
14099 GNU @code{troff} has a number of features which cause incompatibilities
14100 with documents written with old versions of @code{troff}.
14102 @cindex long names
14103 @cindex names, long
14104 Long names cause some incompatibilities.  @acronym{UNIX} @code{troff}
14105 interprets
14107 @Example
14108 .dsabcd
14109 @endExample
14111 @cindex @code{\*}, incompatibilities with @acronym{AT&T} @code{troff}
14112 @cindex @code{\n}, incompatibilities with @acronym{AT&T} @code{troff}
14113 @noindent
14114 as defining a string @samp{ab} with contents @samp{cd}.  Normally, GNU
14115 @code{troff} interprets this as a call of a macro named @code{dsabcd}.
14116 Also @acronym{UNIX} @code{troff} interprets @code{\*[} or @code{\n[} as
14117 references to a string or number register called @samp{[}.  In GNU
14118 @code{troff}, however, this is normally interpreted as the start of a
14119 long name.  In compatibility mode GNU @code{troff} interprets long names
14120 in the traditional way (which means that they are not recognized as
14121 names).
14123 @DefreqList {cp, [@Var{n}]}
14124 @DefreqItem {do, cmd}
14125 @DefregListEnd {.C}
14126 If @var{n} is missing or non-zero, turn on compatibility mode;
14127 otherwise, turn it off.
14129 The read-only number register @code{.C} is@tie{}1 if compatibility mode
14130 is on, 0@tie{}otherwise.
14132 Compatibility mode can be also turned on with the @option{-C} command
14133 line option.
14135 The @code{do} request turns off compatibility mode while executing its
14136 arguments as a @code{gtroff} command.  However, it does not turn off
14137 compatibility mode while processing the macro itself.  To do that, use
14138 the @code{de1} request (or manipulate the @code{.C} register manually).
14139 @xref{Writing Macros}.
14141 @Example
14142 .do fam T
14143 @endExample
14145 @noindent
14146 executes the @code{fam} request when compatibility mode is enabled.
14148 @code{gtroff} restores the previous compatibility setting before
14149 interpreting any files sourced by the @var{cmd}.
14150 @endDefreq
14152 @cindex input level in delimited arguments
14153 @cindex delimited arguments, incompatibilities with @acronym{AT&T} @code{troff}
14154 Two other features are controlled by @option{-C}.  If not in
14155 compatibility mode, GNU @code{troff} preserves the input level in
14156 delimited arguments:
14158 @Example
14159 .ds xx '
14160 \w'abc\*(xxdef'
14161 @endExample
14163 @noindent
14164 In compatibility mode, the string @samp{72def'} is returned; without
14165 @option{-C} the resulting string is @samp{168} (assuming a TTY output
14166 device).
14168 @cindex @code{\f}, incompatibilities with @acronym{AT&T} @code{troff}
14169 @cindex @code{\H}, incompatibilities with @acronym{AT&T} @code{troff}
14170 @cindex @code{\s}, incompatibilities with @acronym{AT&T} @code{troff}
14171 @cindex @code{\S}, incompatibilities with @acronym{AT&T} @code{troff}
14172 Finally, the escapes @code{\f}, @code{\H}, @code{\m}, @code{\M},
14173 @code{\R}, @code{\s}, and @code{\S} are transparent for recognizing the
14174 beginning of a line only in compatibility mode (this is a rather obscure
14175 feature).  For example, the code
14177 @Example
14178 .de xx
14179 Hallo!
14181 \fB.xx\fP
14182 @endExample
14184 @noindent
14185 prints @samp{Hallo!} in bold face if in compatibility mode, and
14186 @samp{.xx} in bold face otherwise.
14188 @cindex @code{\A}, incompatibilities with @acronym{AT&T} @code{troff}
14189 @cindex @code{\|}, incompatibilities with @acronym{AT&T} @code{troff}
14190 @cindex @code{\^}, incompatibilities with @acronym{AT&T} @code{troff}
14191 @cindex @code{\&}, incompatibilities with @acronym{AT&T} @code{troff}
14192 @cindex @code{\@{}, incompatibilities with @acronym{AT&T} @code{troff}
14193 @cindex @code{\@}}, incompatibilities with @acronym{AT&T} @code{troff}
14194 @cindex @code{\@key{SP}}, incompatibilities with @acronym{AT&T} @code{troff}
14195 @cindex @code{\'}, incompatibilities with @acronym{AT&T} @code{troff}
14196 @cindex @code{\`}, incompatibilities with @acronym{AT&T} @code{troff}
14197 @cindex @code{\-}, incompatibilities with @acronym{AT&T} @code{troff}
14198 @cindex @code{\_}, incompatibilities with @acronym{AT&T} @code{troff}
14199 @cindex @code{\!}, incompatibilities with @acronym{AT&T} @code{troff}
14200 @cindex @code{\%}, incompatibilities with @acronym{AT&T} @code{troff}
14201 @cindex @code{\c}, incompatibilities with @acronym{AT&T} @code{troff}
14202 GNU @code{troff} does not allow the use of the escape sequences
14203 @code{\|}, @code{\^}, @code{\&}, @code{\@{}, @code{\@}},
14204 @code{\@key{SP}}, @code{\'}, @code{\`}, @code{\-}, @code{\_}, @code{\!},
14205 @code{\%}, and @code{\c} in names of strings, macros, diversions, number
14206 registers, fonts or environments; @acronym{UNIX} @code{troff} does.  The
14207 @code{\A} escape sequence (@pxref{Identifiers}) may be helpful in
14208 avoiding use of these escape sequences in names.
14210 @cindex fractional point sizes
14211 @cindex fractional type sizes
14212 @cindex point sizes, fractional
14213 @cindex type sizes, fractional
14214 @cindex sizes, fractional
14215 @cindex @code{ps} request, incompatibilities with @acronym{AT&T} @code{troff}
14216 Fractional point sizes cause one noteworthy incompatibility.  In
14217 @acronym{UNIX} @code{troff} the @code{ps} request ignores scale
14218 indicators and thus
14220 @Example
14221 .ps 10u
14222 @endExample
14224 @noindent
14225 sets the point size to 10@tie{}points, whereas in GNU @code{troff} it
14226 sets the point size to 10@tie{}scaled points.  @xref{Fractional Type
14227 Sizes}, for more information.
14229 @cindex @code{bd} request, incompatibilities with @acronym{AT&T} @code{troff}
14230 @cindex @code{cs} request, incompatibilities with @acronym{AT&T} @code{troff}
14231 @cindex @code{tr} request, incompatibilities with @acronym{AT&T} @code{troff}
14232 @cindex @code{fp} request, incompatibilities with @acronym{AT&T} @code{troff}
14233 @cindex input characters and output glyphs, compatibility with @acronym{AT&T} @code{troff}
14234 @cindex output glyphs, and input characters,compatibility with @acronym{AT&T} @code{troff}
14235 @cindex characters, input, and output glyphs, compatibility with @acronym{AT&T} @code{troff}
14236 @cindex glyphs, output, and input characters, compatibility with @acronym{AT&T} @code{troff}
14237 In GNU @code{troff} there is a fundamental difference between
14238 (unformatted) input characters and (formatted) output glyphs.
14239 Everything that affects how a glyph is output is stored with the glyph
14240 node; once a glyph node has been constructed it is unaffected by any
14241 subsequent requests that are executed, including @code{bd}, @code{cs},
14242 @code{tkf}, @code{tr}, or @code{fp} requests.  Normally glyphs are
14243 constructed from input characters at the moment immediately before the
14244 glyph is added to the current output line.  Macros, diversions and
14245 strings are all, in fact, the same type of object; they contain lists of
14246 input characters and glyph nodes in any combination.  A glyph node does
14247 not behave like an input character for the purposes of macro processing;
14248 it does not inherit any of the special properties that the input
14249 character from which it was constructed might have had.  For example,
14251 @Example
14252 .di x
14253 \\\\
14257 @endExample
14259 @cindex printing backslash (@code{\\}, @code{\e}, @code{\E}, @code{\[rs]})
14260 @cindex backslash, printing (@code{\\}, @code{\e}, @code{\E}, @code{\[rs]})
14261 @cindex @code{\e}, incompatibilities with @acronym{AT&T} @code{troff}
14262 @cindex @code{\!}, incompatibilities with @acronym{AT&T} @code{troff}
14263 @cindex @code{\?}, incompatibilities with @acronym{AT&T} @code{troff}
14264 @cindex transparent output, incompatibilities with @acronym{AT&T} @code{troff}
14265 @cindex output, transparent, incompatibilities with @acronym{AT&T} @code{troff}
14266 @noindent
14267 prints @samp{\\} in GNU @code{troff}; each pair of input backslashes is
14268 turned into one output backslash and the resulting output backslashes
14269 are not interpreted as escape characters when they are reread.
14270 @acronym{UNIX} @code{troff} would interpret them as escape characters
14271 when they were reread and would end up printing one @samp{\}.  The
14272 correct way to obtain a printable backslash is to use the @code{\e}
14273 escape sequence: This always prints a single instance of the current
14274 escape character, regardless of whether or not it is used in a
14275 diversion; it also works in both GNU @code{troff} and @acronym{UNIX}
14276 @code{troff}.@footnote{To be completely independent of the current
14277 escape character, use @code{\(rs} which represents a reverse solidus
14278 (backslash) glyph.}  To store, for some reason, an escape sequence in a
14279 diversion that is interpreted when the diversion is reread, either use
14280 the traditional @code{\!} transparent output facility, or, if this is
14281 unsuitable, the new @code{\?} escape sequence.
14283 @xref{Diversions}, and @ref{Gtroff Internals}, for more information.
14287 @c =====================================================================
14288 @c =====================================================================
14290 @node Preprocessors, Output Devices, gtroff Reference, Top
14291 @chapter Preprocessors
14292 @cindex preprocessors
14294 This chapter describes all preprocessors that come with @code{groff} or
14295 which are freely available.
14297 @menu
14298 * geqn::
14299 * gtbl::
14300 * gpic::
14301 * ggrn::
14302 * grap::
14303 * grefer::
14304 * gsoelim::
14305 @end menu
14308 @c =====================================================================
14310 @node geqn, gtbl, Preprocessors, Preprocessors
14311 @section @code{geqn}
14312 @cindex @code{eqn}, the program
14313 @cindex @code{geqn}, the program
14315 @c XXX
14317 @menu
14318 * Invoking geqn::
14319 @end menu
14321 @c ---------------------------------------------------------------------
14323 @node Invoking geqn,  , geqn, geqn
14324 @subsection Invoking @code{geqn}
14325 @cindex invoking @code{geqn}
14326 @cindex @code{geqn}, invoking
14328 @c XXX
14331 @c =====================================================================
14333 @node gtbl, gpic, geqn, Preprocessors
14334 @section @code{gtbl}
14335 @cindex @code{tbl}, the program
14336 @cindex @code{gtbl}, the program
14338 @c XXX
14340 @menu
14341 * Invoking gtbl::
14342 @end menu
14344 @c ---------------------------------------------------------------------
14346 @node Invoking gtbl,  , gtbl, gtbl
14347 @subsection Invoking @code{gtbl}
14348 @cindex invoking @code{gtbl}
14349 @cindex @code{gtbl}, invoking
14351 @c XXX
14354 @c =====================================================================
14356 @node gpic, ggrn, gtbl, Preprocessors
14357 @section @code{gpic}
14358 @cindex @code{pic}, the program
14359 @cindex @code{gpic}, the program
14361 @c XXX
14363 @menu
14364 * Invoking gpic::
14365 @end menu
14367 @c ---------------------------------------------------------------------
14369 @node Invoking gpic,  , gpic, gpic
14370 @subsection Invoking @code{gpic}
14371 @cindex invoking @code{gpic}
14372 @cindex @code{gpic}, invoking
14374 @c XXX
14377 @c =====================================================================
14379 @node ggrn, grap, gpic, Preprocessors
14380 @section @code{ggrn}
14381 @cindex @code{grn}, the program
14382 @cindex @code{ggrn}, the program
14384 @c XXX
14386 @menu
14387 * Invoking ggrn::
14388 @end menu
14390 @c ---------------------------------------------------------------------
14392 @node Invoking ggrn,  , ggrn, ggrn
14393 @subsection Invoking @code{ggrn}
14394 @cindex invoking @code{ggrn}
14395 @cindex @code{ggrn}, invoking
14397 @c XXX
14400 @c =====================================================================
14402 @node grap, grefer, ggrn, Preprocessors
14403 @section @code{grap}
14404 @cindex @code{grap}, the program
14406 A free implementation of @code{grap}, written by Ted Faber,
14407 is available as an extra package from the following address:
14409 @display
14410 @uref{http://www.lunabase.org/~faber/Vault/software/grap/}
14411 @end display
14414 @c =====================================================================
14416 @node grefer, gsoelim, grap, Preprocessors
14417 @section @code{grefer}
14418 @cindex @code{refer}, the program
14419 @cindex @code{grefer}, the program
14421 @c XXX
14423 @menu
14424 * Invoking grefer::
14425 @end menu
14427 @c ---------------------------------------------------------------------
14429 @node Invoking grefer,  , grefer, grefer
14430 @subsection Invoking @code{grefer}
14431 @cindex invoking @code{grefer}
14432 @cindex @code{grefer}, invoking
14434 @c XXX
14437 @c =====================================================================
14439 @node gsoelim,  , grefer, Preprocessors
14440 @section @code{gsoelim}
14441 @cindex @code{soelim}, the program
14442 @cindex @code{gsoelim}, the program
14444 @c XXX
14446 @menu
14447 * Invoking gsoelim::
14448 @end menu
14450 @c ---------------------------------------------------------------------
14452 @node Invoking gsoelim,  , gsoelim, gsoelim
14453 @subsection Invoking @code{gsoelim}
14454 @cindex invoking @code{gsoelim}
14455 @cindex @code{gsoelim}, invoking
14457 @c XXX
14461 @c =====================================================================
14462 @c =====================================================================
14464 @node Output Devices, File formats, Preprocessors, Top
14465 @chapter Output Devices
14466 @cindex output devices
14467 @cindex devices for output
14469 @c XXX
14471 @menu
14472 * Special Characters::
14473 * grotty::
14474 * grops::
14475 * grodvi::
14476 * grolj4::
14477 * grolbp::
14478 * grohtml::
14479 * gxditview::
14480 @end menu
14483 @c =====================================================================
14485 @node Special Characters, grotty, Output Devices, Output Devices
14486 @section Special Characters
14487 @cindex special characters
14488 @cindex characters, special
14490 @c XXX
14492 @xref{Font Files}.
14495 @c =====================================================================
14497 @node grotty, grops, Special Characters, Output Devices
14498 @section @code{grotty}
14499 @cindex @code{grotty}, the program
14501 @c XXX
14503 @menu
14504 * Invoking grotty::
14505 @end menu
14507 @c ---------------------------------------------------------------------
14509 @node Invoking grotty,  , grotty, grotty
14510 @subsection Invoking @code{grotty}
14511 @cindex invoking @code{grotty}
14512 @cindex @code{grotty}, invoking
14514 @c XXX
14516 @c The following is no longer true; fix and extend it.
14518 @c @pindex less
14519 @c @cindex Teletype
14520 @c @cindex ISO 6249 SGR
14521 @c @cindex terminal control sequences
14522 @c @cindex control sequences, for terminals
14523 @c For TTY output devices, underlining is done by emitting sequences of
14524 @c @samp{_} and @samp{\b} (the backspace character) before the actual
14525 @c character.  Literally, this is printing an underline character, then
14526 @c moving back one character position, and printing the actual character
14527 @c at the same position as the underline character (similar to a
14528 @c typewriter).  Usually, a modern terminal can't interpret this (and
14529 @c the original Teletype machines for which this sequence was
14530 @c appropriate are no longer in use).  You need a pager program like
14531 @c @code{less} which translates this into ISO 6429 SGR sequences to
14532 @c control terminals.
14535 @c =====================================================================
14537 @node grops, grodvi, grotty, Output Devices
14538 @section @code{grops}
14539 @cindex @code{grops}, the program
14541 @c XXX
14543 @menu
14544 * Invoking grops::
14545 * Embedding PostScript::
14546 @end menu
14548 @c ---------------------------------------------------------------------
14550 @node Invoking grops, Embedding PostScript, grops, grops
14551 @subsection Invoking @code{grops}
14552 @cindex invoking @code{grops}
14553 @cindex @code{grops}, invoking
14555 @c XXX
14557 @c ---------------------------------------------------------------------
14559 @node Embedding PostScript,  , Invoking grops, grops
14560 @subsection Embedding @sc{PostScript}
14561 @cindex embedding PostScript
14562 @cindex PostScript, embedding
14564 @c XXX
14567 @c =====================================================================
14569 @node grodvi, grolj4, grops, Output Devices
14570 @section @code{grodvi}
14571 @cindex @code{grodvi}, the program
14573 @c XXX
14575 @menu
14576 * Invoking grodvi::
14577 @end menu
14579 @c ---------------------------------------------------------------------
14581 @node Invoking grodvi,  , grodvi, grodvi
14582 @subsection Invoking @code{grodvi}
14583 @cindex invoking @code{grodvi}
14584 @cindex @code{grodvi}, invoking
14586 @c XXX
14589 @c =====================================================================
14591 @node grolj4, grolbp, grodvi, Output Devices
14592 @section @code{grolj4}
14593 @cindex @code{grolj4}, the program
14595 @c XXX
14597 @menu
14598 * Invoking grolj4::
14599 @end menu
14601 @c ---------------------------------------------------------------------
14603 @node Invoking grolj4,  , grolj4, grolj4
14604 @subsection Invoking @code{grolj4}
14605 @cindex invoking @code{grolj4}
14606 @cindex @code{grolj4}, invoking
14608 @c XXX
14611 @c =====================================================================
14613 @node grolbp, grohtml, grolj4, Output Devices
14614 @section @code{grolbp}
14615 @cindex @code{grolbp}, the program
14617 @c XXX
14619 @menu
14620 * Invoking grolbp::
14621 @end menu
14623 @c ---------------------------------------------------------------------
14625 @node Invoking grolbp,  , grolbp, grolbp
14626 @subsection Invoking @code{grolbp}
14627 @cindex invoking @code{grolbp}
14628 @cindex @code{grolbp}, invoking
14630 @c XXX
14633 @c =====================================================================
14635 @node grohtml, gxditview, grolbp, Output Devices
14636 @section @code{grohtml}
14637 @cindex @code{grohtml}, the program
14639 @c XXX
14641 @menu
14642 * Invoking grohtml::
14643 * grohtml specific registers and strings::
14644 @end menu
14646 @c ---------------------------------------------------------------------
14648 @node Invoking grohtml, grohtml specific registers and strings, grohtml, grohtml
14649 @subsection Invoking @code{grohtml}
14650 @cindex invoking @code{grohtml}
14651 @cindex @code{grohtml}, invoking
14653 @c XXX
14655 @c ---------------------------------------------------------------------
14657 @node grohtml specific registers and strings,  , Invoking grohtml, grohtml
14658 @subsection @code{grohtml} specific registers and strings
14659 @cindex registers specific to @code{grohtml}
14660 @cindex strings specific to @code{grohtml}
14661 @cindex @code{grohtml}, registers and strings
14663 @DefmpregList {ps4html, grohtml}
14664 @DefstrListEnd {www-image-template, grohtml}
14665 The registers @code{ps4html} and @code{www-image-template} are defined
14666 by the @code{pre-grohtml} preprocessor.  @code{pre-grohtml} reads in the
14667 @code{troff} input, marks up the inline equations and passes the result
14668 firstly to
14670 @Example
14671 troff -Tps -rps4html=1 -dwww-image-template=@var{template}
14672 @endExample
14674 @noindent
14675 and secondly to
14677 @Example
14678 troff -Thtml
14679 @endExample
14681 @noindent
14684 @Example
14685 troff -Txhtml
14686 @endExample
14688 @cindex MathML
14689 The PostScript device is used to create all the image files (for
14690 @option{-Thtml}; if @option{-Txhtml} is used, all equations are passed
14691 to @code{geqn} to produce @acronym{MathML}, and the register
14692 @code{ps4html} enables the macro sets to ignore floating keeps, footers,
14693 and headings.
14695 The register @code{www-image-template} is set to the user specified
14696 template name or the default name.
14697 @endDefmpreg
14700 @c =====================================================================
14702 @node gxditview,  , grohtml, Output Devices
14703 @section @code{gxditview}
14704 @cindex @code{gxditview}, the program
14706 @c XXX
14708 @menu
14709 * Invoking gxditview::
14710 @end menu
14712 @c ---------------------------------------------------------------------
14714 @node Invoking gxditview,  , gxditview, gxditview
14715 @subsection Invoking @code{gxditview}
14716 @cindex invoking @code{gxditview}
14717 @cindex @code{gxditview}, invoking
14719 @c XXX
14720 @c X11's xditview
14724 @c =====================================================================
14725 @c =====================================================================
14727 @node File formats, Installation, Output Devices, Top
14728 @chapter File formats
14729 @cindex file formats
14730 @cindex formats, file
14732 All files read and written by @code{gtroff} are text files.  The
14733 following two sections describe their format.
14735 @menu
14736 * gtroff Output::
14737 * Font Files::
14738 @end menu
14741 @c =====================================================================
14743 @node gtroff Output, Font Files, File formats, File formats
14744 @section @code{gtroff} Output
14745 @cindex @code{gtroff}, output
14746 @cindex output, @code{gtroff}
14748 This section describes the intermediate output format of GNU
14749 @code{troff}.  This output is produced by a run of @code{gtroff} before
14750 it is fed into a device postprocessor program.
14752 As @code{groff} is a wrapper program around @code{gtroff} that
14753 automatically calls a postprocessor, this output does not show up
14754 normally.  This is why it is called @dfn{intermediate}.  @code{groff}
14755 provides the option @option{-Z} to inhibit postprocessing, such that the
14756 produced intermediate output is sent to standard output just like
14757 calling @code{gtroff} manually.
14759 @cindex troff output
14760 @cindex output, troff
14761 @cindex intermediate output
14762 @cindex output, intermediate
14763 Here, the term @dfn{troff output} describes what is output by
14764 @code{gtroff}, while @dfn{intermediate output} refers to the language
14765 that is accepted by the parser that prepares this output for the
14766 postprocessors.  This parser is smarter on whitespace and implements
14767 obsolete elements for compatibility, otherwise both formats are the
14768 same.@footnote{The parser and postprocessor for intermediate output can
14769 be found in the file@*
14770 @file{@var{groff-source-dir}/src/libs/libdriver/input.cpp}.}
14772 The main purpose of the intermediate output concept is to facilitate the
14773 development of postprocessors by providing a common programming
14774 interface for all devices.  It has a language of its own that is
14775 completely different from the @code{gtroff} language.  While the
14776 @code{gtroff} language is a high-level programming language for text
14777 processing, the intermediate output language is a kind of low-level
14778 assembler language by specifying all positions on the page for writing
14779 and drawing.
14781 The intermediate output produced by @code{gtroff} is fairly readable,
14782 while output from @acronym{AT&T} @code{troff} is rather hard to
14783 understand because of strange habits that are still supported, but not
14784 used any longer by @code{gtroff}.
14786 @menu
14787 * Language Concepts::
14788 * Command Reference::
14789 * Intermediate Output Examples::
14790 * Output Language Compatibility::
14791 @end menu
14793 @c ---------------------------------------------------------------------
14795 @node Language Concepts, Command Reference, gtroff Output, gtroff Output
14796 @subsection Language Concepts
14798 During the run of @code{gtroff}, the input data is cracked down to the
14799 information on what has to be printed at what position on the intended
14800 device.  So the language of the intermediate output format can be quite
14801 small.  Its only elements are commands with and without arguments.  In
14802 this section, the term @dfn{command} always refers to the intermediate
14803 output language, and never to the @code{gtroff} language used for
14804 document formatting.  There are commands for positioning and text
14805 writing, for drawing, and for device controlling.
14807 @menu
14808 * Separation::
14809 * Argument Units::
14810 * Document Parts::
14811 @end menu
14813 @node Separation, Argument Units, Language Concepts, Language Concepts
14814 @subsubsection Separation
14816 @acronym{AT&T} @code{troff} output has strange requirements on
14817 whitespace.  The @code{gtroff} output parser, however, is smart about
14818 whitespace by making it maximally optional.  The whitespace characters,
14819 i.e., the tab, space, and newline characters, always have a syntactical
14820 meaning.  They are never printable because spacing within the output is
14821 always done by positioning commands.
14823 Any sequence of space or tab characters is treated as a single
14824 @dfn{syntactical space}.  It separates commands and arguments, but is
14825 only required when there would occur a clashing between the command code
14826 and the arguments without the space.  Most often, this happens when
14827 variable-length command names, arguments, argument lists, or command
14828 clusters meet.  Commands and arguments with a known, fixed length need
14829 not be separated by syntactical space.
14831 A line break is a syntactical element, too.  Every command argument can
14832 be followed by whitespace, a comment, or a newline character.  Thus a
14833 @dfn{syntactical line break} is defined to consist of optional
14834 syntactical space that is optionally followed by a comment, and a
14835 newline character.
14837 The normal commands, those for positioning and text, consist of a single
14838 letter taking a fixed number of arguments.  For historical reasons, the
14839 parser allows to stack such commands on the same line, but fortunately,
14840 in @code{gtroff}'s intermediate output, every command with at least one
14841 argument is followed by a line break, thus providing excellent
14842 readability.
14844 The other commands -- those for drawing and device controlling -- have a
14845 more complicated structure; some recognize long command names, and some
14846 take a variable number of arguments.  So all @samp{D} and @samp{x}
14847 commands were designed to request a syntactical line break after their
14848 last argument.  Only one command, @w{@samp{x X}}, has an argument that
14849 can stretch over several lines; all other commands must have all of
14850 their arguments on the same line as the command, i.e., the arguments may
14851 not be split by a line break.
14853 Empty lines (these are lines containing only space and/or a comment),
14854 can occur everywhere.  They are just ignored.
14856 @node Argument Units, Document Parts, Separation, Language Concepts
14857 @subsubsection Argument Units
14859 Some commands take integer arguments that are assumed to represent
14860 values in a measurement unit, but the letter for the corresponding scale
14861 indicator is not written with the output command arguments.  Most
14862 commands assume the scale indicator @samp{u}, the basic unit of the
14863 device, some use @samp{z}, the scaled point unit of the device, while
14864 others, such as the color commands, expect plain integers.
14866 Note that single characters can have the eighth bit set, as can the
14867 names of fonts and special characters.  The names of characters and
14868 fonts can be of arbitrary length.  A character that is to be printed is
14869 always in the current font.
14871 A string argument is always terminated by the next whitespace character
14872 (space, tab, or newline); an embedded @samp{#} character is regarded as
14873 part of the argument, not as the beginning of a comment command.  An
14874 integer argument is already terminated by the next non-digit character,
14875 which then is regarded as the first character of the next argument or
14876 command.
14878 @node Document Parts,  , Argument Units, Language Concepts
14879 @subsubsection Document Parts
14881 A correct intermediate output document consists of two parts, the
14882 @dfn{prologue} and the @dfn{body}.
14884 The task of the prologue is to set the general device parameters using
14885 three exactly specified commands.  @code{gtroff}'s prologue is
14886 guaranteed to consist of the following three lines (in that order):
14888 @Example
14889 x T @var{device}
14890 x res @var{n} @var{h} @var{v}
14891 x init
14892 @endExample
14894 @noindent
14895 with the arguments set as outlined in @ref{Device Control Commands}.
14896 Note that the parser for the intermediate output format is able to
14897 swallow additional whitespace and comments as well even in the prologue.
14899 The body is the main section for processing the document data.
14900 Syntactically, it is a sequence of any commands different from the ones
14901 used in the prologue.  Processing is terminated as soon as the first
14902 @w{@samp{x stop}} command is encountered; the last line of any
14903 @code{gtroff} intermediate output always contains such a command.
14905 Semantically, the body is page oriented.  A new page is started by a
14906 @samp{p} command.  Positioning, writing, and drawing commands are always
14907 done within the current page, so they cannot occur before the first
14908 @samp{p} command.  Absolute positioning (by the @samp{H} and @samp{V}
14909 commands) is done relative to the current page; all other positioning is
14910 done relative to the current location within this page.
14912 @c ---------------------------------------------------------------------
14914 @node Command Reference, Intermediate Output Examples, Language Concepts, gtroff Output
14915 @subsection Command Reference
14917 This section describes all intermediate output commands, both from
14918 @acronym{AT&T} @code{troff} as well as the @code{gtroff} extensions.
14920 @menu
14921 * Comment Command::
14922 * Simple Commands::
14923 * Graphics Commands::
14924 * Device Control Commands::
14925 * Obsolete Command::
14926 @end menu
14928 @node Comment Command, Simple Commands, Command Reference, Command Reference
14929 @subsubsection Comment Command
14931 @table @code
14932 @item #@var{anything}@angles{end of line}
14933 A comment.  Ignore any characters from the @samp{#} character up to the
14934 next newline character.
14936 This command is the only possibility for commenting in the intermediate
14937 output.  Each comment can be preceded by arbitrary syntactical space;
14938 every command can be terminated by a comment.
14939 @end table
14941 @node Simple Commands, Graphics Commands, Comment Command, Command Reference
14942 @subsubsection Simple Commands
14944 The commands in this subsection have a command code consisting of a
14945 single character, taking a fixed number of arguments.  Most of them are
14946 commands for positioning and text writing.  These commands are smart
14947 about whitespace.  Optionally, syntactical space can be inserted before,
14948 after, and between the command letter and its arguments.  All of these
14949 commands are stackable, i.e., they can be preceded by other simple
14950 commands or followed by arbitrary other commands on the same line.  A
14951 separating syntactical space is only necessary when two integer
14952 arguments would clash or if the preceding argument ends with a string
14953 argument.
14955 @table @code
14956 @ignore
14957 .if (\n[@USE_ENV_STACK] == 1) \{\
14958 .command {
14959 Open a new environment by copying the actual device configuration data
14960 to the environment stack.
14962 The current environment is setup by the device specification and
14963 manipulated by the setting commands.
14966 .command }
14967 Close the actual environment (opened by a preceding
14968 .BR { \~command)
14969 and restore the previous environment from the environment
14970 stack as the actual device configuration data.
14972 \}              \" endif @USE_ENV_STACK
14973 @end ignore
14975 @item C @var{xxx}@angles{whitespace}
14976 Print a special character named @var{xxx}.  The trailing syntactical
14977 space or line break is necessary to allow glyph names of arbitrary
14978 length.  The glyph is printed at the current print position; the glyph's
14979 size is read from the font file.  The print position is not changed.
14981 @item c @var{g}
14982 Print glyph@tie{}@var{g} at the current print
14983 position;@footnote{@samp{c} is actually a misnomer since it outputs a
14984 glyph.} the glyph's size is read from the font file.  The print position
14985 is not changed.
14987 @item f @var{n}
14988 Set font to font number@tie{}@var{n} (a non-negative integer).
14990 @item H @var{n}
14991 Move right to the absolute vertical position@tie{}@var{n} (a
14992 non-negative integer in basic units @samp{u} relative to left edge of
14993 current page.
14995 @item h @var{n}
14996 Move @var{n} (a non-negative integer) basic units @samp{u} horizontally
14997 to the right.  The original @acronym{UNIX} troff manual allows negative
14998 values for @var{n} also, but @code{gtroff} doesn't use this.
15000 @item m @var{color-scheme} @r{[}@var{component} @dots{}@r{]}
15001 Set the color for text (glyphs), line drawing, and the outline of
15002 graphic objects using different color schemes; the analoguous command
15003 for the filling color of graphic objects is @samp{DF}.  The color
15004 components are specified as integer arguments between 0 and 65536.  The
15005 number of color components and their meaning vary for the different
15006 color schemes.  These commands are generated by @code{gtroff}'s escape
15007 sequence @code{\m}.  No position changing.  These commands are a
15008 @code{gtroff} extension.
15010 @table @code
15011 @item mc @var{cyan} @var{magenta} @var{yellow}
15012 Set color using the CMY color scheme, having the 3@tie{}color components
15013 @var{cyan}, @var{magenta}, and @var{yellow}.
15015 @item md
15016 Set color to the default color value (black in most cases).  No
15017 component arguments.
15019 @item mg @var{gray}
15020 Set color to the shade of gray given by the argument, an integer between
15021 0 (black) and 65536 (white).
15023 @item mk @var{cyan} @var{magenta} @var{yellow} @var{black}
15024 Set color using the CMYK color scheme, having the 4@tie{}color
15025 components @var{cyan}, @var{magenta}, @var{yellow}, and @var{black}.
15027 @item mr @var{red} @var{green} @var{blue}
15028 Set color using the RGB color scheme, having the 3@tie{}color components
15029 @var{red}, @var{green}, and @var{blue}.
15030 @end table
15032 @item N @var{n}
15033 Print glyph with index@tie{}@var{n} (a non-negative integer) of the
15034 current font.  This command is a @code{gtroff} extension.
15036 @item n @var{b} @var{a}
15037 Inform the device about a line break, but no positioning is done by this
15038 command.  In @acronym{AT&T} @code{troff}, the integer arguments @var{b}
15039 and@tie{}@var{a} informed about the space before and after the current
15040 line to make the intermediate output more human readable without
15041 performing any action.  In @code{groff}, they are just ignored, but they
15042 must be provided for compatibility reasons.
15044 @item p @var{n}
15045 Begin a new page in the outprint.  The page number is set
15046 to@tie{}@var{n}.  This page is completely independent of pages formerly
15047 processed even if those have the same page number.  The vertical
15048 position on the outprint is automatically set to@tie{}0.  All
15049 positioning, writing, and drawing is always done relative to a page, so
15050 a @samp{p} command must be issued before any of these commands.
15052 @item s @var{n}
15053 Set point size to @var{n}@tie{}scaled points (this is unit @samp{z}).
15054 @acronym{AT&T} @code{troff} used the unit points (@samp{p}) instead.
15055 @xref{Output Language Compatibility}.
15057 @item t @var{xxx}@angles{whitespace}
15058 @itemx t @var{xxx} @var{dummy-arg}@angles{whitespace}
15059 Print a word, i.e., a sequence of characters @var{xxx} representing
15060 output glyphs which names are single characters, terminated by a space
15061 character or a line break; an optional second integer argument is
15062 ignored (this allows the formatter to generate an even number of
15063 arguments).  The first glyph should be printed at the current position,
15064 the current horizontal position should then be increased by the width of
15065 the first glyph, and so on for each glyph.  The widths of the glyphs are
15066 read from the font file, scaled for the current point size, and rounded
15067 to a multiple of the horizontal resolution.  Special characters cannot
15068 be printed using this command (use the @samp{C} command for special
15069 characters).  This command is a @code{gtroff} extension; it is only used
15070 for devices whose @file{DESC} file contains the @code{tcommand} keyword
15071 (@pxref{DESC File Format}).
15073 @item u @var{n} @var{xxx}@angles{whitespace}
15074 Print word with track kerning.  This is the same as the @samp{t} command
15075 except that after printing each glyph, the current horizontal position
15076 is increased by the sum of the width of that glyph and@tie{}@var{n} (an
15077 integer in basic units @samp{u}).  This command is a @code{gtroff}
15078 extension; it is only used for devices whose @file{DESC} file contains
15079 the @code{tcommand} keyword (@pxref{DESC File Format}).
15081 @item V @var{n}
15082 Move down to the absolute vertical position@tie{}@var{n} (a non-negative
15083 integer in basic units @samp{u}) relative to upper edge of current page.
15085 @item v @var{n}
15086 Move @var{n}@tie{}basic units @samp{u} down (@var{n} is a non-negative
15087 integer).  The original @acronym{UNIX} troff manual allows negative
15088 values for @var{n} also, but @code{gtroff} doesn't use this.
15090 @item w
15091 Informs about a paddable white space to increase readability.  The
15092 spacing itself must be performed explicitly by a move command.
15093 @end table
15095 @node Graphics Commands, Device Control Commands, Simple Commands, Command Reference
15096 @subsubsection Graphics Commands
15098 Each graphics or drawing command in the intermediate output starts with
15099 the letter @samp{D}, followed by one or two characters that specify a
15100 subcommand; this is followed by a fixed or variable number of integer
15101 arguments that are separated by a single space character.  A @samp{D}
15102 command may not be followed by another command on the same line (apart
15103 from a comment), so each @samp{D} command is terminated by a syntactical
15104 line break.
15106 @code{gtroff} output follows the classical spacing rules (no space
15107 between command and subcommand, all arguments are preceded by a single
15108 space character), but the parser allows optional space between the
15109 command letters and makes the space before the first argument optional.
15110 As usual, each space can be any sequence of tab and space characters.
15112 Some graphics commands can take a variable number of arguments.  In this
15113 case, they are integers representing a size measured in basic units
15114 @samp{u}.  The arguments called @var{h1}, @var{h2}, @dots{}, @var{hn}
15115 stand for horizontal distances where positive means right, negative
15116 left.  The arguments called @var{v1}, @var{v2}, @dots{}, @var{vn} stand
15117 for vertical distances where positive means down, negative up.  All
15118 these distances are offsets relative to the current location.
15120 Each graphics command directly corresponds to a similar @code{gtroff}
15121 @code{\D} escape sequence.  @xref{Drawing Requests}.
15123 Unknown @samp{D} commands are assumed to be device-specific.  Its
15124 arguments are parsed as strings; the whole information is then sent to
15125 the postprocessor.
15127 In the following command reference, the syntax element @angles{line
15128 break} means a syntactical line break as defined above.
15130 @table @code
15131 @item D~ @var{h1} @var{v1} @var{h2} @var{v2} @dots{} @var{hn} @var{vn}@angles{line break}
15132 Draw B-spline from current position to offset (@var{h1},@var{v1}), then
15133 to offset (@var{h2},@var{v2}), if given, etc.@: up to
15134 (@var{hn},@var{vn}).  This command takes a variable number of argument
15135 pairs; the current position is moved to the terminal point of the drawn
15136 curve.
15138 @item Da @var{h1} @var{v1} @var{h2} @var{v2}@angles{line break}
15139 Draw arc from current position to
15140 (@var{h1},@var{v1})@math{+}(@var{h2},@var{v2}) with center at
15141 (@var{h1},@var{v1}); then move the current position to the final point
15142 of the arc.
15144 @item DC @var{d}@angles{line break}
15145 @itemx DC @var{d} @var{dummy-arg}@angles{line break}
15146 Draw a solid circle using the current fill color with
15147 diameter@tie{}@var{d} (integer in basic units @samp{u}) with leftmost
15148 point at the current position; then move the current position to the
15149 rightmost point of the circle.  An optional second integer argument is
15150 ignored (this allows the formatter to generate an even number of
15151 arguments).  This command is a @code{gtroff} extension.
15153 @item Dc @var{d}@angles{line break}
15154 Draw circle line with diameter@tie{}@var{d} (integer in basic units
15155 @samp{u}) with leftmost point at the current position; then move the
15156 current position to the rightmost point of the circle.
15158 @item DE @var{h} @var{v}@angles{line break}
15159 Draw a solid ellipse in the current fill color with a horizontal
15160 diameter of@tie{}@var{h} and a vertical diameter of@tie{}@var{v} (both
15161 integers in basic units @samp{u}) with the leftmost point at the current
15162 position; then move to the rightmost point of the ellipse.  This command
15163 is a @code{gtroff} extension.
15165 @item De @var{h} @var{v}@angles{line break}
15166 Draw an outlined ellipse with a horizontal diameter of@tie{}@var{h} and
15167 a vertical diameter of@tie{}@var{v} (both integers in basic units
15168 @samp{u}) with the leftmost point at current position; then move to the
15169 rightmost point of the ellipse.
15171 @item DF @var{color-scheme} @r{[}@var{component} @dots{}@r{]}@angles{line break}
15172 Set fill color for solid drawing objects using different color schemes;
15173 the analoguous command for setting the color of text, line graphics, and
15174 the outline of graphic objects is @samp{m}.  The color components are
15175 specified as integer arguments between 0 and 65536.  The number of color
15176 components and their meaning vary for the different color schemes.
15177 These commands are generated by @code{gtroff}'s escape sequences
15178 @w{@code{\D'F @dots{}'}} and @code{\M} (with no other corresponding
15179 graphics commands).  No position changing.  This command is a
15180 @code{gtroff} extension.
15182 @table @code
15183 @item DFc @var{cyan} @var{magenta} @var{yellow}@angles{line break}
15184 Set fill color for solid drawing objects using the CMY color scheme,
15185 having the 3@tie{}color components @var{cyan}, @var{magenta}, and
15186 @var{yellow}.
15188 @item DFd@angles{line break}
15189 Set fill color for solid drawing objects to the default fill color value
15190 (black in most cases).  No component arguments.
15192 @item DFg @var{gray}@angles{line break}
15193 Set fill color for solid drawing objects to the shade of gray given by
15194 the argument, an integer between 0 (black) and 65536 (white).
15196 @item DFk @var{cyan} @var{magenta} @var{yellow} @var{black}@angles{line break}
15197 Set fill color for solid drawing objects using the CMYK color scheme,
15198 having the 4@tie{}color components @var{cyan}, @var{magenta},
15199 @var{yellow}, and @var{black}.
15201 @item DFr @var{red} @var{green} @var{blue}@angles{line break}
15202 Set fill color for solid drawing objects using the RGB color scheme,
15203 having the 3@tie{}color components @var{red}, @var{green}, and
15204 @var{blue}.
15205 @end table
15207 @item Df @var{n}@angles{line break}
15208 The argument@tie{}@var{n} must be an integer in the range @math{-32767}
15209 to 32767.
15211 @table @asis
15212 @item @math{0 @LE{} @var{n} @LE{} 1000}
15213 Set the color for filling solid drawing objects to a shade of gray,
15214 where 0 corresponds to solid white, 1000 (the default) to solid black,
15215 and values in between to intermediate shades of gray; this is obsoleted
15216 by command @samp{DFg}.
15218 @item @math{@var{n} < 0} or @math{@var{n} > 1000}
15219 Set the filling color to the color that is currently being used for the
15220 text and the outline, see command @samp{m}.  For example, the command
15221 sequence
15223 @Example
15224 mg 0 0 65536
15225 Df -1
15226 @endExample
15228 @noindent
15229 sets all colors to blue.
15230 @end table
15232 @noindent
15233 No position changing.  This command is a @code{gtroff} extension.
15235 @item Dl @var{h} @var{v}@angles{line break}
15236 Draw line from current position to offset (@var{h},@var{v}) (integers in
15237 basic units @samp{u}); then set current position to the end of the drawn
15238 line.
15240 @item Dp @var{h1} @var{v1} @var{h2} @var{v2} @dots{} @var{hn} @var{vn}@angles{line break}
15241 Draw a polygon line from current position to offset (@var{h1},@var{v1}),
15242 from there to offset (@var{h2},@var{v2}), etc.@: up to offset
15243 (@var{hn},@var{vn}), and from there back to the starting position.  For
15244 historical reasons, the position is changed by adding the sum of all
15245 arguments with odd index to the actual horizontal position and the even
15246 ones to the vertical position.  Although this doesn't make sense it is
15247 kept for compatibility.
15248 @ignore
15249 As the polygon is closed, the end of drawing is the starting point, so
15250 the position doesn't change.
15251 @end ignore
15252 This command is a @code{gtroff} extension.
15254 @item Dp @var{h1} @var{v1} @var{h2} @var{v2} @dots{} @var{hn} @var{vn}@angles{line break}
15255 Draw a solid polygon in the current fill color rather than an outlined
15256 polygon, using the same arguments and positioning as the corresponding
15257 @samp{Dp} command.
15258 @ignore
15259 No position changing.
15260 @end ignore
15261 This command is a @code{gtroff} extension.
15263 @item Dt @var{n}@angles{line break}
15264 Set the current line thickness to@tie{}@var{n} (an integer in basic
15265 units @samp{u}) if @math{@var{n}>0}; if @math{@var{n}=0} select the
15266 smallest available line thickness; if @math{@var{n}<0} set the line
15267 thickness proportional to the point size (this is the default before the
15268 first @samp{Dt} command was specified).  For historical reasons, the
15269 horizontal position is changed by adding the argument to the actual
15270 horizontal position, while the vertical position is not changed.
15271 Although this doesn't make sense it is kept for compatibility.
15272 @ignore
15273 No position changing.
15274 @end ignore
15275 This command is a @code{gtroff} extension.
15276 @end table
15278 @node Device Control Commands, Obsolete Command, Graphics Commands, Command Reference
15279 @subsubsection Device Control Commands
15281 Each device control command starts with the letter @samp{x}, followed by
15282 a space character (optional or arbitrary space or tab in @code{gtroff})
15283 and a subcommand letter or word; each argument (if any) must be preceded
15284 by a syntactical space.  All @samp{x} commands are terminated by a
15285 syntactical line break; no device control command can be followed by
15286 another command on the same line (except a comment).
15288 The subcommand is basically a single letter, but to increase
15289 readability, it can be written as a word, i.e., an arbitrary sequence of
15290 characters terminated by the next tab, space, or newline character.  All
15291 characters of the subcommand word but the first are simply ignored.  For
15292 example, @code{gtroff} outputs the initialization command @w{@samp{x i}}
15293 as @w{@samp{x init}} and the resolution command @w{@samp{x r}} as
15294 @w{@samp{x res}}.
15296 In the following, the syntax element @angles{line break} means a
15297 syntactical line break (@pxref{Separation}).
15299 @table @code
15300 @item xF @var{name}@angles{line break}
15301 The @samp{F} stands for @var{Filename}.
15303 Use @var{name} as the intended name for the current file in error
15304 reports.  This is useful for remembering the original file name when
15305 @code{gtroff} uses an internal piping mechanism.  The input file is not
15306 changed by this command.  This command is a @code{gtroff} extension.
15308 @item xf @var{n} @var{s}@angles{line break}
15309 The @samp{f} stands for @var{font}.
15311 Mount font position@tie{}@var{n} (a non-negative integer) with font
15312 named@tie{}@var{s} (a text word).  @xref{Font Positions}.
15314 @item xH @var{n}@angles{line break}
15315 The @samp{H} stands for @var{Height}.
15317 Set glyph height to@tie{}@var{n} (a positive integer in scaled points
15318 @samp{z}).  @acronym{AT&T} @code{troff} uses the unit points (@samp{p})
15319 instead.  @xref{Output Language Compatibility}.
15321 @item xi@angles{line break}
15322 The @samp{i} stands for @var{init}.
15324 Initialize device.  This is the third command of the prologue.
15326 @item xp@angles{line break}
15327 The @samp{p} stands for @var{pause}.
15329 Parsed but ignored.  The original @acronym{UNIX} troff manual writes
15331 @display
15332 pause device, can be restarted
15333 @end display
15335 @item xr @var{n} @var{h} @var{v}@angles{line break}
15336 The @samp{r} stands for @var{resolution}.
15338 Resolution is@tie{}@var{n}, while @var{h} is the minimal horizontal
15339 motion, and @var{v} the minimal vertical motion possible with this
15340 device; all arguments are positive integers in basic units @samp{u} per
15341 inch.  This is the second command of the prologue.
15343 @item xS @var{n}@angles{line break}
15344 The @samp{S} stands for @var{Slant}.
15346 Set slant to@tie{}@var{n} (an integer in basic units @samp{u}).
15348 @item xs@angles{line break}
15349 The @samp{s} stands for @var{stop}.
15351 Terminates the processing of the current file; issued as the last
15352 command of any intermediate troff output.
15354 @item xt@angles{line break}
15355 The @samp{t} stands for @var{trailer}.
15357 Generate trailer information, if any.  In @var{gtroff}, this is actually
15358 just ignored.
15360 @item xT @var{xxx}@angles{line break}
15361 The @samp{T} stands for @var{Typesetter}.
15363 Set name of device to word @var{xxx}, a sequence of characters ended by
15364 the next white space character.  The possible device names coincide with
15365 those from the @code{groff} @option{-T} option.  This is the first
15366 command of the prologue.
15368 @item xu @var{n}@angles{line break}
15369 The @samp{u} stands for @var{underline}.
15371 Configure underlining of spaces.  If @var{n} is@tie{}1, start
15372 underlining of spaces; if @var{n} is@tie{}0, stop underlining of spaces.
15373 This is needed for the @code{cu} request in nroff mode and is ignored
15374 otherwise.  This command is a @code{gtroff} extension.
15376 @item xX @var{anything}@angles{line break}
15377 The @samp{x} stands for @var{X-escape}.
15379 Send string @var{anything} uninterpreted to the device.  If the line
15380 following this command starts with a @samp{+} character this line is
15381 interpreted as a continuation line in the following sense.  The @samp{+}
15382 is ignored, but a newline character is sent instead to the device, the
15383 rest of the line is sent uninterpreted.  The same applies to all
15384 following lines until the first character of a line is not a @samp{+}
15385 character.  This command is generated by the @code{gtroff} escape
15386 sequence @code{\X}.  The line-continuing feature is a @code{gtroff}
15387 extension.
15388 @end table
15390 @node Obsolete Command,  , Device Control Commands, Command Reference
15391 @subsubsection Obsolete Command
15392 In @acronym{AT&T} @code{troff} output, the writing of a single glyph is
15393 mostly done by a very strange command that combines a horizontal move
15394 and a single character giving the glyph name.  It doesn't have a command
15395 code, but is represented by a 3-character argument consisting of exactly
15396 2@tie{}digits and a character.
15398 @table @asis
15399 @item @var{dd}@var{g}
15400 Move right @var{dd} (exactly two decimal digits) basic units @samp{u},
15401 then print glyph@tie{}@var{g} (represented as a single character).
15403 In @code{gtroff}, arbitrary syntactical space around and within this
15404 command is allowed to be added.  Only when a preceding command on the
15405 same line ends with an argument of variable length a separating space is
15406 obligatory.  In @acronym{AT&T} @code{troff}, large clusters of these and
15407 other commands are used, mostly without spaces; this made such output
15408 almost unreadable.
15409 @end table
15411 For modern high-resolution devices, this command does not make sense
15412 because the width of the glyphs can become much larger than two decimal
15413 digits.  In @code{gtroff}, this is only used for the devices @code{X75},
15414 @code{X75-12}, @code{X100}, and @code{X100-12}.  For other devices, the
15415 commands @samp{t} and @samp{u} provide a better functionality.
15417 @c ---------------------------------------------------------------------
15419 @node Intermediate Output Examples, Output Language Compatibility, Command Reference, gtroff Output
15420 @subsection Intermediate Output Examples
15422 This section presents the intermediate output generated from the same
15423 input for three different devices.  The input is the sentence @samp{hell
15424 world} fed into @code{gtroff} on the command line.
15426 @table @asis
15427 @item High-resolution device @code{ps}
15429 This is the standard output of @code{gtroff} if no @option{-T} option is
15430 given.
15432 @example
15433 @group
15434 shell> echo "hell world" | groff -Z -T ps
15436 x T ps
15437 x res 72000 1 1
15438 x init
15439 @end group
15441 x font 5 TR
15443 s10000
15444 V12000
15445 H72000
15446 thell
15447 wh2500
15449 H96620
15450 torld
15451 n12000 0
15452 @group
15453 x trailer
15454 V792000
15455 x stop
15456 @end group
15457 @end example
15459 @noindent
15460 This output can be fed into @code{grops} to get its representation as a
15461 PostScript file.
15463 @item Low-resolution device @code{latin1}
15465 This is similar to the high-resolution device except that the
15466 positioning is done at a minor scale.  Some comments (lines starting
15467 with @samp{#}) were added for clarification; they were not generated by
15468 the formatter.
15470 @example
15471 @group
15472 shell> echo "hell world" | groff -Z -T latin1
15474 # prologue
15475 x T latin1
15476 x res 240 24 40
15477 x init
15478 @end group
15479 # begin a new page
15481 # font setup
15482 x font 1 R
15485 # initial positioning on the page
15488 # write text `hell'
15489 thell
15490 # inform about space, and issue a horizontal jump
15491 wh24
15492 # write text `world'
15493 tworld
15494 # announce line break, but do nothing because ...
15495 n40 0
15496 @group
15497 # ... the end of the document has been reached
15498 x trailer
15499 V2640
15500 x stop
15501 @end group
15502 @end example
15504 @noindent
15505 This output can be fed into @code{grotty} to get a formatted text
15506 document.
15508 @item @acronym{AT&T} @code{troff} output
15509 Since a computer monitor has a very low resolution compared to modern
15510 printers the intermediate output for the X@tie{}Window devices can use
15511 the jump-and-write command with its 2-digit displacements.
15513 @example
15514 @group
15515 shell> echo "hell world" | groff -Z -T X100
15517 x T X100
15518 x res 100 1 1
15519 x init
15520 @end group
15522 x font 5 TR
15526 H100
15527 # write text with jump-and-write commands
15528 ch07e07l03lw06w11o07r05l03dh7
15529 n16 0
15530 @group
15531 x trailer
15532 V1100
15533 x stop
15534 @end group
15535 @end example
15537 @noindent
15538 This output can be fed into @code{xditview} or @code{gxditview} for
15539 displaying in@tie{}X.
15541 Due to the obsolete jump-and-write command, the text clusters in the
15542 @acronym{AT&T} @code{troff} output are almost unreadable.
15543 @end table
15545 @c ---------------------------------------------------------------------
15547 @node Output Language Compatibility,  , Intermediate Output Examples, gtroff Output
15548 @subsection Output Language Compatibility
15550 The intermediate output language of @acronym{AT&T} @code{troff} was
15551 first documented in the @acronym{UNIX} troff manual, with later
15552 additions documented in @cite{A Typesetter-indenpendent TROFF}, written
15553 by Brian Kernighan.
15555 The @code{gtroff} intermediate output format is compatible with this
15556 specification except for the following features.
15558 @itemize @bullet
15559 @item
15560 The classical quasi device independence is not yet implemented.
15562 @item
15563 The old hardware was very different from what we use today.  So the
15564 @code{groff} devices are also fundamentally different from the ones in
15565 @acronym{AT&T} @code{troff}.  For example, the @acronym{AT&T} PostScript
15566 device is called @code{post} and has a resolution of only 720 units per
15567 inch, suitable for printers 20 years ago, while @code{groff}'s @code{ps}
15568 device has a resolution of 72000 units per inch.  Maybe, by implementing
15569 some rescaling mechanism similar to the classical quasi device
15570 independence, @code{groff} could emulate @acronym{AT&T}'s @code{post}
15571 device.
15573 @item
15574 The B-spline command @samp{D~} is correctly handled by the intermediate
15575 output parser, but the drawing routines aren't implemented in some of
15576 the postprocessor programs.
15578 @item
15579 The argument of the commands @samp{s} and @w{@samp{x H}} has the
15580 implicit unit scaled point @samp{z} in @code{gtroff}, while
15581 @acronym{AT&T} @code{troff} has point (@samp{p}).  This isn't an
15582 incompatibility but a compatible extension, for both units coincide for
15583 all devices without a @code{sizescale} parameter in the @file{DESC}
15584 file, including all postprocessors from @acronym{AT&T} and
15585 @code{groff}'s text devices.  The few @code{groff} devices with a
15586 @code{sizescale} parameter either do not exist for @acronym{AT&T}
15587 @code{troff}, have a different name, or seem to have a different
15588 resolution.  So conflicts are very unlikely.
15590 @item
15591 The position changing after the commands @samp{Dp}, @samp{DP}, and
15592 @samp{Dt} is illogical, but as old versions of @code{gtroff} used this
15593 feature it is kept for compatibility reasons.
15595 @ignore
15596 Temporarily, there existed some confusion on the positioning after the
15597 @samp{D} commands that are groff extensions.  This has been clarified by
15598 establishing the classical rule for all @code{groff} drawing commands:
15600 @itemize
15601 @item
15602 The position after a graphic object has been drawn is at its end; for
15603 circles and ellipses, the `end' is at the right side.
15605 @item
15606 From this, the positionings specified for the drawing commands above
15607 follow quite naturally.
15608 @end itemize
15609 @end ignore
15611 @end itemize
15614 @c =====================================================================
15616 @node Font Files,  , gtroff Output, File formats
15617 @section Font Files
15618 @cindex font files
15619 @cindex files, font
15621 The @code{gtroff} font format is roughly a superset of the
15622 @code{ditroff} font format (as used in later versions of @acronym{AT&T}
15623 @code{troff} and its descendants).  Unlike the @code{ditroff} font
15624 format, there is no associated binary format; all files are text
15625 files.@footnote{Plan@tie{}9 @code{troff} has also abandoned the binary
15626 format.}  The font files for device @var{name} are stored in a directory
15627 @file{dev@var{name}}.  There are two types of file: a device description
15628 file called @file{DESC} and for each font@tie{}@var{f} a font file
15629 called@tie{}@file{@var{f}}.
15631 @menu
15632 * DESC File Format::
15633 * Font File Format::
15634 @end menu
15636 @c ---------------------------------------------------------------------
15638 @node DESC File Format, Font File Format, Font Files, Font Files
15639 @subsection @file{DESC} File Format
15640 @cindex @file{DESC} file, format
15641 @cindex font description file, format
15642 @cindex format of font description file
15643 @pindex DESC@r{ file format}
15645 The @file{DESC} file can contain the following types of line.  Except
15646 for the @code{charset} keyword which must comes last (if at all), the
15647 order of the lines is not important.  Later entries in the file,
15648 however, override previous values.
15650 @table @code
15651 @item charset
15652 @kindex charset
15653 This line and everything following in the file are ignored.  It is
15654 allowed for the sake of backwards compatibility.
15656 @item family @var{fam}
15657 @kindex family
15658 The default font family is @var{fam}.
15660 @item fonts @var{n} @var{F1} @var{F2} @var{F3} @dots{} @var{Fn}
15661 @kindex fonts
15662 Fonts @var{F1} @dots{} @var{Fn} are mounted in the font positions
15663 @var{m}+1, @dots{}, @var{m}+@var{n} where @var{m} is the number of
15664 styles.  This command may extend over more than one line.  A font name
15665 of@tie{}0 means no font is mounted on the corresponding font position.
15667 @item hor @var{n}
15668 @kindex hor
15669 @cindex horizontal resolution
15670 @cindex resolution, horizontal
15671 The horizontal resolution is @var{n}@tie{}machine units.  All horizontal
15672 quantities are rounded to be multiples of this value.
15674 @item image_generator @var{string}
15675 @kindex image_generator
15676 @cindex PostScript, PNG image generation
15677 @cindex PNG image generation from PostScript
15678 Needed for @code{grohtml} only.  It specifies the program to generate
15679 PNG images from PostScript input.  Under GNU/Linux this is usually
15680 @code{gs} but under other systems (notably cygwin) it might be set to
15681 another name.
15683 @item paperlength @var{n}
15684 @kindex paperlength
15685 The physical vertical dimension of the output medium in machine units.
15686 This isn't used by @code{troff} itself but by output devices.
15687 Deprecated.  Use @code{papersize} instead.
15689 @item papersize @var{string} @dots{}
15690 @kindex papersize
15691 Select a paper size.  Valid values for @var{string} are the ISO paper
15692 types @code{A0}-@code{A7}, @code{B0}-@code{B7}, @code{C0}-@code{C7},
15693 @code{D0}-@code{D7}, @code{DL}, and the US paper types @code{letter},
15694 @code{legal}, @code{tabloid}, @code{ledger}, @code{statement},
15695 @code{executive}, @code{com10}, and @code{monarch}.  Case is not
15696 significant for @var{string} if it holds predefined paper types.
15697 Alternatively, @var{string} can be a file name (e.g.@:
15698 @file{/etc/papersize}); if the file can be opened, @code{groff} reads
15699 the first line and tests for the above paper sizes.  Finally,
15700 @var{string} can be a custom paper size in the format
15701 @code{@var{length},@var{width}} (no spaces before and after the comma).
15702 Both @var{length} and @var{width} must have a unit appended; valid
15703 values are @samp{i} for inches, @samp{C} for centimeters, @samp{p} for
15704 points, and @samp{P} for picas.  Example: @code{12c,235p}.  An argument
15705 which starts with a digit is always treated as a custom paper format.
15706 @code{papersize} sets both the vertical and horizontal dimension of the
15707 output medium.
15709 More than one argument can be specified; @code{groff} scans from left to
15710 right and uses the first valid paper specification.
15712 @item paperwidth @var{n}
15713 @kindex paperwidth
15714 The physical horizontal dimension of the output medium in machine units.
15715 This isn't used by @code{troff} itself but by output devices.
15716 Deprecated.  Use @code{papersize} instead.
15718 @item pass_filenames
15719 @kindex pass_filenames
15720 Tell @code{gtroff} to emit the name of the source file currently being
15721 processed.  This is achieved by the intermediate output command
15722 @samp{F}.  Currently, this is only used by the @code{grohtml} output
15723 device.
15725 @item postpro @var{program}
15726 @kindex postpro
15727 Call @var{program} as a postprocessor.  For example, the line
15729 @Example
15730 postpro grodvi
15731 @endExample
15733 @noindent
15734 in the file @file{devdvi/DESC} makes @code{groff} call @code{grodvi} if
15735 option @option{-Tdvi} is given (and @option{-Z} isn't used).
15737 @item prepro @var{program}
15738 @kindex prepro
15739 Call @var{program} as a preprocessor.  Currently, this keyword is used
15740 by @code{groff} with option @option{-Thtml} or @option{-Txhtml} only.
15742 @item print @var{program}
15743 @kindex print
15744 Use @var{program} as a spooler program for printing.  If omitted, the
15745 @option{-l} and @option{-L} options of @code{groff} are ignored.
15747 @item res @var{n}
15748 @kindex res
15749 @cindex device resolution
15750 @cindex resolution, device
15751 There are @var{n}@tie{}machine units per inch.
15753 @item sizes @var{s1} @var{s2} @dots{} @var{sn} 0
15754 @kindex sizes
15755 This means that the device has fonts at @var{s1}, @var{s2}, @dots{}
15756 @var{sn} scaled points.  The list of sizes must be terminated by@tie{}0
15757 (this is digit zero).  Each @var{si} can also be a range of sizes
15758 @var{m}-@var{n}.  The list can extend over more than one line.
15760 @item sizescale @var{n}
15761 @kindex sizescale
15762 The scale factor for point sizes.  By default this has a value
15763 of@tie{}1.  One scaled point is equal to one point/@var{n}.  The
15764 arguments to the @code{unitwidth} and @code{sizes} commands are given in
15765 scaled points.  @xref{Fractional Type Sizes}, for more information.
15767 @item styles @var{S1} @var{S2} @dots{} @var{Sm}
15768 @kindex styles
15769 The first @var{m}@tie{}font positions are associated with styles
15770 @var{S1} @dots{} @var{Sm}.
15772 @item tcommand
15773 @kindex tcommand
15774 This means that the postprocessor can handle the @samp{t} and @samp{u}
15775 intermediate output commands.
15777 @item unicode
15778 @kindex unicode
15779 Indicate that the output device supports the complete Unicode
15780 repertoire.  Useful only for devices which produce @emph{character
15781 entities} instead of glyphs.
15783 If @code{unicode} is present, no @code{charset} section is required in
15784 the font description files since the Unicode handling built into
15785 @code{groff} is used.  However, if there are entries in a @code{charset}
15786 section, they either override the default mappings for those particular
15787 characters or add new mappings (normally for composite characters).
15789 This is used for @option{-Tutf8}, @option{-Thtml}, and @option{-Txhtml}.
15791 @item unitwidth @var{n}
15792 @kindex unitwidth
15793 Quantities in the font files are given in machine units for fonts whose
15794 point size is @var{n}@tie{}scaled points.
15796 @item unscaled_charwidths
15797 @kindex unscaled_charwidths
15798 Make the font handling module always return unscaled character widths.
15799 Needed for the @code{grohtml} device.
15800 @item use_charnames_in_special
15801 @kindex use_charnames_in_special
15802 This command indicates that @code{gtroff} should encode special
15803 characters inside special commands.  Currently, this is only used by the
15804 @code{grohtml} output device.  @xref{Postprocessor Access}.
15806 @item vert @var{n}
15807 @kindex vert
15808 @cindex vertical resolution
15809 @cindex resolution, vertical
15810 The vertical resolution is @var{n}@tie{}machine units.  All vertical
15811 quantities are rounded to be multiples of this value.
15812 @end table
15814 The @code{res}, @code{unitwidth}, @code{fonts}, and @code{sizes} lines
15815 are mandatory.  Other commands are ignored by @code{gtroff} but may be
15816 used by postprocessors to store arbitrary information about the device
15817 in the @file{DESC} file.
15819 @kindex spare1
15820 @kindex spare2
15821 @kindex biggestfont
15822 Here a list of obsolete keywords which are recognized by @code{groff}
15823 but completely ignored: @code{spare1}, @code{spare2},
15824 @code{biggestfont}.
15826 @c ---------------------------------------------------------------------
15828 @node Font File Format,  , DESC File Format, Font Files
15829 @subsection Font File Format
15830 @cindex font file, format
15831 @cindex font description file, format
15832 @cindex format of font files
15833 @cindex format of font description files
15835 A @dfn{font file}, also (and probably better) called a @dfn{font
15836 description file}, has two sections.  The first section is a sequence of
15837 lines each containing a sequence of blank delimited words; the first
15838 word in the line is a key, and subsequent words give a value for that
15839 key.
15841 @table @code
15842 @item name @var{f}
15843 @kindex name
15844 The name of the font is@tie{}@var{f}.
15846 @item spacewidth @var{n}
15847 @kindex spacewidth
15848 The normal width of a space is@tie{}@var{n}.
15850 @item slant @var{n}
15851 @kindex slant
15852 The glyphs of the font have a slant of @var{n}@tie{}degrees.  (Positive
15853 means forward.)
15855 @item ligatures @var{lig1} @var{lig2} @dots{} @var{lign} [0]
15856 @kindex ligatures
15857 Glyphs @var{lig1}, @var{lig2}, @dots{}, @var{lign} are ligatures;
15858 possible ligatures are @samp{ff}, @samp{fi}, @samp{fl}, @samp{ffi} and
15859 @samp{ffl}.  For backwards compatibility, the list of ligatures may be
15860 terminated with a@tie{}0.  The list of ligatures may not extend over
15861 more than one line.
15863 @item special
15864 @cindex special fonts
15865 @kindex special
15866 The font is @dfn{special}; this means that when a glyph is requested
15867 that is not present in the current font, it is searched for in any
15868 special fonts that are mounted.
15869 @end table
15871 Other commands are ignored by @code{gtroff} but may be used by
15872 postprocessors to store arbitrary information about the font in the font
15873 file.
15875 @cindex comments in font files
15876 @cindex font files, comments
15877 @kindex #
15878 The first section can contain comments which start with the @samp{#}
15879 character and extend to the end of a line.
15881 The second section contains one or two subsections.  It must contain a
15882 @code{charset} subsection and it may also contain a @code{kernpairs}
15883 subsection.  These subsections can appear in any order.  Each subsection
15884 starts with a word on a line by itself.
15886 @kindex charset
15887 The word @code{charset} starts the character set
15888 subsection.@footnote{This keyword is misnamed since it starts a list of
15889 ordered glyphs, not characters.}  The @code{charset} line is followed by
15890 a sequence of lines.  Each line gives information for one glyph.  A line
15891 comprises a number of fields separated by blanks or tabs.  The format is
15893 @quotation
15894 @var{name} @var{metrics} @var{type} @var{code} [@var{entity-name}]
15895 [@code{--} @var{comment}]
15896 @end quotation
15898 @cindex 8-bit input
15899 @cindex input, 8-bit
15900 @cindex accessing unnamed glyphs with @code{\N}
15901 @cindex unnamed glyphs, accessing with @code{\N}
15902 @cindex characters, unnamed, accessing with @code{\N}
15903 @cindex glyphs, unnamed, accessing with @code{\N}
15904 @kindex ---
15905 @noindent
15906 @var{name} identifies the glyph name@footnote{The distinction between
15907 input, characters, and output, glyphs, is not clearly separated in the
15908 terminology of @code{groff}; for example, the @code{char} request should
15909 be called @code{glyph} since it defines an output entity.}: If
15910 @var{name} is a single character@tie{}@var{c} then it corresponds to the
15911 @code{gtroff} input character@tie{}@var{c}; if it is of the form
15912 @samp{\@var{c}} where @var{c} is a single character, then it corresponds
15913 to the special character @code{\[@var{c}]}; otherwise it corresponds to
15914 the special character @samp{\[@var{name}]}.  If it is exactly two
15915 characters @var{xx} it can be entered as @samp{\(@var{xx}}.  Note that
15916 single-letter special characters can't be accessed as @samp{\@var{c}};
15917 the only exception is @samp{\-} which is identical to @code{\[-]}.
15919 @code{gtroff} supports 8-bit input characters; however some utilities
15920 have difficulties with eight-bit characters.  For this reason, there is
15921 a convention that the entity name @samp{char@var{n}} is equivalent to
15922 the single input character whose code is@tie{}@var{n}.  For example,
15923 @samp{char163} would be equivalent to the character with code@tie{}163
15924 which is the pounds sterling sign in the ISO@tie{}@w{Latin-1} character
15925 set.  You shouldn't use @samp{char@var{n}} entities in font description
15926 files since they are related to input, not output.  Otherwise, you get
15927 hard-coded connections between input and output encoding which prevents
15928 use of different (input) character sets.
15930 The name @samp{---} is special and indicates that the glyph is unnamed;
15931 such glyphs can only be used by means of the @code{\N} escape sequence
15932 in @code{gtroff}.
15934 The @var{type} field gives the glyph type:
15936 @table @code
15937 @item 1
15938 the glyph has a descender, for example, @samp{p};
15940 @item 2
15941 the glyph has an ascender, for example, @samp{b};
15943 @item 3
15944 the glyph has both an ascender and a descender, for example, @samp{(}.
15945 @end table
15947 The @var{code} field gives the code which the postprocessor uses to
15948 print the glyph.  The glyph can also be input to @code{gtroff} using
15949 this code by means of the @code{\N} escape sequence.  @var{code} can be
15950 any integer.  If it starts with @samp{0} it is interpreted as octal; if
15951 it starts with @samp{0x} or @samp{0X} it is interpreted as hexadecimal.
15952 Note, however, that the @code{\N} escape sequence only accepts a decimal
15953 integer.
15955 The @var{entity-name} field gives an @acronym{ASCII} string identifying
15956 the glyph which the postprocessor uses to print the @code{gtroff} glyph
15957 @var{name}.  This field is optional and has been introduced so that the
15958 @code{grohtml} device driver can encode its character set.  For example,
15959 the glyph @samp{\[Po]} is represented as @samp{&pound;} in
15960 @acronym{HTML} 4.0.
15962 Anything on the line after the @var{entity-name} field resp.@: after
15963 @samp{--} is ignored.
15965 The @var{metrics} field has the form:
15967 @display
15968 @group
15969 @var{width}[@code{,}@var{height}[@code{,}@var{depth}[@code{,}@var{italic-correction}
15970   [@code{,}@var{left-italic-correction}[@code{,}@var{subscript-correction}]]]]]
15971 @end group
15972 @end display
15974 @noindent
15975 There must not be any spaces between these subfields (it has been split
15976 here into two lines for better legibility only).  Missing subfields are
15977 assumed to be@tie{}0.  The subfields are all decimal integers.  Since
15978 there is no associated binary format, these values are not required to
15979 fit into a variable of type @samp{char} as they are in @code{ditroff}.
15980 The @var{width} subfield gives the width of the glyph.  The @var{height}
15981 subfield gives the height of the glyph (upwards is positive); if a glyph
15982 does not extend above the baseline, it should be given a zero height,
15983 rather than a negative height.  The @var{depth} subfield gives the depth
15984 of the glyph, that is, the distance from the baseline to the lowest
15985 point below the baseline to which the glyph extends (downwards is
15986 positive); if a glyph does not extend below the baseline, it should be
15987 given a zero depth, rather than a negative depth.  The
15988 @var{italic-correction} subfield gives the amount of space that should
15989 be added after the glyph when it is immediately to be followed by a
15990 glyph from a roman font.  The @var{left-italic-correction} subfield
15991 gives the amount of space that should be added before the glyph when it
15992 is immediately to be preceded by a glyph from a roman font.  The
15993 @var{subscript-correction} gives the amount of space that should be
15994 added after a glyph before adding a subscript.  This should be less than
15995 the italic correction.
15997 A line in the @code{charset} section can also have the format
15999 @Example
16000 @var{name} "
16001 @endExample
16003 @noindent
16004 This indicates that @var{name} is just another name for the glyph
16005 mentioned in the preceding line.
16007 @kindex kernpairs
16008 The word @code{kernpairs} starts the kernpairs section.  This contains a
16009 sequence of lines of the form:
16011 @Example
16012 @var{c1} @var{c2} @var{n}
16013 @endExample
16015 @noindent
16016 This means that when glyph @var{c1} appears next to glyph @var{c2} the
16017 space between them should be increased by@tie{}@var{n}.  Most entries in
16018 the kernpairs section have a negative value for@tie{}@var{n}.
16022 @c =====================================================================
16023 @c =====================================================================
16025 @node Installation, Copying This Manual, File formats, Top
16026 @chapter Installation
16027 @cindex installation
16029 @c XXX
16033 @c =====================================================================
16034 @c =====================================================================
16036 @node Copying This Manual, Request Index, Installation, Top
16037 @appendix Copying This Manual
16039 @menu
16040 * GNU Free Documentation License::  License for copying this manual.
16041 @end menu
16043 @include fdl.texi
16047 @c =====================================================================
16048 @c =====================================================================
16050 @node Request Index, Escape Index, Copying This Manual, Top
16051 @appendix Request Index
16053 Requests appear without the leading control character (normally either
16054 @samp{.} or @samp{'}).
16056 @printindex rq
16060 @c =====================================================================
16061 @c =====================================================================
16063 @node Escape Index, Operator Index, Request Index, Top
16064 @appendix Escape Index
16066 Any escape sequence @code{\@var{X}} with @var{X} not in the list below
16067 emits a warning, printing glyph @var{X}.
16069 @printindex es
16073 @c =====================================================================
16074 @c =====================================================================
16076 @node Operator Index, Register Index, Escape Index, Top
16077 @appendix Operator Index
16079 @printindex op
16083 @c =====================================================================
16084 @c =====================================================================
16086 @node Register Index, Macro Index, Operator Index, Top
16087 @appendix Register Index
16089 The macro package or program a specific register belongs to is appended in
16090 brackets.
16092 A register name@tie{}@code{x} consisting of exactly one character can be
16093 accessed as @samp{\nx}.  A register name @code{xx} consisting of exactly
16094 two characters can be accessed as @samp{\n(xx}.  Register names
16095 @code{xxx} of any length can be accessed as @samp{\n[xxx]}.
16097 @printindex vr
16101 @c =====================================================================
16102 @c =====================================================================
16104 @node Macro Index, String Index, Register Index, Top
16105 @appendix Macro Index
16107 The macro package a specific macro belongs to is appended in brackets.
16108 They appear without the leading control character (normally @samp{.}).
16110 @printindex ma
16114 @c =====================================================================
16115 @c =====================================================================
16117 @node String Index, Glyph Name Index, Macro Index, Top
16118 @appendix String Index
16120 The macro package or program a specific string belongs to is appended in
16121 brackets.
16123 A string name@tie{}@code{x} consisting of exactly one character can be
16124 accessed as @samp{\*x}.  A string name @code{xx} consisting of exactly
16125 two characters can be accessed as @samp{\*(xx}.  String names @code{xxx}
16126 of any length can be accessed as @samp{\*[xxx]}.
16129 @printindex st
16133 @c =====================================================================
16134 @c =====================================================================
16136 @node Glyph Name Index, Font File Keyword Index, String Index, Top
16137 @appendix Glyph Name Index
16139 A glyph name @code{xx} consisting of exactly two characters can be
16140 accessed as @samp{\(xx}.  Glyph names @code{xxx} of any length can be
16141 accessed as @samp{\[xxx]}.
16143 @c XXX
16147 @c =====================================================================
16148 @c =====================================================================
16150 @node Font File Keyword Index, Program and File Index, Glyph Name Index, Top
16151 @appendix Font File Keyword Index
16153 @printindex ky
16157 @c =====================================================================
16158 @c =====================================================================
16160 @node Program and File Index, Concept Index, Font File Keyword Index, Top
16161 @appendix Program and File Index
16163 @printindex pg
16167 @c =====================================================================
16168 @c =====================================================================
16170 @node Concept Index,  , Program and File Index, Top
16171 @appendix Concept Index
16173 @printindex cp
16176 @bye