1 This is groff.info, produced by makeinfo version 5.2dev from
4 This manual documents GNU 'troff' version 1.22.3.
6 Copyright © 1994-2014 Free Software Foundation, Inc.
8 Permission is granted to copy, distribute and/or modify this
9 document under the terms of the GNU Free Documentation License,
10 Version 1.3 or any later version published by the Free Software
11 Foundation; with no Invariant Sections, with the Front-Cover texts
12 being "A GNU Manual," and with the Back-Cover Texts as in (a)
13 below. A copy of the license is included in the section entitled
14 "GNU Free Documentation License."
16 (a) The FSF's Back-Cover Text is: "You have the freedom to copy and
17 modify this GNU manual. Buying copies from the FSF supports it in
18 developing GNU and promoting software freedom."
19 INFO-DIR-SECTION Typesetting
21 * Groff: (groff). The GNU troff document formatting system.
25 File: groff.info, Node: Top, Next: Introduction, Prev: (dir), Up: (dir)
34 * Tutorial for Macro Users::
41 * Copying This Manual::
49 * Font File Keyword Index::
50 * Program and File Index::
53 This manual documents GNU 'troff' version 1.22.3.
55 Copyright © 1994-2014 Free Software Foundation, Inc.
57 Permission is granted to copy, distribute and/or modify this
58 document under the terms of the GNU Free Documentation License,
59 Version 1.3 or any later version published by the Free Software
60 Foundation; with no Invariant Sections, with the Front-Cover texts
61 being "A GNU Manual," and with the Back-Cover Texts as in (a)
62 below. A copy of the license is included in the section entitled
63 "GNU Free Documentation License."
65 (a) The FSF's Back-Cover Text is: "You have the freedom to copy and
66 modify this GNU manual. Buying copies from the FSF supports it in
67 developing GNU and promoting software freedom."
70 File: groff.info, Node: Introduction, Next: Invoking groff, Prev: Top, Up: Top
75 GNU 'troff' (or 'groff') is a system for typesetting documents. 'troff'
76 is very flexible and has been used extensively for some thirty years.
77 It is well entrenched in the UNIX community.
83 * groff Capabilities::
84 * Macro Package Intro::
85 * Preprocessor Intro::
86 * Output device intro::
90 File: groff.info, Node: What Is groff?, Next: History, Prev: Introduction, Up: Introduction
95 'groff' belongs to an older generation of document preparation systems,
96 which operate more like compilers than the more recent interactive
97 WYSIWYG(1) (*note What Is groff?-Footnote-1::) systems. 'groff' and its
98 contemporary counterpart, TeX, both work using a "batch" paradigm: The
99 input (or "source") files are normal text files with embedded formatting
100 commands. These files can then be processed by 'groff' to produce a
101 typeset document on a variety of devices.
103 'groff' should not be confused with a "word processor", an integrated
104 system of editor and text formatter. Also, many word processors follow
105 the WYSIWYG paradigm discussed earlier.
107 Although WYSIWYG systems may be easier to use, they have a number of
108 disadvantages compared to 'troff':
110 * They must be used on a graphics display to work on a document.
112 * Most of the WYSIWYG systems are either non-free or are not very
115 * 'troff' is firmly entrenched in all UNIX systems.
117 * It is difficult to have a wide range of capabilities within the
118 confines of a GUI/window system.
120 * It is more difficult to make global changes to a document.
122 "GUIs normally make it simple to accomplish simple actions and
123 impossible to accomplish complex actions." -Doug Gwyn (22/Jun/91
124 in 'comp.unix.wizards')
127 File: groff.info, Node: What Is groff?-Footnotes, Up: What Is groff?
129 (1) What You See Is What You Get
132 File: groff.info, Node: History, Next: groff Capabilities, Prev: What Is groff?, Up: Introduction
137 'troff' can trace its origins back to a formatting program called
138 'RUNOFF', written by Jerry Saltzer, which ran on the CTSS (_Compatible
139 Time Sharing System_, a project of MIT, the Massachusetts Institute of
140 Technology) in the mid-sixties.(1) (*note History-Footnote-1::) The
141 name came from the use of the phrase "run off a document", meaning to
142 print it out. Bob Morris ported it to the 635 architecture and called
143 the program 'roff' (an abbreviation of 'runoff'). It was rewritten as
144 'rf' for the PDP-7 (before having UNIX), and at the same time (1969),
145 Doug McIllroy rewrote an extended and simplified version of 'roff' in
146 the BCPL programming language.
148 In 1971, the UNIX developers wanted to get a PDP-11, and to justify
149 the cost, proposed the development of a document formatting system for
150 the AT&T patents division. This first formatting program was a
151 reimplementation of McIllroy's 'roff', written by J. F. Ossanna.
153 When they needed a more flexible language, a new version of 'roff'
154 called 'nroff' ("Newer 'roff'") was written. It had a much more
155 complicated syntax, but provided the basis for all future versions.
156 When they got a Graphic Systems CAT Phototypesetter, Ossanna wrote a
157 version of 'nroff' that would drive it. It was dubbed 'troff', for
158 "typesetter 'roff'", although many people have speculated that it
159 actually means "Times 'roff'" because of the use of the Times font
160 family in 'troff' by default. As such, the name 'troff' is pronounced
161 't-roff' rather than 'trough'.
163 With 'troff' came 'nroff' (they were actually the same program except
164 for some '#ifdef's), which was for producing output for line printers
165 and character terminals. It understood everything 'troff' did, and
166 ignored the commands that were not applicable (e.g. font changes).
168 Since there are several things that cannot be done easily in 'troff',
169 work on several preprocessors began. These programs would transform
170 certain parts of a document into 'troff', which made a very natural use
173 The 'eqn' preprocessor allowed mathematical formulæ to be specified
174 in a much simpler and more intuitive manner. 'tbl' is a preprocessor
175 for formatting tables. The 'refer' preprocessor (and the similar
176 program, 'bib') processes citations in a document according to a
177 bibliographic database.
179 Unfortunately, Ossanna's 'troff' was written in PDP-11 assembly
180 language and produced output specifically for the CAT phototypesetter.
181 He rewrote it in C, although it was now 7000 lines of uncommented code
182 and still dependent on the CAT. As the CAT became less common, and was
183 no longer supported by the manufacturer, the need to make it support
184 other devices became a priority. However, before this could be done,
185 Ossanna died by a severe heart attack in a hospital while recovering
188 So, Brian Kernighan took on the task of rewriting 'troff'. The newly
189 rewritten version produced device independent code that was very easy
190 for postprocessors to read and translate to the appropriate printer
191 codes. Also, this new version of 'troff' (called 'ditroff' for "device
192 independent 'troff'") had several extensions, which included drawing
195 Due to the additional abilities of the new version of 'troff',
196 several new preprocessors appeared. The 'pic' preprocessor provides a
197 wide range of drawing functions. Likewise the 'ideal' preprocessor did
198 the same, although via a much different paradigm. The 'grap'
199 preprocessor took specifications for graphs, but, unlike other
200 preprocessors, produced 'pic' code.
202 James Clark began work on a GNU implementation of 'ditroff' in
203 early 1989. The first version, 'groff' 0.3.1, was released June 1990.
206 * A replacement for 'ditroff' with many extensions.
208 * The 'soelim', 'pic', 'tbl', and 'eqn' preprocessors.
210 * Postprocessors for character devices, POSTSCRIPT, TeX DVI, and
211 X Windows. GNU 'troff' also eliminated the need for a separate
212 'nroff' program with a postprocessor that would produce ASCII
215 * A version of the 'me' macros and an implementation of the 'man'
218 Also, a front-end was included that could construct the, sometimes
219 painfully long, pipelines required for all the post- and preprocessors.
221 Development of GNU 'troff' progressed rapidly, and saw the additions
222 of a replacement for 'refer', an implementation of the 'ms' and 'mm'
223 macros, and a program to deduce how to format a document ('grog').
225 It was declared a stable (i.e. non-beta) package with the release of
226 version 1.04 around November 1991.
228 Beginning in 1999, 'groff' has new maintainers (the package was an
229 orphan for a few years). As a result, new features and programs like
230 'grn', a preprocessor for gremlin images, and an output device to
231 produce HTML and XHTML have been added.
234 File: groff.info, Node: History-Footnotes, Up: History
236 (1) Jerome H. Saltzer, a grad student then, later a Professor of
237 Electrical Engineering, now retired. Saltzer's PhD thesis was the first
238 application for 'RUNOFF' and is available from the MIT Libraries.
241 File: groff.info, Node: groff Capabilities, Next: Macro Package Intro, Prev: History, Up: Introduction
243 1.3 'groff' Capabilities
244 ========================
246 So what exactly is 'groff' capable of doing? 'groff' provides a wide
247 range of low-level text formatting operations. Using these, it is
248 possible to perform a wide range of formatting tasks, such as footnotes,
249 table of contents, multiple columns, etc. Here's a list of the most
250 important operations supported by 'groff':
252 * text filling, adjusting, and centering
258 * font and glyph size control
260 * vertical spacing (e.g. double-spacing)
262 * line length and indenting
264 * macros, strings, diversions, and traps
268 * tabs, leaders, and fields
270 * input and output conventions and character translation
272 * overstrike, bracket, line drawing, and zero-width functions
274 * local horizontal and vertical motions and the width function
278 * output line numbering
280 * conditional acceptance of input
282 * environment switching
284 * insertions from the standard input
286 * input/output file switching
288 * output and error messages
291 File: groff.info, Node: Macro Package Intro, Next: Preprocessor Intro, Prev: groff Capabilities, Up: Introduction
296 Since 'groff' provides such low-level facilities, it can be quite
297 difficult to use by itself. However, 'groff' provides a "macro"
298 facility to specify how certain routine operations (e.g. starting
299 paragraphs, printing headers and footers, etc.) should be done. These
300 macros can be collected together into a "macro package". There are a
301 number of macro packages available; the most common (and the ones
302 described in this manual) are 'man', 'mdoc', 'me', 'ms', and 'mm'.
305 File: groff.info, Node: Preprocessor Intro, Next: Output device intro, Prev: Macro Package Intro, Up: Introduction
310 Although 'groff' provides most functions needed to format a document,
311 some operations would be unwieldy (e.g. to draw pictures). Therefore,
312 programs called "preprocessors" were written that understand their own
313 language and produce the necessary 'groff' operations. These
314 preprocessors are able to differentiate their own input from the rest of
315 the document via markers.
317 To use a preprocessor, UNIX pipes are used to feed the output from
318 the preprocessor into 'groff'. Any number of preprocessors may be used
319 on a given document; in this case, the preprocessors are linked together
320 into one pipeline. However, with 'groff', the user does not need to
321 construct the pipe, but only tell 'groff' what preprocessors to use.
323 'groff' currently has preprocessors for producing tables ('tbl'),
324 typesetting equations ('eqn'), drawing pictures ('pic' and 'grn'),
325 processing bibliographies ('refer'), and drawing chemical structures
326 ('chem'). An associated program that is useful when dealing with
327 preprocessors is 'soelim'.
329 A free implementation of 'grap', a preprocessor for drawing graphs,
330 can be obtained as an extra package; 'groff' can use 'grap' also.
332 Unique to 'groff' is the 'preconv' preprocessor that enables 'groff'
333 to handle documents in various input encodings.
335 There are other preprocessors in existence, but, unfortunately, no
336 free implementations are available. Among them is a preprocessor for
337 drawing mathematical pictures ('ideal').
340 File: groff.info, Node: Output device intro, Next: Credits, Prev: Preprocessor Intro, Up: Introduction
345 'groff' actually produces device independent code that may be fed into a
346 postprocessor to produce output for a particular device. Currently,
347 'groff' has postprocessors for POSTSCRIPT devices, character terminals,
348 X Windows (for previewing), TeX DVI format, HP LaserJet 4 and Canon LBP
349 printers (which use CAPSL), HTML, XHTML, and PDF.
352 File: groff.info, Node: Credits, Prev: Output device intro, Up: Introduction
357 Large portions of this manual were taken from existing documents, most
358 notably, the manual pages for the 'groff' package by James Clark, and
359 Eric Allman's papers on the 'me' macro package.
361 The section on the 'man' macro package is partly based on Susan G.
362 Kleinmann's 'groff_man' manual page written for the Debian GNU/Linux
365 Larry Kollar contributed the section in the 'ms' macro package.
368 File: groff.info, Node: Invoking groff, Next: Tutorial for Macro Users, Prev: Introduction, Up: Top
373 This section focuses on how to invoke the 'groff' front end. This front
374 end takes care of the details of constructing the pipeline among the
375 preprocessors, 'gtroff' and the postprocessor.
377 It has become a tradition that GNU programs get the prefix 'g' to
378 distinguish it from its original counterparts provided by the host (see
379 *note Environment::, for more details). Thus, for example, 'geqn' is
380 GNU 'eqn'. On operating systems like GNU/Linux or the Hurd, which don't
381 contain proprietary versions of 'troff', and on MS-DOS/MS-Windows, where
382 'troff' and associated programs are not available at all, this prefix is
383 omitted since GNU 'troff' is the only used incarnation of 'troff'.
384 Exception: 'groff' is never replaced by 'roff'.
386 In this document, we consequently say 'gtroff' when talking about the
387 GNU 'troff' program. All other implementations of 'troff' are called
388 AT&T 'troff', which is the common origin of all 'troff' derivates (with
389 more or less compatible changes). Similarly, we say 'gpic', 'geqn',
396 * Macro Directories::
399 * Invocation Examples::
402 File: groff.info, Node: Groff Options, Next: Environment, Prev: Invoking groff, Up: Invoking groff
407 'groff' normally runs the 'gtroff' program and a postprocessor
408 appropriate for the selected device. The default device is 'ps' (but it
409 can be changed when 'groff' is configured and built). It can optionally
410 preprocess with any of 'gpic', 'geqn', 'gtbl', 'ggrn', 'grap', 'gchem',
411 'grefer', 'gsoelim', or 'preconv'.
413 This section only documents options to the 'groff' front end. Many
414 of the arguments to 'groff' are passed on to 'gtroff', therefore those
415 are also included. Arguments to pre- or postprocessors can be found in
416 *note Invoking gpic::, *note Invoking geqn::, *note Invoking gtbl::,
417 *note Invoking ggrn::, *note Invoking grefer::, *note Invoking gchem::,
418 *note Invoking gsoelim::, *note Invoking preconv::, *note Invoking
419 grotty::, *note Invoking grops::, *note Invoking gropdf::, *note
420 Invoking grohtml::, *note Invoking grodvi::, *note Invoking grolj4::,
421 *note Invoking grolbp::, and *note Invoking gxditview::.
423 The command line format for 'groff' is:
425 groff [ -abceghijklpstvzCEGNRSUVXZ ] [ -dCS ] [ -DARG ]
426 [ -fFAM ] [ -FDIR ] [ -IDIR ] [ -KARG ]
427 [ -LARG ] [ -mNAME ] [ -MDIR ] [ -nNUM ]
428 [ -oLIST ] [ -PARG ] [ -rCN ] [ -TDEV ]
429 [ -wNAME ] [ -WNAME ] [ FILES... ]
431 The command line format for 'gtroff' is as follows.
433 gtroff [ -abcivzCERU ] [ -dCS ] [ -fFAM ] [ -FDIR ]
434 [ -mNAME ] [ -MDIR ] [ -nNUM ] [ -oLIST ]
435 [ -rCN ] [ -TNAME ] [ -wNAME ] [ -WNAME ]
438 Obviously, many of the options to 'groff' are actually passed on to
441 Options without an argument can be grouped behind a single '-'. A
442 filename of '-' denotes the standard input. It is possible to have
443 whitespace between an option and its parameter.
445 The 'grog' command can be used to guess the correct 'groff' command
448 Here's the description of the command-line options:
451 Generate an ASCII approximation of the typeset output. The
452 read-only register '.A' is then set to 1. *Note Built-in
453 Registers::. A typical example is
455 groff -a -man -Tdvi troff.man | less
457 which shows how lines are broken for the DVI device. Note that
458 this option is rather useless today since graphic output devices
459 are available virtually everywhere.
462 Print a backtrace with each warning or error message. This
463 backtrace should help track down the cause of the error. The line
464 numbers given in the backtrace may not always be correct: 'gtroff'
465 can get confused by 'as' or 'am' requests while counting line
469 Suppress color output.
472 Enable compatibility mode. *Note Implementation Differences::, for
473 the list of incompatibilities between 'groff' and AT&T 'troff'.
477 Define C or NAME to be a string S. C must be a one-letter name;
478 NAME can be of arbitrary length. All string assignments happen
479 before loading any macro file (including the start-up file).
482 Set default input encoding used by 'preconv' to ARG. Implies '-k'.
485 Preprocess with 'geqn'.
488 Inhibit all error messages.
491 Use FAM as the default font family. *Note Font Families::.
494 Search 'DIR' for subdirectories 'devNAME' (NAME is the name of the
495 device), for the 'DESC' file, and for font files before looking in
496 the standard directories (*note Font Directories::). This option
497 is passed to all pre- and postprocessors using the
498 'GROFF_FONT_PATH' environment variable.
501 Preprocess with 'ggrn'.
504 Preprocess with 'grap'. Implies '-p'.
507 Print a help message.
510 Read the standard input after all the named input files have been
514 This option may be used to specify a directory to search for files.
515 It is passed to the following programs:
517 * 'gsoelim' (see *note gsoelim:: for more details); it also
518 implies 'groff''s '-s' option.
520 * 'gtroff'; it is used to search files named in the 'psbb' and
523 * 'grops'; it is used to search files named in the
524 '\X'ps: import' and '\X'ps: file' escapes.
526 The current directory is always searched first. This option may be
527 specified more than once; the directories are searched in the order
528 specified. No directory search is performed for files specified
529 using an absolute path.
532 Preprocess with 'gchem'. Implies '-p'.
535 Preprocess with 'preconv'. This is run before any other
536 preprocessor. Please refer to 'preconv''s manual page for its
537 behaviour if no '-K' (or '-D') option is specified.
540 Set input encoding used by preconv to ARG. Implies '-k'.
543 Send the output to a spooler for printing. The command used for
544 this is specified by the 'print' command in the device description
545 file (see *note Font Files::, for more info). If not present, '-l'
549 Pass ARG to the spooler. Each argument should be passed with a
550 separate '-L' option. Note that 'groff' does not prepend a '-' to
551 ARG before passing it to the postprocessor. If the 'print' keyword
552 in the device description file is missing, '-L' is ignored.
555 Read in the file 'NAME.tmac'. Normally 'groff' searches for this
556 in its macro directories. If it isn't found, it tries 'tmac.NAME'
557 (searching in the same directories).
560 Search directory 'DIR' for macro files before the standard
561 directories (*note Macro Directories::).
564 Number the first page NUM.
567 Don't allow newlines with 'eqn' delimiters. This is the same as
568 the '-N' option in 'geqn'.
571 Output only pages in LIST, which is a comma-separated list of page
572 ranges; 'N' means print page N, 'M-N' means print every page
573 between M and N, '-N' means print every page up to N, 'N-' means
574 print every page beginning with N. 'gtroff' exits after printing
575 the last page in the list. All the ranges are inclusive on both
578 Within 'gtroff', this information can be extracted with the '.P'
579 register. *Note Built-in Registers::.
581 If your document restarts page numbering at the beginning of each
582 chapter, then 'gtroff' prints the specified page range for each
586 Preprocess with 'gpic'.
589 Pass ARG to the postprocessor. Each argument should be passed with
590 a separate '-P' option. Note that 'groff' does not prepend '-' to
591 ARG before passing it to the postprocessor.
595 Set number register C or NAME to the value N. C must be a
596 one-letter name; NAME can be of arbitrary length. N can be any
597 'gtroff' numeric expression. All register assignments happen
598 before loading any macro file (including the start-up file).
601 Preprocess with 'grefer'. No mechanism is provided for passing
602 arguments to 'grefer' because most 'grefer' options have equivalent
603 commands that can be included in the file. *Note grefer::, for
606 Note that 'gtroff' also accepts a '-R' option, which is not
607 accessible via 'groff'. This option prevents the loading of the
608 'troffrc' and 'troffrc-end' files.
611 Preprocess with 'gsoelim'.
614 Safer mode. Pass the '-S' option to 'gpic' and disable the 'open',
615 'opena', 'pso', 'sy', and 'pi' requests. For security reasons,
616 this is enabled by default.
619 Preprocess with 'gtbl'.
622 Prepare output for device DEV. The default device is 'ps', unless
623 changed when 'groff' was configured and built. The following are
624 the output devices currently available:
627 For POSTSCRIPT printers and previewers.
630 For PDF viewers or printers.
636 For a 75dpi X11 previewer.
639 For a 75dpi X11 previewer with a 12pt base font in the
643 For a 100dpi X11 previewer.
646 For a 100dpi X11 previewer with a 12pt base font in the
650 For typewriter-like devices using the (7-bit) ASCII character
654 For typewriter-like devices that support the Latin-1
655 (ISO 8859-1) character set.
658 For typewriter-like devices that use the Unicode (ISO 10646)
659 character set with UTF-8 encoding.
662 For typewriter-like devices that use the EBCDIC encoding IBM
666 For HP LaserJet4-compatible (or other PCL5-compatible)
670 For Canon CAPSL printers (LBP-4 and LBP-8 series laser
675 To produce HTML and XHTML output, respectively. Note that
676 this driver consists of two parts, a preprocessor
677 ('pre-grohtml') and a postprocessor ('post-grohtml').
679 The predefined 'gtroff' string register '.T' contains the current
680 output device; the read-only number register '.T' is set to 1 if
681 this option is used (which is always true if 'groff' is used to
682 call 'gtroff'). *Note Built-in Registers::.
684 The postprocessor to be used for a device is specified by the
685 'postpro' command in the device description file. (*Note Font
686 Files::, for more info.) This can be overridden with the '-X'
690 Unsafe mode. This enables the 'open', 'opena', 'pso', 'sy', and
694 Enable warning NAME. Available warnings are described in *note
695 Debugging::. Multiple '-w' options are allowed.
698 Inhibit warning NAME. Multiple '-W' options are allowed.
701 Make programs run by 'groff' print out their version number.
704 Print the pipeline on 'stdout' instead of executing it. If
705 specified more than once, print the pipeline on 'stderr' and
709 Preview with 'gxditview' instead of using the usual postprocessor.
710 This is unlikely to produce good results except with '-Tps'.
712 Note that this is not the same as using '-TX75' or '-TX100' to view
713 a document with 'gxditview': The former uses the metrics of the
714 specified device, whereas the latter uses X-specific fonts and
718 Suppress output from 'gtroff'. Only error messages are printed.
721 Do not postprocess the output of 'gtroff'. Normally 'groff'
722 automatically runs the appropriate postprocessor.
725 File: groff.info, Node: Environment, Next: Macro Directories, Prev: Groff Options, Up: Invoking groff
730 There are also several environment variables (of the operating system,
731 not within 'gtroff') that can modify the behavior of 'groff'.
734 This search path, followed by 'PATH', is used for commands executed
737 'GROFF_COMMAND_PREFIX'
738 If this is set to X, then 'groff' runs 'Xtroff' instead of
739 'gtroff'. This also applies to 'tbl', 'pic', 'eqn', 'grn', 'chem',
740 'refer', and 'soelim'. It does not apply to 'grops', 'grodvi',
741 'grotty', 'pre-grohtml', 'post-grohtml', 'preconv', 'grolj4',
742 'gropdf', and 'gxditview'.
744 The default command prefix is determined during the installation
745 process. If a non-GNU troff system is found, prefix 'g' is used,
749 The value of this environment value is passed to the 'preconv'
750 preprocessor to select the encoding of input files. Setting this
751 option implies 'groff''s command line option '-k' (this is, 'groff'
752 actually always calls 'preconv'). If set without a value, 'groff'
753 calls 'preconv' without arguments. An explicit '-K' command line
754 option overrides the value of 'GROFF_ENCODING'. See the manual
755 page of 'preconv' for details.
758 A colon-separated list of directories in which to search for the
759 'dev'NAME directory (before the default directories are tried).
760 *Note Font Directories::.
763 A colon-separated list of directories in which to search for macro
764 files (before the default directories are tried). *Note Macro
768 The directory in which 'groff' creates temporary files. If this is
769 not set and 'TMPDIR' is set, temporary files are created in that
770 directory. Otherwise temporary files are created in a
771 system-dependent default directory (on Unix and GNU/Linux systems,
772 this is usually '/tmp'). 'grops', 'grefer', 'pre-grohtml', and
773 'post-grohtml' can create temporary files in this directory.
776 The default output device.
778 Note that MS-DOS and MS-Windows ports of 'groff' use semi-colons,
779 rather than colons, to separate the directories in the lists described
783 File: groff.info, Node: Macro Directories, Next: Font Directories, Prev: Environment, Up: Invoking groff
785 2.3 Macro Directories
786 =====================
788 All macro file names must be named 'NAME.tmac' or 'tmac.NAME' to make
789 the '-mNAME' command line option work. The 'mso' request doesn't have
790 this restriction; any file name can be used, and 'gtroff' won't try to
791 append or prepend the 'tmac' string.
793 Macro files are kept in the "tmac directories", all of which
794 constitute the "tmac path". The elements of the search path for macro
795 files are (in that order):
797 * The directories specified with 'gtroff''s or 'groff''s '-M' command
800 * The directories given in the 'GROFF_TMAC_PATH' environment
803 * The current directory (only if in unsafe mode using the '-U'
804 command line switch).
806 * The home directory.
808 * A platform-dependent directory, a site-specific
809 (platform-independent) directory, and the main tmac directory; the
810 default locations are
812 /usr/local/lib/groff/site-tmac
813 /usr/local/share/groff/site-tmac
814 /usr/local/share/groff/1.22.3/tmac
816 assuming that the version of 'groff' is 1.22.3, and the
817 installation prefix was '/usr/local'. It is possible to fine-tune
818 those directories during the installation process.
821 File: groff.info, Node: Font Directories, Next: Paper Size, Prev: Macro Directories, Up: Invoking groff
826 Basically, there is no restriction how font files for 'groff' are named
827 and how long font names are; however, to make the font family mechanism
828 work (*note Font Families::), fonts within a family should start with
829 the family name, followed by the shape. For example, the Times family
830 uses 'T' for the family name and 'R', 'B', 'I', and 'BI' to indicate the
831 shapes 'roman', 'bold', 'italic', and 'bold italic', respectively. Thus
832 the final font names are 'TR', 'TB', 'TI', and 'TBI'.
834 All font files are kept in the "font directories", which constitute
835 the "font path". The file search functions always append the directory
836 'dev'NAME, where NAME is the name of the output device. Assuming, say,
837 DVI output, and '/foo/bar' as a font directory, the font files for
838 'grodvi' must be in '/foo/bar/devdvi'.
840 The elements of the search path for font files are (in that order):
842 * The directories specified with 'gtroff''s or 'groff''s '-F' command
843 line option. All device drivers and some preprocessors also have
846 * The directories given in the 'GROFF_FONT_PATH' environment
849 * A site-specific directory and the main font directory; the default
852 /usr/local/share/groff/site-font
853 /usr/local/share/groff/1.22.3/font
855 assuming that the version of 'groff' is 1.22.3, and the
856 installation prefix was '/usr/local'. It is possible to fine-tune
857 those directories during the installation process.
860 File: groff.info, Node: Paper Size, Next: Invocation Examples, Prev: Font Directories, Up: Invoking groff
865 In groff, the page size for 'gtroff' and for output devices are handled
866 separately. *Note Page Layout::, for vertical manipulation of the page
867 size. *Note Line Layout::, for horizontal changes.
869 A default paper size can be set in the device's 'DESC' file. Most
870 output devices also have a command line option '-p' to override the
871 default paper size and option '-l' to use landscape orientation. *Note
872 DESC File Format::, for a description of the 'papersize' keyword, which
873 takes the same argument as '-p'.
875 A convenient shorthand to set a particular paper size for 'gtroff' is
876 command line option '-dpaper=SIZE'. This defines string 'paper', which
877 is processed in file 'papersize.tmac' (loaded in the start-up file
878 'troffrc' by default). Possible values for SIZE are the same as the
879 predefined values for the 'papersize' keyword (but only in lowercase)
880 except 'a7'-'d7'. An appended 'l' (ell) character denotes landscape
883 For example, use the following for PS output on A4 paper in landscape
886 groff -Tps -dpaper=a4l -P-pa4 -P-l -ms foo.ms > foo.ps
888 Note that it is up to the particular macro package to respect default
889 page dimensions set in this way (most do).
892 File: groff.info, Node: Invocation Examples, Prev: Paper Size, Up: Invoking groff
894 2.6 Invocation Examples
895 =======================
897 This section lists several common uses of 'groff' and the corresponding
902 This command processes 'file' without a macro package or a preprocessor.
903 The output device is the default, 'ps', and the output is sent to
906 groff -t -mandoc -Tascii file | less
908 This is basically what a call to the 'man' program does. 'gtroff'
909 processes the manual page 'file' with the 'mandoc' macro file (which in
910 turn either calls the 'man' or the 'mdoc' macro package), using the
911 'tbl' preprocessor and the ASCII output device. Finally, the 'less'
912 pager displays the result.
916 Preview 'file' with 'gxditview', using the 'me' macro package. Since no
917 '-T' option is specified, use the default device ('ps'). Note that you
918 can either say '-m me' or '-me'; the latter is an anachronism from the
919 early days of UNIX.(1) (*note Invocation Examples-Footnote-1::)
921 groff -man -rD1 -z file
923 Check 'file' with the 'man' macro package, forcing double-sided printing
924 - don't produce any output.
931 File: groff.info, Node: Invocation Examples-Footnotes, Up: Invocation Examples
933 (1) The same is true for the other main macro packages that come with
934 'groff': 'man', 'mdoc', 'ms', 'mm', and 'mandoc'. This won't work in
935 general; for example, to load 'trace.tmac', either '-mtrace' or
936 '-m trace' must be used.
939 File: groff.info, Node: grog, Prev: Invocation Examples, Up: Invocation Examples
944 'grog' reads files, guesses which of the 'groff' preprocessors and/or
945 macro packages are required for formatting them, and prints the 'groff'
946 command including those options on the standard output. It generates
947 one or more of the options '-e', '-man', '-me', '-mm', '-mom', '-ms',
948 '-mdoc', '-mdoc-old', '-p', '-R', '-g', '-G', '-s', and '-t'.
950 A special file name '-' refers to the standard input. Specifying no
951 files also means to read the standard input. Any specified options are
952 included in the printed command. No space is allowed between options
953 and their arguments. The only options recognized are '-C' (which is
954 also passed on) to enable compatibility mode, and '-v' to print the
955 version number and exit.
961 guesses the appropriate command to print 'paper.ms' and then prints it
962 to the command line after adding the '-Tdvi' option. For direct
963 execution, enclose the call to 'grog' in backquotes at the UNIX shell
966 `grog -Tdvi paper.ms` > paper.dvi
968 As seen in the example, it is still necessary to redirect the output to
969 something meaningful (i.e. either a file or a pager program like
973 File: groff.info, Node: Tutorial for Macro Users, Next: Macro Packages, Prev: Invoking groff, Up: Top
975 3 Tutorial for Macro Users
976 **************************
978 Most users tend to use a macro package to format their papers. This
979 means that the whole breadth of 'groff' is not necessary for most
980 people. This chapter covers the material needed to efficiently use a
989 File: groff.info, Node: Basics, Next: Common Features, Prev: Tutorial for Macro Users, Up: Tutorial for Macro Users
994 This section covers some of the basic concepts necessary to understand
995 how to use a macro package.(1) (*note Basics-Footnote-1::) References
996 are made throughout to more detailed information, if desired.
998 'gtroff' reads an input file prepared by the user and outputs a
999 formatted document suitable for publication or framing. The input
1000 consists of text, or words to be printed, and embedded commands
1001 ("requests" and "escapes"), which tell 'gtroff' how to format the
1002 output. For more detail on this, see *note Embedded Commands::.
1004 The word "argument" is used in this chapter to mean a word or number
1005 that appears on the same line as a request, and which modifies the
1006 meaning of that request. For example, the request
1010 spaces one line, but
1014 spaces four lines. The number 4 is an argument to the 'sp' request,
1015 which says to space four lines instead of one. Arguments are separated
1016 from the request and from each other by spaces (_no_ tabs). More
1017 details on this can be found in *note Request and Macro Arguments::.
1019 The primary function of 'gtroff' is to collect words from input
1020 lines, fill output lines with those words, justify the right-hand margin
1021 by inserting extra spaces in the line, and output the result. For
1028 Four score and seven
1031 is read, packed onto output lines, and justified to produce:
1033 Now is the time for all good men to come to the aid of their party.
1034 Four score and seven years ago, etc.
1036 Sometimes a new output line should be started even though the current
1037 line is not yet full; for example, at the end of a paragraph. To do
1038 this it is possible to cause a "break", which starts a new output line.
1039 Some requests cause a break automatically, as normally do blank input
1040 lines and input lines beginning with a space.
1042 Not all input lines are text to be formatted. Some input lines are
1043 requests that describe how to format the text. Requests always have a
1044 period ('.') or an apostrophe (''') as the first character of the input
1047 The text formatter also does more complex things, such as
1048 automatically numbering pages, skipping over page boundaries, putting
1049 footnotes in the correct place, and so forth.
1051 Here are a few hints for preparing text for input to 'gtroff'.
1053 * First, keep the input lines short. Short input lines are easier to
1054 edit, and 'gtroff' packs words onto longer lines anyhow.
1056 * In keeping with this, it is helpful to begin a new line after every
1057 comma or phrase, since common corrections are to add or delete
1058 sentences or phrases.
1060 * End each sentence with two spaces - or better, start each sentence
1061 on a new line. 'gtroff' recognizes characters that usually end a
1062 sentence, and inserts sentence space accordingly.
1064 * Do not hyphenate words at the end of lines - 'gtroff' is smart
1065 enough to hyphenate words as needed, but is not smart enough to
1066 take hyphens out and join a word back together. Also, words such
1067 as "mother-in-law" should not be broken over a line, since then a
1068 space can occur where not wanted, such as "mother- in-law".
1070 'gtroff' double-spaces output text automatically if you use the
1071 request '.ls 2'. Reactivate single-spaced mode by typing '.ls 1'.(2)
1072 (*note Basics-Footnote-2::)
1074 A number of requests allow to change the way the output looks,
1075 sometimes called the "layout" of the output page. Most of these
1076 requests adjust the placing of "whitespace" (blank lines or spaces).
1078 The 'bp' request starts a new page, causing a line break.
1080 The request '.sp N' leaves N lines of blank space. N can be omitted
1081 (meaning skip a single line) or can be of the form Ni (for N inches) or
1082 Nc (for N centimeters). For example, the input:
1085 My thoughts on the subject
1088 leaves one and a half inches of space, followed by the line "My thoughts
1089 on the subject", followed by a single blank line (more measurement units
1090 are available, see *note Measurements::).
1092 Text lines can be centered by using the 'ce' request. The line after
1093 'ce' is centered (horizontally) on the page. To center more than one
1094 line, use '.ce N' (where N is the number of lines to center), followed
1095 by the N lines. To center many lines without counting them, type:
1101 The '.ce 0' request tells 'groff' to center zero more lines, in other
1102 words, stop centering.
1104 All of these requests cause a break; that is, they always start a new
1105 line. To start a new line without performing any other action, use
1109 File: groff.info, Node: Basics-Footnotes, Up: Basics
1111 (1) This section is derived from 'Writing Papers with nroff using
1112 -me' by Eric P. Allman.
1114 (2) If you need finer granularity of the vertical space, use the
1115 'pvs' request (*note Changing Type Sizes::).
1118 File: groff.info, Node: Common Features, Prev: Basics, Up: Tutorial for Macro Users
1123 'gtroff' provides very low-level operations for formatting a document.
1124 There are many common routine operations that are done in all documents.
1125 These common operations are written into "macros" and collected into a
1128 All macro packages provide certain common capabilities that fall into
1129 the following categories.
1134 * Sections and Chapters::
1135 * Headers and Footers::
1136 * Page Layout Adjustment::
1138 * Footnotes and Annotations::
1139 * Table of Contents::
1142 * Multiple Columns::
1143 * Font and Size Changes::
1144 * Predefined Strings::
1145 * Preprocessor Support::
1146 * Configuration and Customization::
1149 File: groff.info, Node: Paragraphs, Next: Sections and Chapters, Prev: Common Features, Up: Common Features
1154 One of the most common and most used capability is starting a paragraph.
1155 There are a number of different types of paragraphs, any of which can be
1156 initiated with macros supplied by the macro package. Normally,
1157 paragraphs start with a blank line and the first line indented, like the
1158 text in this manual. There are also block style paragraphs, which omit
1161 Some men look at constitutions with sanctimonious
1162 reverence, and deem them like the ark of the covenant, too
1163 sacred to be touched.
1165 And there are also indented paragraphs, which begin with a tag or label
1166 at the margin and the remaining text indented.
1168 one This is the first paragraph. Notice how the first
1169 line of the resulting paragraph lines up with the
1170 other lines in the paragraph.
1173 This paragraph had a long label. The first
1174 character of text on the first line does not line up
1175 with the text on second and subsequent lines,
1176 although they line up with each other.
1178 A variation of this is a bulleted list.
1180 . Bulleted lists start with a bullet. It is possible
1181 to use other glyphs instead of the bullet. In nroff
1182 mode using the ASCII character set for output, a dot
1183 is used instead of a real bullet.
1186 File: groff.info, Node: Sections and Chapters, Next: Headers and Footers, Prev: Paragraphs, Up: Common Features
1188 3.2.2 Sections and Chapters
1189 ---------------------------
1191 Most macro packages supply some form of section headers. The simplest
1192 kind is simply the heading on a line by itself in bold type. Others
1193 supply automatically numbered section heading or different heading
1194 styles at different levels. Some, more sophisticated, macro packages
1195 supply macros for starting chapters and appendices.
1198 File: groff.info, Node: Headers and Footers, Next: Page Layout Adjustment, Prev: Sections and Chapters, Up: Common Features
1200 3.2.3 Headers and Footers
1201 -------------------------
1203 Every macro package gives some way to manipulate the "headers" and
1204 "footers" (also called "titles") on each page. This is text put at the
1205 top and bottom of each page, respectively, which contain data like the
1206 current page number, the current chapter title, and so on. Its
1207 appearance is not affected by the running text. Some packages allow for
1208 different ones on the even and odd pages (for material printed in a book
1211 The titles are called "three-part titles", that is, there is a
1212 left-justified part, a centered part, and a right-justified part. An
1213 automatically generated page number may be put in any of these fields
1214 with the '%' character (see *note Page Layout::, for more details).
1217 File: groff.info, Node: Page Layout Adjustment, Next: Displays, Prev: Headers and Footers, Up: Common Features
1222 Most macro packages let the user specify top and bottom margins and
1223 other details about the appearance of the printed pages.
1226 File: groff.info, Node: Displays, Next: Footnotes and Annotations, Prev: Page Layout Adjustment, Up: Common Features
1231 "Displays" are sections of text to be set off from the body of the
1232 paper. Major quotes, tables, and figures are types of displays, as are
1233 all the examples used in this document.
1235 "Major quotes" are quotes that are several lines long, and hence are
1236 set in from the rest of the text without quote marks around them.
1238 A "list" is an indented, single-spaced, unfilled display. Lists
1239 should be used when the material to be printed should not be filled and
1240 justified like normal text, such as columns of figures or the examples
1243 A "keep" is a display of lines that are kept on a single page if
1244 possible. An example for a keep might be a diagram. Keeps differ from
1245 lists in that lists may be broken over a page boundary whereas keeps are
1248 "Floating keeps" move relative to the text. Hence, they are good for
1249 things that are referred to by name, such as "See figure 3". A floating
1250 keep appears at the bottom of the current page if it fits; otherwise, it
1251 appears at the top of the next page. Meanwhile, the surrounding text
1252 'flows' around the keep, thus leaving no blank areas.
1255 File: groff.info, Node: Footnotes and Annotations, Next: Table of Contents, Prev: Displays, Up: Common Features
1257 3.2.6 Footnotes and Annotations
1258 -------------------------------
1260 There are a number of requests to save text for later printing.
1262 "Footnotes" are printed at the bottom of the current page.
1264 "Delayed text" is very similar to a footnote except that it is
1265 printed when called for explicitly. This allows a list of references to
1266 appear (for example) at the end of each chapter, as is the convention in
1269 Most macro packages that supply this functionality also supply a
1270 means of automatically numbering either type of annotation.
1273 File: groff.info, Node: Table of Contents, Next: Indices, Prev: Footnotes and Annotations, Up: Common Features
1275 3.2.7 Table of Contents
1276 -----------------------
1278 "Tables of contents" are a type of delayed text having a tag (usually
1279 the page number) attached to each entry after a row of dots. The table
1280 accumulates throughout the paper until printed, usually after the paper
1281 has ended. Many macro packages provide the ability to have several
1282 tables of contents (e.g. a standard table of contents, a list of tables,
1286 File: groff.info, Node: Indices, Next: Paper Formats, Prev: Table of Contents, Up: Common Features
1291 While some macro packages use the term "index", none actually provide
1292 that functionality. The facilities they call indices are actually more
1293 appropriate for tables of contents.
1295 To produce a real index in a document, external tools like the
1296 'makeindex' program are necessary.
1299 File: groff.info, Node: Paper Formats, Next: Multiple Columns, Prev: Indices, Up: Common Features
1304 Some macro packages provide stock formats for various kinds of
1305 documents. Many of them provide a common format for the title and
1306 opening pages of a technical paper. The 'mm' macros in particular
1307 provide formats for letters and memoranda.
1310 File: groff.info, Node: Multiple Columns, Next: Font and Size Changes, Prev: Paper Formats, Up: Common Features
1312 3.2.10 Multiple Columns
1313 -----------------------
1315 Some macro packages (but not 'man') provide the ability to have two or
1316 more columns on a page.
1319 File: groff.info, Node: Font and Size Changes, Next: Predefined Strings, Prev: Multiple Columns, Up: Common Features
1321 3.2.11 Font and Size Changes
1322 ----------------------------
1324 The built-in font and size functions are not always intuitive, so all
1325 macro packages provide macros to make these operations simpler.
1328 File: groff.info, Node: Predefined Strings, Next: Preprocessor Support, Prev: Font and Size Changes, Up: Common Features
1330 3.2.12 Predefined Strings
1331 -------------------------
1333 Most macro packages provide various predefined strings for a variety of
1334 uses; examples are sub- and superscripts, printable dates, quotes and
1335 various special characters.
1338 File: groff.info, Node: Preprocessor Support, Next: Configuration and Customization, Prev: Predefined Strings, Up: Common Features
1340 3.2.13 Preprocessor Support
1341 ---------------------------
1343 All macro packages provide support for various preprocessors and may
1344 extend their functionality.
1346 For example, all macro packages mark tables (which are processed with
1347 'gtbl') by placing them between 'TS' and 'TE' macros. The 'ms' macro
1348 package has an option, '.TS H', that prints a caption at the top of a
1349 new page (when the table is too long to fit on a single page).
1352 File: groff.info, Node: Configuration and Customization, Prev: Preprocessor Support, Up: Common Features
1354 3.2.14 Configuration and Customization
1355 --------------------------------------
1357 Some macro packages provide means of customizing many of the details of
1358 how the package behaves. This ranges from setting the default type size
1359 to changing the appearance of section headers.
1362 File: groff.info, Node: Macro Packages, Next: gtroff Reference, Prev: Tutorial for Macro Users, Up: Top
1367 This chapter documents the main macro packages that come with 'groff'.
1369 Different main macro packages can't be used at the same time; for
1372 groff -m man foo.man -m ms bar.doc
1374 doesn't work. Note that option arguments are processed before
1375 non-option arguments; the above (failing) sample is thus reordered to
1377 groff -m man -m ms foo.man bar.doc
1389 File: groff.info, Node: man, Next: mdoc, Prev: Macro Packages, Up: Macro Packages
1394 This is the most popular and probably the most important macro package
1395 of 'groff'. It is easy to use, and a vast majority of manual pages are
1403 * Miscellaneous man macros::
1404 * Predefined man strings::
1405 * Preprocessors in man pages::
1406 * Optional man extensions::
1409 File: groff.info, Node: Man options, Next: Man usage, Prev: man, Up: man
1414 The command line format for using the 'man' macros with 'groff' is:
1416 groff -m man [ -rLL=LENGTH ] [ -rLT=LENGTH ] [ -rFT=DIST ]
1417 [ -rcR=1 ] [ -rC1 ] [ -rD1 ] [-rHY=FLAGS ]
1418 [ -rPNNN ] [ -rSXX ] [ -rXNNN ]
1419 [ -rIN=LENGTH ] [ -rSN=LENGTH ] [ FILES... ]
1421 It is possible to use '-man' instead of '-m man'.
1424 This option (the default if a TTY output device is used) creates a
1425 single, very long page instead of multiple pages. Use '-rcR=0' to
1429 If more than one manual page is given on the command line, number
1430 the pages continuously, rather than starting each at 1.
1433 Double-sided printing. Footers for even and odd pages are
1434 formatted differently.
1437 Set the position of the footer text to DIST. If positive, the
1438 distance is measured relative to the top of the page, otherwise it
1439 is relative to the bottom. The default is -0.5i.
1442 Set hyphenation flags. Possible values are 1 to hyphenate without
1443 restrictions, 2 to not hyphenate the last word on a page, 4 to not
1444 hyphenate the last two characters of a word, and 8 to not hyphenate
1445 the first two characters of a word. These values are additive; the
1449 Set the body text indentation to LENGTH. If not specified, the
1450 indentation defaults to 7n (7 characters) in nroff mode and 7.2n
1451 otherwise. For nroff, this value should always be an integer
1452 multiple of unit 'n' to get consistent indentation.
1455 Set line length to LENGTH. If not specified, the line length is
1456 set to respect any value set by a prior 'll' request (which _must_
1457 be in effect when the 'TH' macro is invoked), if this differs from
1458 the built-in default for the formatter; otherwise it defaults to
1459 78n in nroff mode (this is 78 characters per line) and 6.5i in
1460 troff mode.(1) (*note Man options-Footnote-1::)
1463 Set title length to LENGTH. If not specified, the title length
1464 defaults to the line length.
1467 Page numbering starts with NNN rather than with 1.
1470 Use XX (which can be 10, 11, or 12pt) as the base document font
1471 size instead of the default value of 10pt.
1474 Set the indentation for sub-subheadings to LENGTH. If not
1475 specified, the indentation defaults to 3n.
1478 After page NNN, number pages as NNNa, NNNb, NNNc, etc. For
1479 example, the option '-rX2' produces the following page numbers: 1,
1483 File: groff.info, Node: Man options-Footnotes, Up: Man options
1485 (1) Note that the use of a '.ll LENGTH' request to initialize the
1486 line length, prior to use of the 'TH' macro, is supported for backward
1487 compatibility with some versions of the 'man' program. _Always_ use the
1488 '-rLL=LENGTH' option, or an equivalent '.nr LL LENGTH' request, in
1489 preference to such a '.ll LENGTH' request. In particular, note that in
1490 nroff mode, the request '.ll 65n', (with any LENGTH expression that
1491 evaluates equal to 65n, i.e., the formatter's default line length in
1492 nroff mode), does _not_ set the line length to 65n (it is adjusted to
1493 the 'man' macro package's default setting of 78n), whereas the use of
1494 the '-rLL=65n' option, or the '.nr LL 65n' request _does_ establish a
1498 File: groff.info, Node: Man usage, Next: Man font macros, Prev: Man options, Up: man
1503 This section describes the available macros for manual pages. For
1504 further customization, put additional macros and requests into the file
1505 'man.local', which is loaded immediately after the 'man' package.
1507 -- Macro: .TH title section [extra1 [extra2 [extra3]]]
1508 Set the title of the man page to TITLE and the section to SECTION,
1509 which must have a value between 1 and 8. The value of SECTION may
1510 also have a string appended, e.g. '.pm', to indicate a specific
1511 subsection of the man pages.
1513 Both TITLE and SECTION are positioned at the left and right in the
1514 header line (with SECTION in parentheses immediately appended to
1515 TITLE. EXTRA1 is positioned in the middle of the footer line.
1516 EXTRA2 is positioned at the left in the footer line (or at the left
1517 on even pages and at the right on odd pages if double-sided
1518 printing is active). EXTRA3 is centered in the header line.
1520 For HTML and XHTML output, headers and footers are completely
1523 Additionally, this macro starts a new page; the new line number
1524 is 1 again (except if the '-rC1' option is given on the command
1525 line) - this feature is intended only for formatting multiple man
1526 pages; a single man page should contain exactly one 'TH' macro at
1527 the beginning of the file.
1529 -- Macro: .SH [heading]
1530 Set up an unnumbered section heading sticking out to the left.
1531 Prints out all the text following 'SH' up to the end of the line
1532 (or the text in the next line if there is no argument to 'SH') in
1533 bold face (or the font specified by the string 'HF'), one size
1534 larger than the base document size. Additionally, the left margin
1535 and the indentation for the following text is reset to its default
1538 -- Macro: .SS [heading]
1539 Set up an unnumbered (sub)section heading. Prints out all the text
1540 following 'SS' up to the end of the line (or the text in the next
1541 line if there is no argument to 'SS') in bold face (or the font
1542 specified by the string 'HF'), at the same size as the base
1543 document size. Additionally, the left margin and the indentation
1544 for the following text is reset to its default value.
1547 Set up an indented paragraph with label. The indentation is set to
1548 NNN if that argument is supplied (the default unit is 'n' if
1549 omitted), otherwise it is set to the previous indentation value
1550 specified with 'TP', 'IP', or 'HP' (or to the default value if none
1551 of them have been used yet).
1553 The first line of text following this macro is interpreted as a
1554 string to be printed flush-left, as it is appropriate for a label.
1555 It is not interpreted as part of a paragraph, so there is no
1556 attempt to fill the first line with text from the following input
1557 lines. Nevertheless, if the label is not as wide as the
1558 indentation the paragraph starts at the same line (but indented),
1559 continuing on the following lines. If the label is wider than the
1560 indentation the descriptive part of the paragraph begins on the
1561 line following the label, entirely indented. Note that neither
1562 font shape nor font size of the label is set to a default value; on
1563 the other hand, the rest of the text has default font settings.
1568 These macros are mutual aliases. Any of them causes a line break
1569 at the current position, followed by a vertical space downwards by
1570 the amount specified by the 'PD' macro. The font size and shape
1571 are reset to the default value (10pt roman if no '-rS' option is
1572 given on the command line). Finally, the current left margin and
1573 the indentation is restored.
1575 -- Macro: .IP [designator [nnn]]
1576 Set up an indented paragraph, using DESIGNATOR as a tag to mark its
1577 beginning. The indentation is set to NNN if that argument is
1578 supplied (default unit is 'n'), otherwise it is set to the previous
1579 indentation value specified with 'TP', 'IP', or 'HP' (or the
1580 default value if none of them have been used yet). Font size and
1581 face of the paragraph (but not the designator) are reset to their
1584 To start an indented paragraph with a particular indentation but
1585 without a designator, use '""' (two double quotes) as the first
1588 For example, to start a paragraph with bullets as the designator
1589 and 4 en indentation, write
1594 Set up a paragraph with hanging left indentation. The indentation
1595 is set to NNN if that argument is supplied (default unit is 'n'),
1596 otherwise it is set to the previous indentation value specified
1597 with 'TP', 'IP', or 'HP' (or the default value if non of them have
1598 been used yet). Font size and face are reset to their default
1602 Move the left margin to the right by the value NNN if specified
1603 (default unit is 'n'); otherwise it is set to the previous
1604 indentation value specified with 'TP', 'IP', or 'HP' (or to the
1605 default value if none of them have been used yet). The indentation
1606 value is then set to the default.
1608 Calls to the 'RS' macro can be nested.
1611 Move the left margin back to level NNN, restoring the previous left
1612 margin. If no argument is given, it moves one level back. The
1613 first level (i.e., no call to 'RS' yet) has number 1, and each call
1614 to 'RS' increases the level by 1.
1616 To summarize, the following macros cause a line break with the
1617 insertion of vertical space (which amount can be changed with the 'PD'
1618 macro): 'SH', 'SS', 'TP', 'LP' ('PP', 'P'), 'IP', and 'HP'.
1620 The macros 'RS' and 'RE' also cause a break but do not insert
1623 Finally, the macros 'SH', 'SS', 'LP' ('PP', 'P'), and 'RS' reset the
1624 indentation to its default value.
1627 File: groff.info, Node: Man font macros, Next: Miscellaneous man macros, Prev: Man usage, Up: man
1629 4.1.3 Macros to set fonts
1630 -------------------------
1632 The standard font is roman; the default text size is 10 point. If
1633 command line option '-rS=N' is given, use Npt as the default text size.
1635 -- Macro: .SM [text]
1636 Set the text on the same line or the text on the next line in a
1637 font that is one point size smaller than the default font.
1639 -- Macro: .SB [text]
1640 Set the text on the same line or the text on the next line in bold
1641 face font, one point size smaller than the default font.
1644 Set its arguments alternately in bold face and italic, without a
1645 space between the arguments. Thus,
1647 .BI this "word and" that
1649 produces "thisword andthat" with "this" and "that" in bold face,
1650 and "word and" in italics.
1653 Set its arguments alternately in italic and bold face, without a
1654 space between the arguments.
1657 Set its arguments alternately in roman and italic, without a space
1658 between the arguments.
1661 Set its arguments alternately in italic and roman, without a space
1662 between the arguments.
1665 Set its arguments alternately in bold face and roman, without a
1666 space between the arguments.
1669 Set its arguments alternately in roman and bold face, without a
1670 space between the arguments.
1673 Set TEXT in bold face. If no text is present on the line where the
1674 macro is called, then the text of the next line appears in bold
1678 Set TEXT in italic. If no text is present on the line where the
1679 macro is called, then the text of the next line appears in italic.
1682 File: groff.info, Node: Miscellaneous man macros, Next: Predefined man strings, Prev: Man font macros, Up: man
1684 4.1.4 Miscellaneous macros
1685 --------------------------
1687 The default indentation is 7.2n in troff mode and 7n in nroff mode
1688 except for 'grohtml', which ignores indentation.
1691 Set tabs every 0.5 inches. Since this macro is always executed
1692 during a call to the 'TH' macro, it makes sense to call it only if
1693 the tab positions have been changed.
1696 Adjust the empty space before a new paragraph (or section). The
1697 optional argument gives the amount of space (default unit is 'v');
1698 without parameter, the value is reset to its default value (1 line
1699 in nroff mode, 0.4v otherwise).
1701 This affects the macros 'SH', 'SS', 'TP', 'LP' (as well as 'PP' and
1702 'P'), 'IP', and 'HP'.
1704 The following two macros are included for BSD compatibility.
1706 -- Macro: .AT [system [release]]
1707 Alter the footer for use with AT&T manpages. This command exists
1708 only for compatibility; don't use it. The first argument SYSTEM
1712 7th Edition (the default)
1720 An optional second argument RELEASE to 'AT' specifies the release
1721 number (such as "System V Release 3").
1723 -- Macro: .UC [version]
1724 Alters the footer for use with BSD manpages. This command exists
1725 only for compatibility; don't use it. The argument can be:
1728 3rd Berkeley Distribution (the default)
1731 4th Berkeley Distribution
1734 4.2 Berkeley Distribution
1737 4.3 Berkeley Distribution
1740 4.4 Berkeley Distribution
1743 File: groff.info, Node: Predefined man strings, Next: Preprocessors in man pages, Prev: Miscellaneous man macros, Up: man
1745 4.1.5 Predefined strings
1746 ------------------------
1748 The following strings are defined:
1751 Switch back to the default font size.
1754 The typeface used for headings. The default is 'B'.
1757 The 'registered' sign.
1760 The 'trademark' sign.
1764 Left and right quote. This is equal to '\(lq' and '\(rq',
1768 File: groff.info, Node: Preprocessors in man pages, Next: Optional man extensions, Prev: Predefined man strings, Up: man
1770 4.1.6 Preprocessors in 'man' pages
1771 ----------------------------------
1773 If a preprocessor like 'gtbl' or 'geqn' is needed, it has become common
1774 usage to make the first line of the man page look like this:
1778 Note the single space character after the double quote. WORD consists
1779 of letters for the needed preprocessors: 'e' for 'geqn', 'r' for
1780 'grefer', 't' for 'gtbl'. Modern implementations of the 'man' program
1781 read this first line and automatically call the right preprocessor(s).
1784 File: groff.info, Node: Optional man extensions, Prev: Preprocessors in man pages, Up: man
1786 4.1.7 Optional 'man' extensions
1787 -------------------------------
1789 Use the file 'man.local' for local extensions to the 'man' macros or for
1792 Custom headers and footers
1793 ..........................
1795 In groff versions 1.18.2 and later, you can specify custom headers and
1796 footers by redefining the following macros in 'man.local'.
1799 Control the content of the headers. Normally, the header prints
1800 the command name and section number on either side, and the
1801 optional fifth argument to 'TH' in the center.
1804 Control the content of the footers. Normally, the footer prints
1805 the page number and the third and fourth arguments to 'TH'.
1807 Use the 'FT' number register to specify the footer position. The
1810 Ultrix-specific man macros
1811 ..........................
1813 The 'groff' source distribution includes a file named 'man.ultrix',
1814 containing macros compatible with the Ultrix variant of 'man'. Copy
1815 this file into 'man.local' (or use the 'mso' request to load it) to
1816 enable the following macros.
1822 Print subsequent text using the constant width (Courier) typeface.
1825 Begin a non-filled display.
1828 End a non-filled display started with 'Ds'.
1830 -- Macro: .EX [indent]
1831 Begin a non-filled display using the constant width (Courier)
1832 typeface. Use the optional INDENT argument to indent the display.
1835 End a non-filled display started with 'EX'.
1838 Set TEXT in Helvetica. If no text is present on the line where the
1839 macro is called, then the text of the next line appears in
1842 -- Macro: .GL [text]
1843 Set TEXT in Helvetica Oblique. If no text is present on the line
1844 where the macro is called, then the text of the next line appears
1845 in Helvetica Oblique.
1847 -- Macro: .HB [text]
1848 Set TEXT in Helvetica Bold. If no text is present on the line
1849 where the macro is called, then all text up to the next 'HB'
1850 appears in Helvetica Bold.
1852 -- Macro: .TB [text]
1855 -- Macro: .MS title sect [punct]
1856 Set a manpage reference in Ultrix format. The TITLE is in Courier
1857 instead of italic. Optional punctuation follows the section number
1858 without an intervening space.
1860 -- Macro: .NT ['C'] [title]
1861 Begin a note. Print the optional title, or the word "Note",
1862 centered on the page. Text following the macro makes up the body
1863 of the note, and is indented on both sides. If the first argument
1864 is 'C', the body of the note is printed centered (the second
1865 argument replaces the word "Note" if specified).
1868 End a note begun with 'NT'.
1870 -- Macro: .PN path [punct]
1871 Set the path name in constant width (Courier), followed by optional
1874 -- Macro: .Pn [punct] path [punct]
1875 If called with two arguments, identical to 'PN'. If called with
1876 three arguments, set the second argument in constant width
1877 (Courier), bracketed by the first and third arguments in the
1881 Switch to roman font and turn off any underlining in effect.
1884 Print the string '<RETURN>'.
1887 Start printing a change bar in the margin if the number '4' is
1888 specified. Otherwise, this macro does nothing.
1891 End printing the change bar begun by 'VS'.
1896 The following example 'man.local' file alters the 'SH' macro to add some
1897 extra vertical space before printing the heading. Headings are printed
1900 .\" Make the heading fonts Helvetica
1903 .\" Put more whitespace in front of headings.
1906 . if t .sp (u;\\n[PD]*2)
1911 File: groff.info, Node: mdoc, Next: ms, Prev: man, Up: Macro Packages
1916 See the 'groff_mdoc(7)' man page (type 'man groff_mdoc' at the command
1920 File: groff.info, Node: ms, Next: me, Prev: mdoc, Up: Macro Packages
1925 The '-ms' macros are suitable for reports, letters, books, user manuals,
1926 and so forth. The package provides macros for cover pages, section
1927 headings, paragraphs, lists, footnotes, pagination, and a table of
1933 * General ms Structure::
1934 * ms Document Control Registers::
1935 * ms Cover Page Macros::
1938 * Differences from AT&T ms::
1939 * Naming Conventions::
1942 File: groff.info, Node: ms Intro, Next: General ms Structure, Prev: ms, Up: ms
1944 4.3.1 Introduction to 'ms'
1945 --------------------------
1947 The original '-ms' macros were included with AT&T 'troff' as well as the
1948 'man' macros. While the 'man' package is intended for brief documents
1949 that can be read on-line as well as printed, the 'ms' macros are
1950 suitable for longer documents that are meant to be printed rather than
1953 The 'ms' macro package included with 'groff' is a complete, bottom-up
1954 re-implementation. Several macros (specific to AT&T or Berkeley) are
1955 not included, while several new commands are. *Note Differences from
1956 AT&T ms::, for more information.
1959 File: groff.info, Node: General ms Structure, Next: ms Document Control Registers, Prev: ms Intro, Up: ms
1961 4.3.2 General structure of an 'ms' document
1962 -------------------------------------------
1964 The 'ms' macro package expects a certain amount of structure, but not as
1965 much as packages such as 'man' or 'mdoc'.
1967 The simplest documents can begin with a paragraph macro (such as 'LP'
1968 or 'PP'), and consist of text separated by paragraph macros or even
1969 blank lines. Longer documents have a structure as follows:
1972 If you invoke the 'RP' (report) macro on the first line of the
1973 document, 'groff' prints the cover page information on its own
1974 page; otherwise it prints the information on the first page with
1975 your document text immediately following. Other document formats
1976 found in AT&T 'troff' are specific to AT&T or Berkeley, and are not
1977 supported in 'groff'.
1980 By setting number registers, you can change your document's type
1981 (font and size), margins, spacing, headers and footers, and
1982 footnotes. *Note ms Document Control Registers::, for more
1986 A cover page consists of a title, the author's name and
1987 institution, an abstract, and the date.(1) (*note General ms
1988 Structure-Footnote-1::) *Note ms Cover Page Macros::, for more
1992 Following the cover page is your document. You can use the 'ms'
1993 macros to write reports, letters, books, and so forth. The package
1994 is designed for structured documents, consisting of paragraphs
1995 interspersed with headings and augmented by lists, footnotes,
1996 tables, and other common constructs. *Note ms Body Text::, for
2000 Longer documents usually include a table of contents, which you can
2001 invoke by placing the 'TC' macro at the end of your document. The
2002 'ms' macros have minimal indexing facilities, consisting of the
2003 'IX' macro, which prints an entry on standard error. Printing the
2004 table of contents at the end is necessary since 'groff' is a
2005 single-pass text formatter, thus it cannot determine the page
2006 number of each section until that section has actually been set and
2007 printed. Since 'ms' output is intended for hardcopy, you can
2008 manually relocate the pages containing the table of contents
2009 between the cover page and the body text after printing.
2012 File: groff.info, Node: General ms Structure-Footnotes, Up: General ms Structure
2014 (1) Actually, only the title is required.
2017 File: groff.info, Node: ms Document Control Registers, Next: ms Cover Page Macros, Prev: General ms Structure, Up: ms
2019 4.3.3 Document control registers
2020 --------------------------------
2022 The following is a list of document control number registers. For the
2023 sake of consistency, set registers related to margins at the beginning
2024 of your document, or just after the 'RP' macro. You can set other
2025 registers later in your document, but you should keep them together at
2026 the beginning to make them easy to find and edit as necessary.
2032 Defines the page offset (i.e., the left margin). There is no
2033 explicit right margin setting; the combination of the 'PO' and 'LL'
2034 registers implicitly define the right margin width.
2036 Effective: next page.
2041 Defines the line length (i.e., the width of the body text).
2043 Effective: next paragraph.
2048 Defines the title length (i.e., the header and footer width). This
2049 is usually the same as 'LL', but not necessarily.
2051 Effective: next paragraph.
2056 Defines the header margin height at the top of the page.
2058 Effective: next page.
2063 Defines the footer margin height at the bottom of the page.
2065 Effective: next page.
2073 Defines the point size of the body text. If the value is larger
2074 than or equal to 1000, divide it by 1000 to get a fractional point
2075 size. For example, '.nr PS 10250' sets the document's point size
2078 Effective: next paragraph.
2083 Defines the space between lines (line height plus leading). If the
2084 value is larger than or equal to 1000, divide it by 1000 to get a
2085 fractional point size. Due to backwards compatibility, 'VS' must
2086 be smaller than 40000 (this is 40.0p).
2088 Effective: next paragraph.
2092 -- Register: \n[PSINCR]
2093 Defines an increment in point size, which is applied to section
2094 headings at nesting levels below the value specified in 'GROWPS'.
2095 The value of 'PSINCR' should be specified in points, with the p
2096 scaling factor, and may include a fractional component; for
2097 example, '.nr PSINCR 1.5p' sets a point size increment of 1.5p.
2099 Effective: next section heading.
2103 -- Register: \n[GROWPS]
2104 Defines the heading level below which the point size increment set
2105 by 'PSINCR' becomes effective. Section headings at and above the
2106 level specified by 'GROWPS' are printed at the point size set by
2107 'PS'; for each level below the value of 'GROWPS', the point size is
2108 increased in steps equal to the value of 'PSINCR'. Setting
2109 'GROWPS' to any value less than 2 disables the incremental heading
2112 Effective: next section heading.
2117 Defines the hyphenation level. 'HY' sets safely the value of the
2118 low-level 'hy' register. Setting the value of 'HY' to 0 is
2119 equivalent to using the 'nh' request.
2121 Effective: next paragraph.
2125 -- Register: \n[FAM]
2126 Defines the font family used to typeset the document.
2128 Effective: next paragraph.
2130 Default: as defined in the output device.
2136 Defines the initial indentation of a ('PP' macro) paragraph.
2138 Effective: next paragraph.
2143 Defines the space between paragraphs.
2145 Effective: next paragraph.
2150 Defines the indentation on both sides of a quoted ('QP' macro)
2153 Effective: next paragraph.
2157 -- Register: \n[PORPHANS]
2158 Defines the minimum number of initial lines of any paragraph that
2159 should be kept together, to avoid orphan lines at the bottom of a
2160 page. If a new paragraph is started close to the bottom of a page,
2161 and there is insufficient space to accommodate 'PORPHANS' lines
2162 before an automatic page break, then the page break is forced,
2163 before the start of the paragraph.
2165 Effective: next paragraph.
2169 -- Register: \n[HORPHANS]
2170 Defines the minimum number of lines of the following paragraph that
2171 should be kept together with any section heading introduced by the
2172 'NH' or 'SH' macros. If a section heading is placed close to the
2173 bottom of a page, and there is insufficient space to accommodate
2174 both the heading and at least 'HORPHANS' lines of the following
2175 paragraph, before an automatic page break, then the page break is
2176 forced before the heading.
2178 Effective: next paragraph.
2186 Defines the length of a footnote.
2188 Effective: next footnote.
2190 Default: '\n[LL]' * 5 / 6.
2193 Defines the footnote indentation.
2195 Effective: next footnote.
2200 The footnote format:
2202 Print the footnote number as a superscript; indent the
2206 Print the number followed by a period (like 1.) and indent the
2210 Like 1, without an indentation.
2213 Like 1, but print the footnote number as a hanging paragraph.
2215 Effective: next footnote.
2219 -- Register: \n[FPS]
2220 Defines the footnote point size. If the value is larger than or
2221 equal to 1000, divide it by 1000 to get a fractional point size.
2223 Effective: next footnote.
2225 Default: '\n[PS]' - 2.
2227 -- Register: \n[FVS]
2228 Defines the footnote vertical spacing. If the value is larger than
2229 or equal to 1000, divide it by 1000 to get a fractional point size.
2231 Effective: next footnote.
2233 Default: '\n[FPS]' + 2.
2235 -- Register: \n[FPD]
2236 Defines the footnote paragraph spacing.
2238 Effective: next footnote.
2240 Default: '\n[PD]' / 2.
2242 Miscellaneous Number Registers
2243 ..............................
2245 -- Register: \n[MINGW]
2246 Defines the minimum width between columns in a multi-column
2249 Effective: next page.
2254 Sets the vertical spacing before and after a display, a 'tbl'
2255 table, an 'eqn' equation, or a 'pic' image.
2257 Effective: next paragraph.
2262 File: groff.info, Node: ms Cover Page Macros, Next: ms Body Text, Prev: ms Document Control Registers, Up: ms
2264 4.3.4 Cover page macros
2265 -----------------------
2267 Use the following macros to create a cover page for your document in the
2270 -- Macro: .RP ['no']
2271 Specifies the report format for your document. The report format
2272 creates a separate cover page. The default action (no 'RP' macro)
2273 is to print a subset of the cover page on page 1 of your document.
2275 If you use the word 'no' as an optional argument, 'groff' prints a
2276 title page but does not repeat any of the title page information
2277 (title, author, abstract, etc.) on page 1 of the document.
2280 (P-one) Prints the header on page 1. The default is to suppress
2284 (optional) Prints the current date, or the arguments to the macro
2285 if any, on the title page (if specified) and in the footers. This
2286 is the default for 'nroff'.
2289 (optional) Prints the current date, or the arguments to the macro
2290 if any, on the title page (if specified) but not in the footers.
2291 This is the default for 'troff'.
2294 Specifies the document title. 'groff' collects text following the
2295 'TL' macro into the title, until reaching the author name or
2299 Specifies the author's name, which appears on the line (or lines)
2300 immediately following. You can specify multiple authors as
2306 University of West Bumblefuzz
2310 Monolithic Corporation
2315 Specifies the author's institution. You can specify multiple
2316 institutions in the same way that you specify multiple authors.
2318 -- Macro: .AB ['no']
2319 Begins the abstract. The default is to print the word ABSTRACT,
2320 centered and in italics, above the text of the abstract. The word
2321 'no' as an optional argument suppresses this heading.
2326 The following is example mark-up for a title page.
2330 The Inevitability of Code Bloat
2331 in Commercial and Free Software
2335 University of West Bumblefuzz
2337 This report examines the long-term growth
2338 of the code bases in two large, popular software
2339 packages; the free Emacs and the commercial
2341 While differences appear in the type or order
2342 of features added, due to the different
2343 methodologies used, the results are the same
2346 The free software approach is shown to be
2347 superior in that while free software can
2348 become as bloated as commercial offerings,
2349 free software tends to have fewer serious
2350 bugs and the added features are in line with
2354 ... the rest of the paper follows ...
2357 File: groff.info, Node: ms Body Text, Next: ms Page Layout, Prev: ms Cover Page Macros, Up: ms
2362 This section describes macros used to mark up the body of your document.
2363 Examples include paragraphs, sections, and other groups.
2367 * Paragraphs in ms::
2369 * Highlighting in ms::
2371 * Indentation values in ms::
2373 * ms Displays and Keeps::
2375 * Example multi-page table::
2379 File: groff.info, Node: Paragraphs in ms, Next: Headings in ms, Prev: ms Body Text, Up: ms Body Text
2384 The following paragraph types are available.
2387 Sets a paragraph with an initial indentation.
2390 Sets a paragraph without an initial indentation.
2393 Sets a paragraph that is indented at both left and right margins.
2394 The effect is identical to the HTML '<BLOCKQUOTE>' element. The
2395 next paragraph or heading returns margins to normal.
2398 Sets a paragraph whose lines are indented, except for the first
2399 line. This is a Berkeley extension.
2401 The following markup uses all four paragraph macros.
2404 Cases used in the study
2406 The following software and versions were
2407 considered for this report.
2409 For commercial software, we chose
2410 .B "Microsoft Word for Windows" ,
2411 starting with version 1.0 through the
2412 current version (Word 2000).
2414 For free software, we chose
2416 from its first appearance as a standalone
2417 editor through the current version (v20).
2418 See [Bloggs 2002] for details.
2420 Franklin's Law applied to software:
2421 software expands to outgrow both
2422 RAM and disk space over time.
2427 .I "Everyone's a Critic" ,
2428 Underground Press, March 2002.
2429 A definitive work that answers all questions
2430 and criticisms about the quality and usability of
2433 The 'PORPHANS' register (*note ms Document Control Registers::)
2434 operates in conjunction with each of these macros, to inhibit the
2435 printing of orphan lines at the bottom of any page.
2438 File: groff.info, Node: Headings in ms, Next: Highlighting in ms, Prev: Paragraphs in ms, Up: ms Body Text
2443 Use headings to create a hierarchical structure for your document. The
2444 'ms' macros print headings in *bold*, using the same font family and
2445 point size as the body text.
2447 The following describes the heading macros:
2449 -- Macro: .NH curr-level
2450 -- Macro: .NH S level0 ...
2451 Numbered heading. The argument is either a numeric argument to
2452 indicate the level of the heading, or the letter 'S' followed by
2453 numeric arguments to set the heading level explicitly.
2455 If you specify heading levels out of sequence, such as invoking
2456 '.NH 3' after '.NH 1', 'groff' prints a warning on standard error.
2459 -- String: \*[SN-DOT]
2460 -- String: \*[SN-NO-DOT]
2461 After invocation of 'NH', the assigned section number is made
2462 available in the strings 'SN-DOT' (as it appears in a printed
2463 section heading with default formatting, followed by a terminating
2464 period), and 'SN-NO-DOT' (with the terminating period omitted).
2465 The string 'SN' is also defined, as an alias for 'SN-DOT'; if
2466 preferred, you may redefine it as an alias for 'SN-NO-DOT', by
2467 including the initialization
2470 at any time *before* you would like the change to take effect.
2472 -- String: \*[SN-STYLE]
2473 You may control the style used to print section numbers, within
2474 numbered section headings, by defining an appropriate alias for the
2475 string 'SN-STYLE'. The default style, in which the printed section
2476 number is followed by a terminating period, is obtained by defining
2479 .als SN-STYLE SN-DOT
2481 If you prefer to omit the terminating period, from section numbers
2482 appearing in numbered section headings, you may define the alias
2484 .als SN-STYLE SN-NO-DOT
2486 Any such change in section numbering style becomes effective from
2487 the next use of '.NH', following redefinition of the alias for
2490 -- Macro: .SH [match-level]
2491 Unnumbered subheading.
2493 The optional MATCH-LEVEL argument is a GNU extension. It is a
2494 number indicating the level of the heading, in a manner analogous
2495 to the CURR-LEVEL argument to '.NH'. Its purpose is to match the
2496 point size, at which the heading is printed, to the size of a
2497 numbered heading at the same level, when the 'GROWPS' and 'PSINCR'
2498 heading size adjustment mechanism is in effect. *Note ms Document
2499 Control Registers::.
2501 The 'HORPHANS' register (*note ms Document Control Registers::)
2502 operates in conjunction with the 'NH' and 'SH' macros, to inhibit the
2503 printing of orphaned section headings at the bottom of any page.
2506 File: groff.info, Node: Highlighting in ms, Next: Lists in ms, Prev: Headings in ms, Up: ms Body Text
2508 4.3.5.3 Highlighting
2509 ....................
2511 The 'ms' macros provide a variety of methods to highlight or emphasize
2514 -- Macro: .B [txt [post [pre]]]
2515 Sets its first argument in *bold type*. If you specify a second
2516 argument, 'groff' prints it in the previous font after the bold
2517 text, with no intervening space (this allows you to set punctuation
2518 after the highlighted text without highlighting the punctuation).
2519 Similarly, it prints the third argument (if any) in the previous
2520 font *before* the first argument. For example,
2526 If you give this macro no arguments, 'groff' prints all text
2527 following in bold until the next highlighting, paragraph, or
2530 -- Macro: .R [txt [post [pre]]]
2531 Sets its first argument in roman (or regular) type. It operates
2532 similarly to the 'B' macro otherwise.
2534 -- Macro: .I [txt [post [pre]]]
2535 Sets its first argument in _italic type_. It operates similarly to
2536 the 'B' macro otherwise.
2538 -- Macro: .CW [txt [post [pre]]]
2539 Sets its first argument in a 'constant width face'. It operates
2540 similarly to the 'B' macro otherwise.
2542 -- Macro: .BI [txt [post [pre]]]
2543 Sets its first argument in bold italic type. It operates similarly
2544 to the 'B' macro otherwise.
2547 Prints its argument and draws a box around it. If you want to box
2548 a string that contains spaces, use a digit-width space ('\0').
2550 -- Macro: .UL [txt [post]]
2551 Prints its first argument with an underline. If you specify a
2552 second argument, 'groff' prints it in the previous font after the
2553 underlined text, with no intervening space.
2556 Prints all text following in larger type (two points larger than
2557 the current point size) until the next font size, highlighting,
2558 paragraph, or heading macro. You can specify this macro multiple
2559 times to enlarge the point size as needed.
2562 Prints all text following in smaller type (two points smaller than
2563 the current point size) until the next type size, highlighting,
2564 paragraph, or heading macro. You can specify this macro multiple
2565 times to reduce the point size as needed.
2568 Prints all text following in the normal point size (that is, the
2569 value of the 'PS' register).
2573 Text enclosed with '\*{' and '\*}' is printed as a superscript.
2576 File: groff.info, Node: Lists in ms, Next: Indentation values in ms, Prev: Highlighting in ms, Up: ms Body Text
2581 The 'IP' macro handles duties for all lists.
2583 -- Macro: .IP [marker [width]]
2584 The MARKER is usually a bullet glyph ('\[bu]') for unordered lists,
2585 a number (or auto-incrementing number register) for numbered lists,
2586 or a word or phrase for indented (glossary-style) lists.
2588 The WIDTH specifies the indentation for the body of each list item;
2589 its default unit is 'n'. Once specified, the indentation remains
2590 the same for all list items in the document until specified again.
2592 The 'PORPHANS' register (*note ms Document Control Registers::)
2593 operates in conjunction with the 'IP' macro, to inhibit the
2594 printing of orphaned list markers at the bottom of any page.
2596 The following is an example of a bulleted list.
2616 The following is an example of a numbered list.
2637 Note the use of the auto-incrementing number register in this
2640 The following is an example of a glossary-style list.
2642 A glossary-style list:
2644 Two or more attorneys.
2646 Firearms, preferably
2654 A glossary-style list:
2657 Two or more attorneys.
2659 guns Firearms, preferably large-caliber.
2662 Gotta pay for those lawyers and guns!
2664 In the last example, the 'IP' macro places the definition on the same
2665 line as the term if it has enough space; otherwise, it breaks to the
2666 next line and starts the definition below the term. This may or may not
2667 be the effect you want, especially if some of the definitions break and
2668 some do not. The following examples show two possible ways to force a
2671 The first workaround uses the 'br' request to force a break after
2672 printing the term or label.
2674 A glossary-style list:
2676 Two or more attorneys.
2679 Firearms, preferably large-caliber.
2681 Gotta pay for those lawyers and guns!
2683 The second workaround uses the '\p' escape to force the break. Note
2684 the space following the escape; this is important. If you omit the
2685 space, 'groff' prints the first word on the same line as the term or
2686 label (if it fits) *then* breaks the line.
2688 A glossary-style list:
2690 Two or more attorneys.
2692 \p Firearms, preferably large-caliber.
2694 Gotta pay for those lawyers and guns!
2696 To set nested lists, use the 'RS' and 'RE' macros. *Note Indentation
2697 values in ms::, for more information.
2727 File: groff.info, Node: Indentation values in ms, Next: Tabstops in ms, Prev: Lists in ms, Up: ms Body Text
2729 4.3.5.5 Indentation values
2730 ..........................
2732 In many situations, you may need to indentation a section of text while
2733 still wrapping and filling. *Note Lists in ms::, for an example of
2738 These macros begin and end an indented section. The 'PI' register
2739 controls the amount of indentation, allowing the indented text to
2740 line up under hanging and indented paragraphs.
2742 *Note ms Displays and Keeps::, for macros to indentation and turn off
2746 File: groff.info, Node: Tabstops in ms, Next: ms Displays and Keeps, Prev: Indentation values in ms, Up: ms Body Text
2751 Use the 'ta' request to define tab stops as needed. *Note Tabs and
2755 Use this macro to reset the tab stops to the default for 'ms'
2756 (every 5n). You can redefine the 'TA' macro to create a different
2757 set of default tab stops.
2760 File: groff.info, Node: ms Displays and Keeps, Next: ms Insertions, Prev: Tabstops in ms, Up: ms Body Text
2762 4.3.5.7 Displays and keeps
2763 ..........................
2765 Use displays to show text-based examples or figures (such as code
2768 Displays turn off filling, so lines of code are displayed as-is
2769 without inserting 'br' requests in between each line. Displays can be
2770 "kept" on a single page, or allowed to break across pages.
2775 Left-justified display. The '.DS L' call generates a page break,
2776 if necessary, to keep the entire display on one page. The 'LD'
2777 macro allows the display to break across pages. The 'DE' macro
2783 Indents the display as defined by the 'DI' register. The '.DS I'
2784 call generates a page break, if necessary, to keep the entire
2785 display on one page. The 'ID' macro allows the display to break
2786 across pages. The 'DE' macro ends the display.
2791 Sets a block-centered display: the entire display is
2792 left-justified, but indented so that the longest line in the
2793 display is centered on the page. The '.DS B' call generates a page
2794 break, if necessary, to keep the entire display on one page. The
2795 'BD' macro allows the display to break across pages. The 'DE'
2796 macro ends the display.
2801 Sets a centered display: each line in the display is centered. The
2802 '.DS C' call generates a page break, if necessary, to keep the
2803 entire display on one page. The 'CD' macro allows the display to
2804 break across pages. The 'DE' macro ends the display.
2809 Right-justifies each line in the display. The '.DS R' call
2810 generates a page break, if necessary, to keep the entire display on
2811 one page. The 'RD' macro allows the display to break across pages.
2812 The 'DE' macro ends the display.
2816 These two macros were formerly provided as aliases for 'DS' and
2817 'DE', respectively. They have been removed, and should no longer
2818 be used. The original implementations of 'DS' and 'DE' are
2819 retained, and should be used instead. X11 documents that actually
2820 use 'Ds' and 'De' always load a specific macro file from the X11
2821 distribution ('macros.t') that provides proper definitions for the
2824 On occasion, you may want to "keep" other text together on a page.
2825 For example, you may want to keep two paragraphs together, or a
2826 paragraph that refers to a table (or list, or other item) immediately
2827 following. The 'ms' macros provide the 'KS' and 'KE' macros for this
2832 The 'KS' macro begins a block of text to be kept on a single page,
2833 and the 'KE' macro ends the block.
2837 Specifies a "floating keep"; if the keep cannot fit on the current
2838 page, 'groff' holds the contents of the keep and allows text
2839 following the keep (in the source file) to fill in the remainder of
2840 the current page. When the page breaks, whether by an explicit
2841 'bp' request or by reaching the end of the page, 'groff' prints the
2842 floating keep at the top of the new page. This is useful for
2843 printing large graphics or tables that do not need to appear
2844 exactly where specified.
2846 You can also use the 'ne' request to force a page break if there is
2847 not enough vertical space remaining on the page.
2849 Use the following macros to draw a box around a section of text (such
2854 Marks the beginning and ending of text that is to have a box drawn
2855 around it. The 'B1' macro begins the box; the 'B2' macro ends it.
2856 Text in the box is automatically placed in a diversion (keep).
2859 File: groff.info, Node: ms Insertions, Next: Example multi-page table, Prev: ms Displays and Keeps, Up: ms Body Text
2861 4.3.5.8 Tables, figures, equations, and references
2862 ..................................................
2864 The 'ms' macros support the standard 'groff' preprocessors: 'tbl',
2865 'pic', 'eqn', and 'refer'. You mark text meant for preprocessors by
2866 enclosing it in pairs of tags as follows.
2870 Denotes a table, to be processed by the 'tbl' preprocessor. The
2871 optional argument 'H' to 'TS' instructs 'groff' to create a running
2872 header with the information up to the 'TH' macro. 'groff' prints
2873 the header at the beginning of the table; if the table runs onto
2874 another page, 'groff' prints the header on the next page as well.
2878 Denotes a graphic, to be processed by the 'pic' preprocessor. You
2879 can create a 'pic' file by hand, using the AT&T 'pic' manual
2880 available on the Web as a reference, or by using a graphics program
2883 -- Macro: .EQ [align]
2885 Denotes an equation, to be processed by the 'eqn' preprocessor.
2886 The optional ALIGN argument can be 'C', 'L', or 'I' to center (the
2887 default), left-justify, or indent the equation.
2891 Denotes a reference, to be processed by the 'refer' preprocessor.
2892 The GNU 'refer(1)' man page provides a comprehensive reference to
2893 the preprocessor and the format of the bibliographic database.
2897 * Example multi-page table::
2900 File: groff.info, Node: Example multi-page table, Next: ms Footnotes, Prev: ms Insertions, Up: ms Body Text
2902 4.3.5.9 An example multi-page table
2903 ...................................
2905 The following is an example of how to set up a table that may print
2906 across two or more pages.
2911 Text ...of heading...
2916 ... the rest of the table follows...
2921 File: groff.info, Node: ms Footnotes, Prev: Example multi-page table, Up: ms Body Text
2926 The 'ms' macro package has a flexible footnote system. You can specify
2927 either numbered footnotes or symbolic footnotes (that is, using a marker
2928 such as a dagger symbol).
2931 Specifies the location of a numbered footnote marker in the text.
2935 Specifies the text of the footnote. The default action is to
2936 create a numbered footnote; you can create a symbolic footnote by
2937 specifying a "mark" glyph (such as '\[dg]' for the dagger glyph) in
2938 the body text and as an argument to the 'FS' macro, followed by the
2939 text of the footnote and the 'FE' macro.
2941 You can control how 'groff' prints footnote numbers by changing the
2942 value of the 'FF' register. *Note ms Document Control Registers::.
2944 Footnotes can be safely used within keeps and displays, but you
2945 should avoid using numbered footnotes within floating keeps. You can
2946 set a second '\**' marker between a '\**' and its corresponding '.FS'
2947 entry; as long as each 'FS' macro occurs _after_ the corresponding '\**'
2948 and the occurrences of '.FS' are in the same order as the corresponding
2949 occurrences of '\**'.
2952 File: groff.info, Node: ms Page Layout, Next: Differences from AT&T ms, Prev: ms Body Text, Up: ms
2957 The default output from the 'ms' macros provides a minimalist page
2958 layout: it prints a single column, with the page number centered at the
2959 top of each page. It prints no footers.
2961 You can change the layout by setting the proper number registers and
2966 * ms Headers and Footers::
2968 * ms Multiple Columns::
2970 * ms Strings and Special Characters::
2973 File: groff.info, Node: ms Headers and Footers, Next: ms Margins, Prev: ms Page Layout, Up: ms Page Layout
2975 4.3.6.1 Headers and footers
2976 ...........................
2978 For documents that do not distinguish between odd and even pages, set
2979 the following strings:
2984 Sets the left, center, and right headers.
2989 Sets the left, center, and right footers.
2991 For documents that need different information printed in the even and
2992 odd pages, use the following macros:
2994 -- Macro: .OH 'left'center'right'
2995 -- Macro: .EH 'left'center'right'
2996 -- Macro: .OF 'left'center'right'
2997 -- Macro: .EF 'left'center'right'
2998 The 'OH' and 'EH' macros define headers for the odd and even pages;
2999 the 'OF' and 'EF' macros define footers for the odd and even pages.
3000 This is more flexible than defining the individual strings.
3002 You can replace the quote (''') marks with any character not
3003 appearing in the header or footer text.
3005 To specify custom header and footer processing, redefine the
3011 The 'PT' macro defines a custom header; the 'BT' macro defines a
3012 custom footer. These macros must handle odd/even/first page
3013 differences if necessary.
3015 The 'HD' macro defines additional header processing to take place
3016 after executing the 'PT' macro.
3019 File: groff.info, Node: ms Margins, Next: ms Multiple Columns, Prev: ms Headers and Footers, Up: ms Page Layout
3024 You control margins using a set of number registers. *Note ms Document
3025 Control Registers::, for details.
3028 File: groff.info, Node: ms Multiple Columns, Next: ms TOC, Prev: ms Margins, Up: ms Page Layout
3030 4.3.6.3 Multiple columns
3031 ........................
3033 The 'ms' macros can set text in as many columns as do reasonably fit on
3034 the page. The following macros are available; all of them force a page
3035 break if a multi-column mode is already set. However, if the current
3036 mode is single-column, starting a multi-column mode does _not_ force a
3045 -- Macro: .MC [width [gutter]]
3046 Multi-column mode. If you specify no arguments, it is equivalent
3047 to the '2C' macro. Otherwise, WIDTH is the width of each column
3048 and GUTTER is the space between columns. The 'MINGW' number
3049 register controls the default gutter width.
3052 File: groff.info, Node: ms TOC, Next: ms Strings and Special Characters, Prev: ms Multiple Columns, Up: ms Page Layout
3054 4.3.6.4 Creating a table of contents
3055 ....................................
3057 The facilities in the 'ms' macro package for creating a table of
3058 contents are semi-automated at best. Assuming that you want the table
3059 of contents to consist of the document's headings, you need to repeat
3060 those headings wrapped in 'XS' and 'XE' macros.
3062 -- Macro: .XS [page]
3063 -- Macro: .XA [page]
3065 These macros define a table of contents or an individual entry in
3066 the table of contents, depending on their use. The macros are very
3067 simple; they cannot indent a heading based on its level. The
3068 easiest way to work around this is to add tabs to the table of
3069 contents string. The following is an example:
3087 You can manually create a table of contents by beginning with the
3088 'XS' macro for the first entry, specifying the page number for that
3089 entry as the argument to 'XS'. Add subsequent entries using the
3090 'XA' macro, specifying the page number for that entry as the
3091 argument to 'XA'. The following is an example:
3096 A Brief History of the Universe
3098 Details of Galactic Formation
3102 -- Macro: .TC ['no']
3103 Prints the table of contents on a new page, setting the page number
3104 to *i* (Roman lowercase numeral one). You should usually place
3105 this macro at the end of the file, since 'groff' is a single-pass
3106 formatter and can only print what has been collected up to the
3107 point that the 'TC' macro appears.
3109 The optional argument 'no' suppresses printing the title specified
3110 by the string register 'TOC'.
3112 -- Macro: .PX ['no']
3113 Prints the table of contents on a new page, using the current page
3114 numbering sequence. Use this macro to print a manually-generated
3115 table of contents at the beginning of your document.
3117 The optional argument 'no' suppresses printing the title specified
3118 by the string register 'TOC'.
3120 The 'Groff and Friends HOWTO' includes a 'sed' script that
3121 automatically inserts 'XS' and 'XE' macro entries after each heading in
3124 Altering the 'NH' macro to automatically build the table of contents
3125 is perhaps initially more difficult, but would save a great deal of time
3126 in the long run if you use 'ms' regularly.
3129 File: groff.info, Node: ms Strings and Special Characters, Prev: ms TOC, Up: ms Page Layout
3131 4.3.6.5 Strings and Special Characters
3132 ......................................
3134 The 'ms' macros provide the following predefined strings. You can
3135 change the string definitions to help in creating documents in languages
3138 -- String: \*[REFERENCES]
3139 Contains the string printed at the beginning of the references
3140 (bibliography) page. The default is 'References'.
3142 -- String: \*[ABSTRACT]
3143 Contains the string printed at the beginning of the abstract. The
3144 default is 'ABSTRACT'.
3147 Contains the string printed at the beginning of the table of
3150 -- String: \*[MONTH1]
3151 -- String: \*[MONTH2]
3152 -- String: \*[MONTH3]
3153 -- String: \*[MONTH4]
3154 -- String: \*[MONTH5]
3155 -- String: \*[MONTH6]
3156 -- String: \*[MONTH7]
3157 -- String: \*[MONTH8]
3158 -- String: \*[MONTH9]
3159 -- String: \*[MONTH10]
3160 -- String: \*[MONTH11]
3161 -- String: \*[MONTH12]
3162 Prints the full name of the month in dates. The default is
3163 'January', 'February', etc.
3165 The following special characters are available(1) (*note ms Strings
3166 and Special Characters-Footnote-1::):
3173 Prints typographer's quotes in troff, and plain quotes in nroff.
3174 '\*Q' is the left quote and '\*U' is the right quote.
3176 Improved accent marks are available in the 'ms' macros.
3179 Specify this macro at the beginning of your document to enable
3180 extended accent marks and special characters. This is a Berkeley
3183 To use the accent marks, place them *after* the character being
3186 Note that groff's native support for accents is superior to the
3187 following definitions.
3189 The following accent marks are available after invoking the 'AM'
3222 The following are standalone characters available after invoking the
3226 Upside-down question mark.
3229 Upside-down exclamation point.
3253 Lowercase æ ligature.
3256 Uppercase Æ ligature.
3259 File: groff.info, Node: ms Strings and Special Characters-Footnotes, Up: ms Strings and Special Characters
3261 (1) For an explanation what special characters are see *note Special
3265 File: groff.info, Node: Differences from AT&T ms, Next: Naming Conventions, Prev: ms Page Layout, Up: ms
3267 4.3.7 Differences from AT&T 'ms'
3268 --------------------------------
3270 This section lists the (minor) differences between the 'groff -ms'
3271 macros and AT&T 'troff -ms' macros.
3273 * The internals of 'groff -ms' differ from the internals of AT&T
3274 'troff -ms'. Documents that depend upon implementation details of
3275 AT&T 'troff -ms' may not format properly with 'groff -ms'.
3277 * The general error-handling policy of 'groff -ms' is to detect and
3278 report errors, rather than silently to ignore them.
3280 * 'groff -ms' does not work in compatibility mode (this is, with the
3283 * There is no special support for typewriter-like devices.
3285 * 'groff -ms' does not provide cut marks.
3287 * Multiple line spacing is not supported. Use a larger vertical
3290 * Some UNIX 'ms' documentation says that the 'CW' and 'GW' number
3291 registers can be used to control the column width and gutter width,
3292 respectively. These number registers are not used in 'groff -ms'.
3294 * Macros that cause a reset (paragraphs, headings, etc.) may change
3295 the indentation. Macros that change the indentation do not
3296 increment or decrement the indentation, but rather set it
3297 absolutely. This can cause problems for documents that define
3298 additional macros of their own. The solution is to use not the
3299 'in' request but instead the 'RS' and 'RE' macros.
3301 * To make 'groff -ms' use the default page offset (which also
3302 specifies the left margin), the 'PO' register must stay undefined
3303 until the first '-ms' macro is evaluated. This implies that 'PO'
3304 should not be used early in the document, unless it is changed
3305 also: Remember that accessing an undefined register automatically
3309 This number register is set to 1 by the 'groff -ms' macros, but it
3310 is not used by the 'AT&T' 'troff -ms' macros. Documents that need
3311 to determine whether they are being formatted with 'AT&T' 'troff
3312 -ms' or 'groff -ms' should use this number register.
3314 Emulations of a few ancient Bell Labs macros can be re-enabled by
3315 calling the otherwise undocumented 'SC' section-header macro. Calling
3316 'SC' enables 'UC' for marking up a product or application name, and the
3317 pair 'P1'/'P2' for surrounding code example displays.
3319 These are not enabled by default because (a) they were not
3320 documented, in the original 'ms' manual, and (b) the 'P1' and 'UC'
3321 macros collide with different macros with the same names in the Berkeley
3324 These 'groff' emulations are sufficient to give back the 1976
3325 Kernighan & Cherry paper 'Typsetting Mathematics - User's Guide' its
3326 section headings, and restore some text that had gone missing as
3327 arguments of undefined macros. No warranty express or implied is given
3328 as to how well the typographic details these produce match the original
3333 * Missing ms Macros::
3334 * Additional ms Macros::
3337 File: groff.info, Node: Missing ms Macros, Next: Additional ms Macros, Prev: Differences from AT&T ms, Up: Differences from AT&T ms
3339 4.3.7.1 'troff' macros not appearing in 'groff'
3340 ...............................................
3342 Macros missing from 'groff -ms' are cover page macros specific to Bell
3343 Labs and Berkeley. The macros known to be missing are:
3346 Technical memorandum; a cover sheet style
3349 Internal memorandum; a cover sheet style
3352 Memo for record; a cover sheet style
3355 Memo for file; a cover sheet style
3358 Engineer's notes; a cover sheet style
3361 Computing Science Tech Report; a cover sheet style
3367 Cover sheet information
3373 File: groff.info, Node: Additional ms Macros, Prev: Missing ms Macros, Up: Differences from AT&T ms
3375 4.3.7.2 'groff' macros not appearing in AT&T 'troff'
3376 ....................................................
3378 The 'groff -ms' macros have a few minor extensions compared to the AT&T
3382 Improved accent marks. *Note ms Strings and Special Characters::,
3386 Indented display. The default behavior of AT&T 'troff -ms' was to
3387 indent; the 'groff' default prints displays flush left with the
3391 Print text in 'constant width' (Courier) font.
3394 Indexing term (printed on standard error). You can write a script
3395 to capture and process an index generated in this manner.
3397 The following additional number registers appear in 'groff -ms':
3399 -- Register: \n[MINGW]
3400 Specifies a minimum space between columns (for multi-column
3401 output); this takes the place of the 'GW' register that was
3402 documented but apparently not implemented in AT&T 'troff'.
3404 Several new string registers are available as well. You can change
3405 these to handle (for example) the local language. *Note ms Strings and
3406 Special Characters::, for details.
3409 File: groff.info, Node: Naming Conventions, Prev: Differences from AT&T ms, Up: ms
3411 4.3.8 Naming Conventions
3412 ------------------------
3414 The following conventions are used for names of macros, strings and
3415 number registers. External names available to documents that use the
3416 'groff -ms' macros contain only uppercase letters and digits.
3418 Internally the macros are divided into modules; naming conventions
3421 * Names used only within one module are of the form MODULE'*'NAME.
3423 * Names used outside the module in which they are defined are of the
3426 * Names associated with a particular environment are of the form
3427 ENVIRONMENT':'NAME; these are used only within the 'par' module.
3429 * NAME does not have a module prefix.
3431 * Constructed names used to implement arrays are of the form
3434 Thus the groff ms macros reserve the following names:
3436 * Names containing the characters '*', '@', and ':'.
3438 * Names containing only uppercase letters and digits.
3441 File: groff.info, Node: me, Next: mm, Prev: ms, Up: Macro Packages
3446 See the 'meintro.me' and 'meref.me' documents in groff's 'doc'
3450 File: groff.info, Node: mm, Next: mom, Prev: me, Up: Macro Packages
3455 See the 'groff_mm(7)' man page (type 'man groff_mm' at the command
3459 File: groff.info, Node: mom, Prev: mm, Up: Macro Packages
3464 See the 'groff_mom(7)' man page (type 'man groff_mom' at the command
3465 line), which gives a short overview and a link to its extensive
3466 documentation in HTML format.
3469 File: groff.info, Node: gtroff Reference, Next: Preprocessors, Prev: Macro Packages, Up: Top
3471 5 'gtroff' Reference
3472 ********************
3474 This chapter covers *all* of the facilities of 'gtroff'. Users of macro
3475 packages may skip it if not interested in details.
3483 * Embedded Commands::
3485 * Manipulating Filling and Adjusting::
3486 * Manipulating Hyphenation::
3487 * Manipulating Spacing::
3489 * Character Translations::
3490 * Troff and Nroff Mode::
3495 * Fonts and Symbols::
3498 * Conditionals and Loops::
3501 * Drawing Requests::
3505 * Suppressing output::
3508 * Postprocessor Access::
3510 * Gtroff Internals::
3512 * Implementation Differences::
3515 File: groff.info, Node: Text, Next: Measurements, Prev: gtroff Reference, Up: gtroff Reference
3520 'gtroff' input files contain text with control commands interspersed
3521 throughout. But, even without control codes, 'gtroff' still does
3522 several things with the input text:
3524 * filling and adjusting
3526 * adding additional space after sentences
3530 * inserting implicit line breaks
3534 * Filling and Adjusting::
3538 * Implicit Line Breaks::
3539 * Input Conventions::
3543 File: groff.info, Node: Filling and Adjusting, Next: Hyphenation, Prev: Text, Up: Text
3545 5.1.1 Filling and Adjusting
3546 ---------------------------
3548 When 'gtroff' reads text, it collects words from the input and fits as
3549 many of them together on one output line as it can. This is known as
3552 Once 'gtroff' has a "filled" line, it tries to "adjust" it. This
3553 means it widens the spacing between words until the text reaches the
3554 right margin (in the default adjustment mode). Extra spaces between
3555 words are preserved, but spaces at the end of lines are ignored. Spaces
3556 at the front of a line cause a "break" (breaks are explained in *note
3557 Implicit Line Breaks::).
3559 *Note Manipulating Filling and Adjusting::.
3562 File: groff.info, Node: Hyphenation, Next: Sentences, Prev: Filling and Adjusting, Up: Text
3567 Since the odds are not great for finding a set of words, for every
3568 output line, which fit nicely on a line without inserting excessive
3569 amounts of space between words, 'gtroff' hyphenates words so that it can
3570 justify lines without inserting too much space between words. It uses
3571 an internal hyphenation algorithm (a simplified version of the algorithm
3572 used within TeX) to indicate which words can be hyphenated and how to do
3573 so. When a word is hyphenated, the first part of the word is added to
3574 the current filled line being output (with an attached hyphen), and the
3575 other portion is added to the next line to be filled.
3577 *Note Manipulating Hyphenation::.
3580 File: groff.info, Node: Sentences, Next: Tab Stops, Prev: Hyphenation, Up: Text
3585 Although it is often debated, some typesetting rules say there should be
3586 different amounts of space after various punctuation marks. For
3587 example, the 'Chicago typsetting manual' says that a period at the end
3588 of a sentence should have twice as much space following it as would a
3589 comma or a period as part of an abbreviation.
3591 'gtroff' does this by flagging certain characters (normally '!', '?',
3592 and '.') as "end-of-sentence" characters. When 'gtroff' encounters one
3593 of these characters at the end of a line, it appends a normal space
3594 followed by a "sentence space" in the formatted output. (This justifies
3595 one of the conventions mentioned in *note Input Conventions::.)
3597 In addition, the following characters and symbols are treated
3598 transparently while handling end-of-sentence characters: '"', ''', ')',
3599 ']', '*', '\[dg]', '\[rq]', and '\[cq]'.
3601 See the 'cflags' request in *note Using Symbols::, for more details.
3603 To prevent the insertion of extra space after an end-of-sentence
3604 character (at the end of a line), append '\&'.
3607 File: groff.info, Node: Tab Stops, Next: Implicit Line Breaks, Prev: Sentences, Up: Text
3612 'gtroff' translates "tabulator characters", also called "tabs" (normally
3613 code point ASCII '0x09' or EBCDIC '0x05'), in the input into movements
3614 to the next tabulator stop. These tab stops are initially located every
3615 half inch across the page. Using this, simple tables can be made
3616 easily. However, it can often be deceptive as the appearance (and
3617 width) of the text on a terminal and the results from 'gtroff' can vary
3620 Also, a possible sticking point is that lines beginning with tab
3621 characters are still filled, again producing unexpected results. For
3622 example, the following input
3631 *Note Tabs and Fields::.
3634 File: groff.info, Node: Implicit Line Breaks, Next: Input Conventions, Prev: Tab Stops, Up: Text
3636 5.1.5 Implicit Line Breaks
3637 --------------------------
3639 An important concept in 'gtroff' is the "break". When a break occurs,
3640 'gtroff' outputs the partially filled line (unjustified), and resumes
3641 collecting and filling text on the next output line.
3643 There are several ways to cause a break in 'gtroff'. A blank line
3644 not only causes a break, but it also outputs a one-line vertical space
3645 (effectively a blank line). Note that this behaviour can be modified
3646 with the blank line macro request 'blm'. *Note Blank Line Traps::.
3648 A line that begins with a space causes a break and the space is
3649 output at the beginning of the next line. Note that this space isn't
3650 adjusted, even in fill mode; however, the behaviour can be modified with
3651 the leading spaces macro request 'lsm'. *Note Leading Spaces Traps::.
3653 The end of file also causes a break - otherwise the last line of the
3654 document may vanish!
3656 Certain requests also cause breaks, implicitly or explicitly. This
3657 is discussed in *note Manipulating Filling and Adjusting::.
3660 File: groff.info, Node: Input Conventions, Next: Input Encodings, Prev: Implicit Line Breaks, Up: Text
3662 5.1.6 Input Conventions
3663 -----------------------
3665 Since 'gtroff' does filling automatically, it is traditional in 'groff'
3666 not to try and type things in as nicely formatted paragraphs. These are
3667 some conventions commonly used when typing 'gtroff' text:
3669 * Break lines after punctuation, particularly at the end of a
3670 sentence and in other logical places. Keep separate phrases on
3671 lines by themselves, as entire phrases are often added or deleted
3674 * Try to keep lines less than 40-60 characters, to allow space for
3675 inserting more text.
3677 * Do not try to do any formatting in a WYSIWYG manner (i.e., don't
3678 try using spaces to get proper indentation).
3681 File: groff.info, Node: Input Encodings, Prev: Input Conventions, Up: Text
3683 5.1.7 Input Encodings
3684 ---------------------
3686 Currently, the following input encodings are available.
3689 This input encoding works only on EBCDIC platforms (and vice versa,
3690 the other input encodings don't work with EBCDIC); the file
3691 'cp1047.tmac' is by default loaded at start-up.
3694 This is the default input encoding on non-EBCDIC platforms; the
3695 file 'latin1.tmac' is loaded at start-up.
3698 To use this encoding, either say '.mso latin2.tmac' at the very
3699 beginning of your document or use '-mlatin2' as a command line
3700 argument for 'groff'.
3703 For Turkish. Either say '.mso latin9.tmac' at the very beginning
3704 of your document or use '-mlatin9' as a command line argument for
3708 This encoding is intended (at least in Europe) to replace latin-1
3709 encoding. The main difference to latin-1 is that latin-9 contains
3710 the Euro character. To use this encoding, either say
3711 '.mso latin9.tmac' at the very beginning of your document or use
3712 '-mlatin9' as a command line argument for 'groff'.
3714 Note that it can happen that some input encoding characters are not
3715 available for a particular output device. For example, saying
3717 groff -Tlatin1 -mlatin9 ...
3719 fails if you use the Euro character in the input. Usually, this
3720 limitation is present only for devices that have a limited set of output
3721 glyphs (e.g. '-Tascii' and '-Tlatin1'); for other devices it is usually
3722 sufficient to install proper fonts that contain the necessary glyphs.
3724 Due to the importance of the Euro glyph in Europe, the groff package
3725 now comes with a POSTSCRIPT font called 'freeeuro.pfa', which provides
3726 various glyph shapes for the Euro. In other words, latin-9 encoding is
3727 supported for the '-Tps' device out of the box (latin-2 isn't).
3729 By its very nature, '-Tutf8' supports all input encodings; '-Tdvi'
3730 has support for both latin-2 and latin-9 if the command line '-mec' is
3731 used also to load the file 'ec.tmac' (which flips to the EC fonts).
3734 File: groff.info, Node: Measurements, Next: Expressions, Prev: Text, Up: gtroff Reference
3739 'gtroff' (like many other programs) requires numeric parameters to
3740 specify various measurements. Most numeric parameters(1) (*note
3741 Measurements-Footnote-1::) may have a "measurement unit" attached.
3742 These units are specified as a single character that immediately follows
3743 the number or expression. Each of these units are understood, by
3744 'gtroff', to be a multiple of its "basic unit". So, whenever a
3745 different measurement unit is specified 'gtroff' converts this into its
3746 "basic units". This basic unit, represented by a 'u', is a device
3747 dependent measurement, which is quite small, ranging from 1/75th to
3748 1/72000th of an inch. The values may be given as fractional numbers;
3749 however, fractional basic units are always rounded to integers.
3751 Some of the measurement units are completely independent of any of
3752 the current settings (e.g. type size) of 'gtroff'.
3755 Inches. An antiquated measurement unit still in use in certain
3756 backwards countries with incredibly low-cost computer equipment.
3757 One inch is equal to 2.54cm.
3760 Centimeters. One centimeter is equal to 0.3937in.
3763 Points. This is a typesetter's measurement used for measure type
3764 size. It is 72 points to an inch.
3767 Pica. Another typesetting measurement. 6 Picas to an inch (and
3768 12 points to a pica).
3772 *Note Fractional Type Sizes::, for a discussion of these units.
3775 Fractions. Value is 65536. *Note Colors::, for usage.
3777 The other measurements understood by 'gtroff' depend on settings
3778 currently in effect in 'gtroff'. These are very useful for specifying
3779 measurements that should look proper with any size of text.
3782 Ems. This unit is equal to the current font size in points. So
3783 called because it is _approximately_ the width of the letter 'm' in
3787 Ens. In 'groff', this is half of an em.
3790 Vertical space. This is equivalent to the current line spacing.
3791 *Note Sizes::, for more information about this.
3801 File: groff.info, Node: Measurements-Footnotes, Up: Measurements
3803 (1) those that specify vertical or horizontal motion or a type size
3806 File: groff.info, Node: Default Units, Prev: Measurements, Up: Measurements
3811 Many requests take a default unit. While this can be helpful at times,
3812 it can cause strange errors in some expressions. For example, the line
3813 length request expects em units. Here are several attempts to get a
3814 line length of 3.5 inches and their results:
3823 Everything is converted to basic units first. In the above example it
3824 is assumed that 1i equals 240u, and 1m equals 10p (thus 1m equals 33u).
3825 The value 7i/2 is first handled as 7i/2m, then converted to 1680u/66u,
3826 which is 25u, and this is approximately 0.1i. As can be seen, a scaling
3827 indicator after a closing parenthesis is simply ignored.
3829 Thus, the safest way to specify measurements is to always attach a
3830 scaling indicator. If you want to multiply or divide by a certain
3831 scalar value, use 'u' as the unit for that value.
3834 File: groff.info, Node: Expressions, Next: Identifiers, Prev: Measurements, Up: gtroff Reference
3839 'gtroff' has most arithmetic operators common to other languages:
3841 * Arithmetic: '+' (addition), '-' (subtraction), '/' (division), '*'
3842 (multiplication), '%' (modulo).
3844 'gtroff' only provides integer arithmetic. The internal type used
3845 for computing results is 'int', which is usually a 32bit signed
3848 * Comparison: '<' (less than), '>' (greater than), '<=' (less than or
3849 equal), '>=' (greater than or equal), '=' (equal), '==' (the same
3852 * Logical: '&' (logical and), ':' (logical or).
3854 * Unary operators: '-' (negating, i.e. changing the sign), '+' (just
3855 for completeness; does nothing in expressions), '!' (logical not;
3856 this works only within 'if' and 'while' requests).(1) (*note
3857 Expressions-Footnote-1::) See below for the use of unary operators
3860 The logical not operator, as described above, works only within
3861 'if' and 'while' requests. Furthermore, it may appear only at the
3862 beginning of an expression, and negates the entire expression.
3863 Attempting to insert the '!' operator within the expression results
3864 in a 'numeric expression expected' warning. This maintains
3865 compatibility with old versions of 'troff'.
3871 .\" This does not work as expected
3872 .if (\n[X])&(!\n[Y]) .nop X only
3874 .\" Use this construct instead
3875 .if (\n[X]=1)&(\n[Y]=0) .nop X only
3877 * Extrema: '>?' (maximum), '<?' (minimum).
3883 .nr z (\n[x] >? \n[y])
3885 The register 'z' now contains 5.
3887 * Scaling: '(C;E)'. Evaluate E using C as the default scaling
3888 indicator. If C is missing, ignore scaling indicators in the
3891 Parentheses may be used as in any other language. However, in
3892 'gtroff' they are necessary to ensure order of evaluation. 'gtroff' has
3893 no operator precedence; expressions are evaluated left to right. This
3894 means that 'gtroff' evaluates '3+5*4' as if it were parenthesized like
3895 '(3+5)*4', not as '3+(5*4)', as might be expected.
3897 For many requests that cause a motion on the page, the unary
3898 operators '+' and '-' work differently if leading an expression. They
3899 then indicate a motion relative to the current position (down or up,
3902 Similarly, a leading '|' operator indicates an absolute position.
3903 For vertical movements, it specifies the distance from the top of the
3904 page; for horizontal movements, it gives the distance from the beginning
3905 of the _input_ line.
3907 '+' and '-' are also treated differently by the following requests
3908 and escapes: 'bp', 'in', 'll', 'lt', 'nm', 'nr', 'pl', 'pn', 'po', 'ps',
3909 'pvs', 'rt', 'ti', '\H', '\R', and '\s'. Here, leading plus and minus
3910 signs indicate increments and decrements.
3912 *Note Setting Registers::, for some examples.
3914 -- Escape: \B'anything'
3915 Return 1 if ANYTHING is a valid numeric expression; or 0 if
3916 ANYTHING is empty or not a valid numeric expression.
3918 Due to the way arguments are parsed, spaces are not allowed in
3919 expressions, unless the entire expression is surrounded by parentheses.
3921 *Note Request and Macro Arguments::, and *note Conditionals and
3925 File: groff.info, Node: Expressions-Footnotes, Up: Expressions
3927 (1) Note that, for example, '!(-1)' evaluates to 'true' because
3928 'gtroff' treats both negative numbers and zero as 'false'.
3931 File: groff.info, Node: Identifiers, Next: Embedded Commands, Prev: Expressions, Up: gtroff Reference
3936 Like any other language, 'gtroff' has rules for properly formed
3937 "identifiers". In 'gtroff', an identifier can be made up of almost any
3938 printable character, with the exception of the following characters:
3940 * Whitespace characters (spaces, tabs, and newlines).
3942 * Backspace (ASCII '0x08' or EBCDIC '0x16') and character code
3945 * The following input characters are invalid and are ignored if
3946 'groff' runs on a machine based on ASCII, causing a warning message
3947 of type 'input' (see *note Debugging::, for more details): '0x00',
3948 '0x0B', '0x0D'-'0x1F', '0x80'-'0x9F'.
3950 And here are the invalid input characters if 'groff' runs on an
3951 EBCDIC host: '0x00', '0x08', '0x09', '0x0B', '0x0D'-'0x14',
3952 '0x17'-'0x1F', '0x30'-'0x3F'.
3954 Currently, some of these reserved codepoints are used internally,
3955 thus making it non-trivial to extend 'gtroff' to cover Unicode or
3956 other character sets and encodings that use characters of these
3959 Note that invalid characters are removed before parsing; an
3960 identifier 'foo', followed by an invalid character, followed by
3961 'bar' is treated as 'foobar'.
3963 For example, any of the following is valid.
3971 Note that identifiers longer than two characters with a closing bracket
3972 (']') in its name can't be accessed with escape sequences that expect an
3973 identifier as a parameter. For example, '\[foo]]' accesses the glyph
3974 'foo', followed by ']', whereas '\C'foo]'' really asks for glyph 'foo]'.
3976 To avoid problems with the 'refer' preprocessor, macro names should
3977 not start with '[' or ']'. Due to backwards compatibility, everything
3978 after '.[' and '.]' is handled as a special argument to 'refer'. For
3979 example, '.[foo' makes 'refer' to start a reference, using 'foo' as a
3982 -- Escape: \A'ident'
3983 Test whether an identifier IDENT is valid in 'gtroff'. It expands
3984 to the character 1 or 0 according to whether its argument (usually
3985 delimited by quotes) is or is not acceptable as the name of a
3986 string, macro, diversion, number register, environment, or font.
3987 It returns 0 if no argument is given. This is useful for looking
3988 up user input in some sort of associative table.
3993 *Note Escapes::, for details on parameter delimiting characters.
3995 Identifiers in 'gtroff' can be any length, but, in some contexts,
3996 'gtroff' needs to be told where identifiers end and text begins (and in
3997 different ways depending on their length):
4001 * Two characters. Must be prefixed with '(' in some situations.
4003 * Arbitrary length ('gtroff' only). Must be bracketed with '['
4004 and ']' in some situations. Any length identifier can be put in
4007 Unlike many other programming languages, undefined identifiers are
4008 silently ignored or expanded to nothing. When 'gtroff' finds an
4009 undefined identifier, it emits a warning, doing the following:
4011 * If the identifier is a string, macro, or diversion, 'gtroff'
4012 defines it as empty.
4014 * If the identifier is a number register, 'gtroff' defines it with a
4017 *Note Warnings::., *note Interpolating Registers::, and *note
4020 Note that macros, strings, and diversions share the same name space.
4034 As can be seen in the previous example, 'gtroff' reuses the identifier
4035 'xxx', changing it from a macro to a diversion. No warning is emitted!
4036 The contents of the first macro definition is lost.
4038 *Note Interpolating Registers::, and *note Strings::.
4041 File: groff.info, Node: Embedded Commands, Next: Registers, Prev: Identifiers, Up: gtroff Reference
4043 5.5 Embedded Commands
4044 =====================
4046 Most documents need more functionality beyond filling, adjusting and
4047 implicit line breaking. In order to gain further functionality,
4048 'gtroff' allows commands to be embedded into the text, in two ways.
4050 The first is a "request" that takes up an entire line, and does some
4051 large-scale operation (e.g. break lines, start new pages).
4053 The other is an "escape" that can be usually embedded anywhere in the
4054 text; most requests can accept it even as an argument. Escapes
4055 generally do more minor operations like sub- and superscripts, print a
4065 File: groff.info, Node: Requests, Next: Macros, Prev: Embedded Commands, Up: Embedded Commands
4070 A request line begins with a control character, which is either a single
4071 quote (''', the "no-break control character") or a period ('.', the
4072 normal "control character"). These can be changed; see *note Character
4073 Translations::, for details. After this there may be optional tabs or
4074 spaces followed by an identifier, which is the name of the request.
4075 This may be followed by any number of space-separated arguments (_no_
4078 Since a control character followed by whitespace only is ignored, it
4079 is common practice to use this feature for structuring the source code
4080 of documents or macro packages.
4091 Another possibility is to use the blank line macro request 'blm' by
4092 assigning an empty macro to it.
4096 .blm do-nothing \" activate blank line macro
4107 .blm \" deactivate blank line macro
4109 *Note Blank Line Traps::.
4111 To begin a line with a control character without it being
4112 interpreted, precede it with '\&'. This represents a zero width space,
4113 which means it does not affect the output.
4115 In most cases the period is used as a control character. Several
4116 requests cause a break implicitly; using the single quote control
4117 character prevents this.
4119 -- Register: \n[.br]
4120 A read-only number register, which is set to 1 if a macro is called
4121 with the normal control character (as defined with the 'cc'
4122 request), and set to 0 otherwise.
4124 This allows to reliably modify requests.
4129 . ie \\n[.br] .bp*orig
4134 Using this register outside of a macro makes no sense (it always
4135 returns zero in such cases).
4137 If a macro is called as a string (this is, using '\*'), the value
4138 of the '.br' register is inherited from the calling macro.
4142 * Request and Macro Arguments::
4145 File: groff.info, Node: Request and Macro Arguments, Prev: Requests, Up: Requests
4147 5.5.1.1 Request and Macro Arguments
4148 ...................................
4150 Arguments to requests and macros are processed much like the shell: The
4151 line is split into arguments according to spaces.(1) (*note Request and
4152 Macro Arguments-Footnote-1::)
4154 An argument to a macro that is intended to contain spaces can either
4155 be enclosed in double quotes, or have the spaces "escaped" with
4156 backslashes. This is _not_ true for requests.
4158 Here are a few examples for a hypothetical macro 'uh':
4160 .uh The Mouse Problem
4161 .uh "The Mouse Problem"
4162 .uh The\ Mouse\ Problem
4164 The first line is the 'uh' macro being called with 3 arguments, 'The',
4165 'Mouse', and 'Problem'. The latter two have the same effect of calling
4166 the 'uh' macro with one argument, 'The Mouse Problem'.(2) (*note
4167 Request and Macro Arguments-Footnote-2::)
4169 A double quote that isn't preceded by a space doesn't start a macro
4170 argument. If not closing a string, it is printed literally.
4174 .xxx a" "b c" "de"fg"
4176 has the arguments 'a"', 'b c', 'de', and 'fg"'. Don't rely on this
4179 There are two possibilities to get a double quote reliably.
4181 * Enclose the whole argument with double quotes and use two
4182 consecutive double quotes to represent a single one. This
4183 traditional solution has the disadvantage that double quotes don't
4184 survive argument expansion again if called in compatibility mode
4185 (using the '-C' option of 'groff'):
4188 . tm xx: `\\$1' `\\$2' `\\$3'
4190 . yy "\\$1" "\\$2" "\\$3"
4193 . tm yy: `\\$1' `\\$2' `\\$3'
4195 .xx A "test with ""quotes""" .
4196 => xx: `A' `test with "quotes"' `.'
4197 => yy: `A' `test with ' `quotes""'
4199 If not in compatibility mode, you get the expected result
4201 xx: `A' `test with "quotes"' `.'
4202 yy: `A' `test with "quotes"' `.'
4204 since 'gtroff' preserves the input level.
4206 * Use the double quote glyph '\(dq'. This works with and without
4207 compatibility mode enabled since 'gtroff' doesn't convert '\(dq'
4208 back to a double quote input character.
4210 Note that this method won't work with UNIX 'troff' in general since
4211 the glyph 'dq' isn't defined normally.
4213 Double quotes in the 'ds' request are handled differently. *Note
4214 Strings::, for more details.
4217 File: groff.info, Node: Request and Macro Arguments-Footnotes, Up: Request and Macro Arguments
4219 (1) Plan 9's 'troff' implementation also allows tabs for argument
4220 separation - 'gtroff' intentionally doesn't support this.
4222 (2) The last solution, i.e., using escaped spaces, is "classical" in
4223 the sense that it can be found in most 'troff' documents. Nevertheless,
4224 it is not optimal in all situations, since '\ ' inserts a fixed-width,
4225 non-breaking space character that can't stretch. 'gtroff' provides a
4226 different command '\~' to insert a stretchable, non-breaking space.
4229 File: groff.info, Node: Macros, Next: Escapes, Prev: Requests, Up: Embedded Commands
4234 'gtroff' has a "macro" facility for defining a series of lines that can
4235 be invoked by name. They are called in the same manner as requests -
4236 arguments also may be passed basically in the same manner.
4238 *Note Writing Macros::, and *note Request and Macro Arguments::.
4241 File: groff.info, Node: Escapes, Prev: Macros, Up: Embedded Commands
4246 Escapes may occur anywhere in the input to 'gtroff'. They usually begin
4247 with a backslash and are followed by a single character, which indicates
4248 the function to be performed. The escape character can be changed; see
4249 *note Character Translations::.
4251 Escape sequences that require an identifier as a parameter accept
4252 three possible syntax forms.
4254 * The next single character is the identifier.
4256 * If this single character is an opening parenthesis, take the
4257 following two characters as the identifier. Note that there is no
4258 closing parenthesis after the identifier.
4260 * If this single character is an opening bracket, take all characters
4261 until a closing bracket as the identifier.
4269 Other escapes may require several arguments and/or some special
4270 format. In such cases the argument is traditionally enclosed in single
4271 quotes (and quotes are always used in this manual for the definitions of
4272 escape sequences). The enclosed text is then processed according to
4273 what that escape expects. Example:
4277 Note that the quote character can be replaced with any other
4278 character that does not occur in the argument (even a newline or a space
4279 character) in the following escapes: '\o', '\b', and '\X'. This makes
4290 possible, but it is better not to use this feature to avoid confusion.
4292 The following escapes sequences (which are handled similarly to
4293 characters since they don't take a parameter) are also allowed as
4294 delimiters: '\%', '\ ', '\|', '\^', '\{', '\}', '\'', '\`', '\-', '\_',
4295 '\!', '\?', '\)', '\/', '\,', '\&', '\:', '\~', '\0', '\a', '\c', '\d',
4296 '\e', '\E', '\p', '\r', '\t', and '\u'. Again, don't use these if
4299 No newline characters as delimiters are allowed in the following
4300 escapes: '\A', '\B', '\Z', '\C', and '\w'.
4302 Finally, the escapes '\D', '\h', '\H', '\l', '\L', '\N', '\R', '\s',
4303 '\S', '\v', and '\x' can't use the following characters as delimiters:
4305 * The digits '0'-'9'.
4307 * The (single-character) operators '+-/*%<>=&:().'.
4309 * The space, tab, and newline characters.
4311 * All escape sequences except '\%', '\:', '\{', '\}', '\'', '\`',
4312 '\-', '\_', '\!', '\/', '\c', '\e', and '\p'.
4314 To have a backslash (actually, the current escape character) appear
4315 in the output several escapes are defined: '\\', '\e' or '\E'. These
4316 are very similar, and only differ with respect to being used in macros
4317 or diversions. *Note Character Translations::, for an exact description
4320 *Note Implementation Differences::, *note Copy-in Mode::, and *note
4321 Diversions::, *note Identifiers::, for more information.
4328 File: groff.info, Node: Comments, Prev: Escapes, Up: Escapes
4333 Probably one of the most(1) (*note Comments-Footnote-1::) common forms
4334 of escapes is the comment.
4337 Start a comment. Everything to the end of the input line is
4340 This may sound simple, but it can be tricky to keep the comments
4341 from interfering with the appearance of the final output.
4343 If the escape is to the right of some text or a request, that
4344 portion of the line is ignored, but the space leading up to it is
4345 noticed by 'gtroff'. This only affects the 'ds' and 'as' request
4348 One possibly irritating idiosyncracy is that tabs must not be used
4349 to line up comments. Tabs are not treated as whitespace between
4350 the request and macro arguments.
4352 A comment on a line by itself is treated as a blank line, because
4353 after eliminating the comment, that is all that remains:
4365 To avoid this, it is common to start the line with '.\"', which
4366 causes the line to be treated as an undefined request and thus
4369 Another commenting scheme seen sometimes is three consecutive
4370 single quotes (''''') at the beginning of a line. This works, but
4371 'gtroff' gives a warning about an undefined macro (namely ''''),
4372 which is harmless, but irritating.
4375 To avoid all this, 'gtroff' has a new comment mechanism using the
4376 '\#' escape. This escape works the same as '\"' except that the
4377 newline is also ignored:
4389 -- Request: .ig [end]
4390 Ignore all input until 'gtroff' encounters the macro named '.'END
4391 on a line by itself (or '..' if END is not specified). This is
4392 useful for commenting out large blocks of text:
4396 This is part of a large block
4397 of text that has been
4398 temporarily(?) commented out.
4400 We can restore it simply by removing
4401 the .ig request and the ".." at the
4404 More text text text...
4408 text text text... More text text text...
4410 Note that the commented-out block of text does not cause a break.
4412 The input is read in copy-mode; auto-incremented registers _are_
4413 affected (*note Auto-increment::).
4416 File: groff.info, Node: Comments-Footnotes, Up: Comments
4418 (1) Unfortunately, this is a lie. But hopefully future 'gtroff'
4419 hackers will believe it ':-)'
4422 File: groff.info, Node: Registers, Next: Manipulating Filling and Adjusting, Prev: Embedded Commands, Up: gtroff Reference
4427 Numeric variables in 'gtroff' are called "registers". There are a
4428 number of built-in registers, supplying anything from the date to
4429 details of formatting parameters.
4431 *Note Identifiers::, for details on register identifiers.
4435 * Setting Registers::
4436 * Interpolating Registers::
4438 * Assigning Formats::
4439 * Built-in Registers::
4442 File: groff.info, Node: Setting Registers, Next: Interpolating Registers, Prev: Registers, Up: Registers
4444 5.6.1 Setting Registers
4445 -----------------------
4447 Define or set registers using the 'nr' request or the '\R' escape.
4449 Although the following requests and escapes can be used to create
4450 registers, simply using an undefined register will cause it to be set to
4453 -- Request: .nr ident value
4454 -- Escape: \R'ident value'
4455 Set number register IDENT to VALUE. If IDENT doesn't exist,
4456 'gtroff' creates it.
4458 The argument to '\R' usually has to be enclosed in quotes. *Note
4459 Escapes::, for details on parameter delimiting characters.
4461 The '\R' escape doesn't produce an input token in 'gtroff'; in
4462 other words, it vanishes completely after 'gtroff' has processed
4465 For example, the following two lines are equivalent:
4467 .nr a (((17 + (3 * 4))) % 4)
4468 \R'a (((17 + (3 * 4))) % 4)'
4471 Note that the complete transparency of '\R' can cause surprising
4472 effects if you use number registers like '.k', which get evaluated
4473 at the time they are accessed.
4477 aaa bbb ccc ddd eee fff ggg hhh\R':k \n[.k]'
4483 aaa bbb ccc ddd eee fff ggg hhh\h'0'\R':k \n[.k]'
4487 If you process this with the POSTSCRIPT device ('-Tps'), there will
4488 be a line break eventually after 'ggg' in both input lines.
4489 However, after processing the space after 'ggg', the partially
4490 collected line is not overfull yet, so 'troff' continues to collect
4491 input until it sees the space (or in this case, the newline) after
4492 'hhh'. At this point, the line is longer than the line length, and
4493 the line gets broken.
4495 In the first input line, since the '\R' escape leaves no traces,
4496 the check for the overfull line hasn't been done yet at the point
4497 where '\R' gets handled, and you get a value for the '.k' number
4498 register that is even greater than the current line length.
4500 In the second input line, the insertion of '\h'0'' to emit an
4501 invisible zero-width space forces 'troff' to check the line length,
4502 which in turn causes the start of a new output line. Now '.k'
4503 returns the expected value.
4505 Both 'nr' and '\R' have two additional special forms to increment or
4506 decrement a register.
4508 -- Request: .nr ident +value
4509 -- Request: .nr ident -value
4510 -- Escape: \R'ident +value'
4511 -- Escape: \R'ident -value'
4512 Increment (decrement) register IDENT by VALUE.
4519 To assign the negated value of a register to another register, some
4520 care must be taken to get the desired result:
4531 The surrounding parentheses prevent the interpretation of the minus
4532 sign as a decrementing operator. An alternative is to start the
4533 assignment with a '0':
4544 -- Request: .rr ident
4545 Remove number register IDENT. If IDENT doesn't exist, the request
4548 -- Request: .rnn ident1 ident2
4549 Rename number register IDENT1 to IDENT2. If either IDENT1 or
4550 IDENT2 doesn't exist, the request is ignored.
4552 -- Request: .aln ident1 ident2
4553 Create an alias IDENT1 for a number register IDENT2. The new name
4554 and the old name are exactly equivalent. If IDENT1 is undefined, a
4555 warning of type 'reg' is generated, and the request is ignored.
4556 *Note Debugging::, for information about warnings.
4559 File: groff.info, Node: Interpolating Registers, Next: Auto-increment, Prev: Setting Registers, Up: Registers
4561 5.6.2 Interpolating Registers
4562 -----------------------------
4564 Numeric registers can be accessed via the '\n' escape.
4568 -- Escape: \n[ident]
4569 Interpolate number register with name IDENT (one-character name I,
4570 two-character name ID). This means that the value of the register
4571 is expanded in-place while 'gtroff' is parsing the input line.
4572 Nested assignments (also called indirect assignments) are possible.
4589 File: groff.info, Node: Auto-increment, Next: Assigning Formats, Prev: Interpolating Registers, Up: Registers
4591 5.6.3 Auto-increment
4592 --------------------
4594 Number registers can also be auto-incremented and auto-decremented. The
4595 increment or decrement value can be specified with a third argument to
4596 the 'nr' request or '\R' escape.
4598 -- Request: .nr ident value incr
4599 Set number register IDENT to VALUE; the increment for
4600 auto-incrementing is set to INCR. Note that the '\R' escape
4601 doesn't support this notation.
4603 To activate auto-incrementing, the escape '\n' has a special syntax
4612 -- Escape: \n[+ident]
4613 -- Escape: \n[-ident]
4614 -- Escape: \n+[ident]
4615 -- Escape: \n-[ident]
4616 Before interpolating, increment or decrement IDENT (one-character
4617 name I, two-character name ID) by the auto-increment value as
4618 specified with the 'nr' request (or the '\R' escape). If no
4619 auto-increment value has been specified, these syntax forms are
4627 \n+a, \n+a, \n+a, \n+a, \n+a
4629 \n-(xx, \n-(xx, \n-(xx, \n-(xx, \n-(xx
4631 \n+[foo], \n+[foo], \n+[foo], \n+[foo], \n+[foo]
4636 -5, -10, -15, -20, -25
4639 To change the increment value without changing the value of a
4640 register (A in the example), the following can be used:
4645 File: groff.info, Node: Assigning Formats, Next: Built-in Registers, Prev: Auto-increment, Up: Registers
4647 5.6.4 Assigning Formats
4648 -----------------------
4650 When a register is used, it is always textually replaced (or
4651 interpolated) with a representation of that number. This output format
4652 can be changed to a variety of formats (numbers, Roman numerals, etc.).
4653 This is done using the 'af' request.
4655 -- Request: .af ident format
4656 Change the output format of a number register. The first argument
4657 IDENT is the name of the number register to be changed, and the
4658 second argument FORMAT is the output format. The following output
4659 formats are available:
4662 Decimal arabic numbers. This is the default format: 0, 1, 2,
4666 Decimal numbers with as many digits as specified. So, '00'
4667 would result in printing numbers as 01, 02, 03, ...
4669 In fact, any digit instead of zero does work; 'gtroff' only
4670 counts how many digits are specified. As a consequence,
4671 'af''s default format '1' could be specified as '0' also (and
4672 exactly this is returned by the '\g' escape, see below).
4675 Upper-case Roman numerals: 0, I, II, III, IV, ...
4678 Lower-case Roman numerals: 0, i, ii, iii, iv, ...
4681 Upper-case letters: 0, A, B, C, ..., Z, AA, AB, ...
4684 Lower-case letters: 0, a, b, c, ..., z, aa, ab, ...
4686 Omitting the number register format causes a warning of type
4687 'missing'. *Note Debugging::, for more details. Specifying a
4688 nonexistent format causes an error.
4690 The following example produces '10, X, j, 010':
4693 .af a 1 \" the default format
4702 The largest number representable for the 'i' and 'I' formats is
4703 39999 (or -39999); UNIX 'troff' uses 'z' and 'w' to represent 10000
4704 and 5000 in Roman numerals, and so does 'gtroff'. Currently, the
4705 correct glyphs of Roman numeral five thousand and Roman numeral ten
4706 thousand (Unicode code points 'U+2182' and 'U+2181', respectively)
4709 If IDENT doesn't exist, it is created.
4711 Changing the output format of a read-only register causes an error.
4712 It is necessary to first copy the register's value to a writeable
4713 register, then apply the 'af' request to this other register.
4717 -- Escape: \g[ident]
4718 Return the current format of the specified register IDENT
4719 (one-character name I, two-character name ID). For example, '\ga'
4720 after the previous example would produce the string '000'. If the
4721 register hasn't been defined yet, nothing is returned.
4724 File: groff.info, Node: Built-in Registers, Prev: Assigning Formats, Up: Registers
4726 5.6.5 Built-in Registers
4727 ------------------------
4729 The following lists some built-in registers that are not described
4730 elsewhere in this manual. Any register that begins with a '.' is
4731 read-only. A complete listing of all built-in registers can be found in
4732 *note Register Index::.
4735 This string-valued register returns the current input file name.
4738 Horizontal resolution in basic units.
4741 The number of number registers available. This is always 10000 in
4742 GNU 'troff'; it exists for backward compatibility.
4745 If 'gtroff' is called with the '-U' command line option to activate
4746 unsafe mode, the number register '.U' is set to 1, and to zero
4747 otherwise. *Note Groff Options::.
4750 Vertical resolution in basic units.
4753 The number of seconds after the minute, normally in the range 0
4754 to 59, but can be up to 61 to allow for leap seconds. Initialized
4755 at start-up of 'gtroff'.
4758 The number of minutes after the hour, in the range 0 to 59.
4759 Initialized at start-up of 'gtroff'.
4762 The number of hours past midnight, in the range 0 to 23.
4763 Initialized at start-up of 'gtroff'.
4766 Day of the week (1-7).
4769 Day of the month (1-31).
4772 Current month (1-12).
4778 The current year minus 1900. Unfortunately, the documentation of
4779 UNIX Version 7's 'troff' had a year 2000 bug: It incorrectly
4780 claimed that 'yr' contains the last two digits of the year. That
4781 claim has never been true of either AT&T 'troff' or GNU 'troff'.
4782 Old 'troff' input that looks like this:
4784 '\" The following line stopped working after 1999
4785 This document was formatted in 19\n(yr.
4787 can be corrected as follows:
4789 This document was formatted in \n[year].
4791 or, to be portable to older 'troff' versions, as follows:
4794 This document was formatted in \n(y4.
4798 The current _input_ line number. Register '.c' is read-only,
4799 whereas 'c.' (a 'gtroff' extension) is writable also, affecting
4803 The current _output_ line number after a call to the 'nm' request
4804 to activate line numbering.
4806 *Note Miscellaneous::, for more information about line numbering.
4809 The major version number. For example, if the version number is
4810 1.03 then '.x' contains '1'.
4813 The minor version number. For example, if the version number is
4814 1.03 then '.y' contains '03'.
4817 The revision number of 'groff'.
4820 The process ID of 'gtroff'.
4823 Always 1. Macros should use this to determine whether they are
4824 running under GNU 'troff'.
4827 If the command line option '-a' is used to produce an ASCII
4828 approximation of the output, this is set to 1, zero otherwise.
4829 *Note Groff Options::.
4832 This read-only register is set to the suppression nesting level
4833 (see escapes '\O'). *Note Suppressing output::.
4836 This register is set to 1 (and to 0 otherwise) if the current page
4837 is actually being printed, i.e., if the '-o' option is being used
4838 to only print selected pages. *Note Groff Options::, for more
4842 If 'gtroff' is called with the '-T' command line option, the number
4843 register '.T' is set to 1, and zero otherwise. *Note Groff
4847 A single read-write string register that contains the current
4848 output device (for example, 'latin1' or 'ps'). This is the only
4849 string register defined by 'gtroff'.
4852 File: groff.info, Node: Manipulating Filling and Adjusting, Next: Manipulating Hyphenation, Prev: Registers, Up: gtroff Reference
4854 5.7 Manipulating Filling and Adjusting
4855 ======================================
4857 Various ways of causing "breaks" were given in *note Implicit Line
4858 Breaks::. The 'br' request likewise causes a break. Several other
4859 requests also cause breaks, but implicitly. These are 'bp', 'ce', 'cf',
4860 'fi', 'fl', 'in', 'nf', 'rj', 'sp', 'ti', and 'trf'.
4863 Break the current line, i.e., the input collected so far is emitted
4866 If the no-break control character is used, 'gtroff' suppresses the
4874 Initially, 'gtroff' fills and adjusts text to both margins. Filling
4875 can be disabled via the 'nf' request and re-enabled with the 'fi'
4880 Activate fill mode (which is the default). This request implicitly
4881 enables adjusting; it also inserts a break in the text currently
4882 being filled. The read-only number register '.u' is set to 1.
4884 The fill mode status is associated with the current environment
4885 (*note Environments::).
4887 See *note Line Control::, for interaction with the '\c' escape.
4890 Activate no-fill mode. Input lines are output as-is, retaining
4891 line breaks and ignoring the current line length. This command
4892 implicitly disables adjusting; it also causes a break. The number
4893 register '.u' is set to 0.
4895 The fill mode status is associated with the current environment
4896 (*note Environments::).
4898 See *note Line Control::, for interaction with the '\c' escape.
4900 -- Request: .ad [mode]
4904 Activation and deactivation of adjusting is done implicitly with
4905 calls to the 'fi' or 'nf' requests.
4907 MODE can have one of the following values:
4910 Adjust text to the left margin. This produces what is
4911 traditionally called ragged-right text.
4914 Adjust text to the right margin, producing ragged-left text.
4917 Center filled text. This is different to the 'ce' request,
4918 which only centers text without filling.
4922 Justify to both margins. This is the default used by
4925 Finally, MODE can be the numeric argument returned by the '.j'
4928 Using 'ad' without argument is the same as saying '.ad \[.j]'. In
4929 particular, 'gtroff' adjusts lines in the same way it did before
4930 adjusting was deactivated (with a call to 'na', say). For example,
4951 .AD \" back to centering
4953 .AD \n[ad] \" back to right justifying
4956 produces the following output:
4965 As just demonstrated, the current adjustment mode is available in
4966 the read-only number register '.j'; it can be stored and
4967 subsequently used to set adjustment.
4969 The adjustment mode status is associated with the current
4970 environment (*note Environments::).
4973 Disable adjusting. This request won't change the current
4974 adjustment mode: A subsequent call to 'ad' uses the previous
4977 The adjustment mode status is associated with the current
4978 environment (*note Environments::).
4982 Adjust the current line and cause a break.
4984 In most cases this produces very ugly results since 'gtroff'
4985 doesn't have a sophisticated paragraph building algorithm (as TeX
4986 have, for example); instead, 'gtroff' fills and adjusts a paragraph
4989 This is an uninteresting sentence.
4990 This is an uninteresting sentence.\p
4991 This is an uninteresting sentence.
4995 This is an uninteresting sentence. This is an
4996 uninteresting sentence.
4997 This is an uninteresting sentence.
4999 -- Request: .ss word_space_size [sentence_space_size]
5000 -- Register: \n[.ss]
5001 -- Register: \n[.sss]
5002 Change the size of a space between words. It takes its units as
5003 one twelfth of the space width parameter for the current font.
5004 Initially both the WORD_SPACE_SIZE and SENTENCE_SPACE_SIZE are 12.
5005 In fill mode, the values specify the minimum distance.
5007 If two arguments are given to the 'ss' request, the second argument
5008 sets the sentence space size. If the second argument is not given,
5009 sentence space size is set to WORD_SPACE_SIZE. The sentence space
5010 size is used in two circumstances: If the end of a sentence occurs
5011 at the end of a line in fill mode, then both an inter-word space
5012 and a sentence space are added; if two spaces follow the end of a
5013 sentence in the middle of a line, then the second space is a
5014 sentence space. If a second argument is never given to the 'ss'
5015 request, the behaviour of UNIX 'troff' is the same as that
5016 exhibited by GNU 'troff'. In GNU 'troff', as in UNIX 'troff', a
5017 sentence should always be followed by either a newline or two
5020 The read-only number registers '.ss' and '.sss' hold the values of
5021 the parameters set by the first and second arguments of the 'ss'
5024 The word space and sentence space values are associated with the
5025 current environment (*note Environments::).
5027 Contrary to AT&T 'troff', this request is _not_ ignored if a TTY
5028 output device is used; the given values are then rounded down to a
5029 multiple of 12 (*note Implementation Differences::).
5031 The request is ignored if there is no parameter.
5033 Another useful application of the 'ss' request is to insert
5034 discardable horizontal space, i.e., space that is discarded at a
5035 line break. For example, paragraph-style footnotes could be
5039 1.\ This is the first footnote.\c
5043 2.\ This is the second footnote.
5047 1. This is the first footnote. 2. This
5048 is the second footnote.
5050 Note that the '\h' escape produces unbreakable space.
5052 -- Request: .ce [nnn]
5053 -- Register: \n[.ce]
5054 Center text. While the '.ad c' request also centers text, it fills
5055 the text as well. 'ce' does not fill the text it affects. This
5056 request causes a break. The number of lines still to be centered
5057 is associated with the current environment (*note Environments::).
5059 The following example demonstrates the differences. Here the
5064 This is a small text fragment that shows the differences
5065 between the `.ce' and the `.ad c' request.
5069 This is a small text fragment that shows the differences
5070 between the `.ce' and the `.ad c' request.
5072 And here the result:
5074 This is a small text fragment that
5075 shows the differences
5076 between the `.ce' and the `.ad c' request.
5078 This is a small text fragment that
5079 shows the differences between the `.ce'
5080 and the `.ad c' request.
5082 With no arguments, 'ce' centers the next line of text. NNN
5083 specifies the number of lines to be centered. If the argument is
5084 zero or negative, centering is disabled.
5086 The basic length for centering text is the line length (as set with
5087 the 'll' request) minus the indentation (as set with the 'in'
5088 request). Temporary indentation is ignored.
5090 As can be seen in the previous example, it is a common idiom to
5091 turn on centering for a large number of lines, and to turn off
5092 centering after text to be centered. This is useful for any
5093 request that takes a number of lines as an argument.
5095 The '.ce' read-only number register contains the number of lines
5096 remaining to be centered, as set by the 'ce' request.
5098 -- Request: .rj [nnn]
5099 -- Register: \n[.rj]
5100 Justify unfilled text to the right margin. Arguments are identical
5101 to the 'ce' request. The '.rj' read-only number register is the
5102 number of lines to be right-justified as set by the 'rj' request.
5103 This request causes a break. The number of lines still to be
5104 right-justified is associated with the current environment (*note
5108 File: groff.info, Node: Manipulating Hyphenation, Next: Manipulating Spacing, Prev: Manipulating Filling and Adjusting, Up: gtroff Reference
5110 5.8 Manipulating Hyphenation
5111 ============================
5113 Here a description of requests that influence hyphenation.
5115 -- Request: .hy [mode]
5116 -- Register: \n[.hy]
5117 Enable hyphenation. The request has an optional numeric argument,
5118 MODE, to restrict hyphenation if necessary:
5121 The default argument if MODE is omitted. Hyphenate without
5122 restrictions. This is also the start-up value of 'gtroff'.
5125 Do not hyphenate the last word on a page or column.
5128 Do not hyphenate the last two characters of a word.
5131 Do not hyphenate the first two characters of a word.
5133 Values in the previous table are additive. For example, the
5134 value 12 causes 'gtroff' to neither hyphenate the last two nor the
5135 first two characters of a word.
5137 The current hyphenation restrictions can be found in the read-only
5138 number register '.hy'.
5140 The hyphenation mode is associated with the current environment
5141 (*note Environments::).
5144 Disable hyphenation (i.e., set the hyphenation mode to zero). Note
5145 that the hyphenation mode of the last call to 'hy' is not
5148 The hyphenation mode is associated with the current environment
5149 (*note Environments::).
5151 -- Request: .hlm [nnn]
5152 -- Register: \n[.hlm]
5153 -- Register: \n[.hlc]
5154 Set the maximum number of consecutive hyphenated lines to NNN. If
5155 this number is negative, there is no maximum. The default value
5156 is -1 if NNN is omitted. This value is associated with the current
5157 environment (*note Environments::). Only lines output from a given
5158 environment count towards the maximum associated with that
5159 environment. Hyphens resulting from '\%' are counted; explicit
5162 The current setting of 'hlm' is available in the '.hlm' read-only
5163 number register. Also the number of immediately preceding
5164 consecutive hyphenated lines are available in the read-only number
5167 -- Request: .hw word1 word2 ...
5168 Define how WORD1, WORD2, etc. are to be hyphenated. The words must
5169 be given with hyphens at the hyphenation points. For example:
5173 Besides the space character, any character whose hyphenation code
5174 value is zero can be used to separate the arguments of 'hw' (see
5175 the documentation for the 'hcode' request below for more
5176 information). In addition, this request can be used more than
5179 Hyphenation exceptions specified with the 'hw' request are
5180 associated with the current hyphenation language; it causes an
5181 error if there is no current hyphenation language.
5183 This request is ignored if there is no parameter.
5185 In old versions of 'troff' there was a limited amount of space to
5186 store such information; fortunately, with 'gtroff', this is no
5187 longer a restriction.
5191 To tell 'gtroff' how to hyphenate words on the fly, use the '\%'
5192 escape, also known as the "hyphenation character". Preceding a
5193 word with this character prevents it from being hyphenated; putting
5194 it inside a word indicates to 'gtroff' that the word may be
5195 hyphenated at that point. Note that this mechanism only affects
5196 that one occurrence of the word; to change the hyphenation of a
5197 word for the entire document, use the 'hw' request.
5199 The '\:' escape inserts a zero-width break point (that is, the word
5200 breaks but without adding a hyphen).
5202 ... check the /var/log/\:httpd/\:access_log file ...
5204 Note that '\X' and '\Y' start a word, that is, the '\%' escape in
5205 (say) '\X'...'\%foobar' and '\Y'...'\%foobar' no longer prevents
5206 hyphenation but inserts a hyphenation point at the beginning of
5207 'foobar'; most likely this isn't what you want to do.
5209 -- Request: .hc [char]
5210 Change the hyphenation character to CHAR. This character then
5211 works the same as the '\%' escape, and thus, no longer appears in
5212 the output. Without an argument, 'hc' resets the hyphenation
5213 character to be '\%' (the default) only.
5215 The hyphenation character is associated with the current
5216 environment (*note Environments::).
5218 -- Request: .hpf pattern_file
5219 -- Request: .hpfa pattern_file
5220 -- Request: .hpfcode a b [c d ...]
5221 Read in a file of hyphenation patterns. This file is searched for
5222 in the same way as 'NAME.tmac' (or 'tmac.NAME') is searched for if
5223 the '-mNAME' option is specified.
5225 It should have the same format as (simple) TeX patterns files.
5226 More specifically, the following scanning rules are implemented.
5228 * A percent sign starts a comment (up to the end of the line)
5229 even if preceded by a backslash.
5231 * No support for 'digraphs' like '\$'.
5233 * '^^XX' (X is 0-9 or a-f) and '^^X' (character code of X in the
5234 range 0-127) are recognized; other use of '^' causes an error.
5236 * No macro expansion.
5238 * 'hpf' checks for the expression '\patterns{...}' (possibly
5239 with whitespace before and after the braces). Everything
5240 between the braces is taken as hyphenation patterns.
5241 Consequently, '{' and '}' are not allowed in patterns.
5243 * Similarly, '\hyphenation{...}' gives a list of hyphenation
5246 * '\endinput' is recognized also.
5248 * For backwards compatibility, if '\patterns' is missing, the
5249 whole file is treated as a list of hyphenation patterns (only
5250 recognizing the '%' character as the start of a comment).
5252 If no 'hpf' request is specified (either in the document or in a
5253 macro package), 'gtroff' won't hyphenate at all.
5255 The 'hpfa' request appends a file of patterns to the current list.
5257 The 'hpfcode' request defines mapping values for character codes in
5258 hyphenation patterns. 'hpf' or 'hpfa' then apply the mapping
5259 (after reading the patterns) before replacing or appending them to
5260 the current list of patterns. Its arguments are pairs of character
5261 codes - integers from 0 to 255. The request maps character code A
5262 to code B, code C to code D, and so on. You can use character
5263 codes that would be invalid otherwise. By default, everything maps
5264 to itself except letters 'A' to 'Z', which map to 'a' to 'z'.
5266 The set of hyphenation patterns is associated with the current
5267 language set by the 'hla' request. The 'hpf' request is usually
5268 invoked by the 'troffrc' or 'troffrc-end' file; by default,
5269 'troffrc' loads hyphenation patterns and exceptions for American
5270 English (in files 'hyphen.us' and 'hyphenex.us').
5272 A second call to 'hpf' (for the same language) replaces the
5273 hyphenation patterns with the new ones.
5275 Invoking 'hpf' causes an error if there is no current hyphenation
5278 -- Request: .hcode c1 code1 [c2 code2 ...]
5279 Set the hyphenation code of character C1 to CODE1, that of C2 to
5280 CODE2, etc. A hyphenation code must be a single input character
5281 (not a special character) other than a digit or a space.
5283 To make hyphenation work, hyphenation codes must be set up. At
5284 start-up, groff only assigns hyphenation codes to the letters
5285 'a'-'z' (mapped to themselves) and to the letters 'A'-'Z' (mapped
5286 to 'a'-'z'); all other hyphenation codes are set to zero.
5287 Normally, hyphenation patterns contain only lowercase letters,
5288 which should be applied regardless of case. In other words, the
5289 words 'FOO' and 'Foo' should be hyphenated exactly the same way as
5290 the word 'foo' is hyphenated, and this is what 'hcode' is good for.
5291 Words that contain other letters won't be hyphenated properly if
5292 the corresponding hyphenation patterns actually do contain them.
5293 For example, the following 'hcode' requests are necessary to assign
5294 hyphenation codes to the letters 'ÄäÖöÜüß' (this is needed for
5302 Without those assignments, groff treats German words like
5303 'Kindergärten' (the plural form of 'kindergarten') as two
5304 substrings 'kinderg' and 'rten' because the hyphenation code of the
5305 umlaut a is zero by default. There is a German hyphenation pattern
5306 that covers 'kinder', so groff finds the hyphenation 'kin-der'.
5307 The other two hyphenation points ('kin-der-gär-ten') are missed.
5309 This request is ignored if it has no parameter.
5311 -- Request: .hym [length]
5312 -- Register: \n[.hym]
5313 Set the (right) hyphenation margin to LENGTH. If the current
5314 adjustment mode is not 'b' or 'n', the line is not hyphenated if it
5315 is shorter than LENGTH. Without an argument, the hyphenation
5316 margin is reset to its default value, which is 0. The default
5317 scaling indicator for this request is 'm'. The hyphenation margin
5318 is associated with the current environment (*note Environments::).
5320 A negative argument resets the hyphenation margin to zero, emitting
5321 a warning of type 'range'.
5323 The current hyphenation margin is available in the '.hym' read-only
5326 -- Request: .hys [hyphenation_space]
5327 -- Register: \n[.hys]
5328 Set the hyphenation space to HYPHENATION_SPACE. If the current
5329 adjustment mode is 'b' or 'n', don't hyphenate the line if it can
5330 be justified by adding no more than HYPHENATION_SPACE extra space
5331 to each word space. Without argument, the hyphenation space is set
5332 to its default value, which is 0. The default scaling indicator
5333 for this request is 'm'. The hyphenation space is associated with
5334 the current environment (*note Environments::).
5336 A negative argument resets the hyphenation space to zero, emitting
5337 a warning of type 'range'.
5339 The current hyphenation space is available in the '.hys' read-only
5342 -- Request: .shc [glyph]
5343 Set the "soft hyphen character" to GLYPH.(1) (*note Manipulating
5344 Hyphenation-Footnote-1::) If the argument is omitted, the soft
5345 hyphen character is set to the default glyph '\(hy' (this is the
5346 start-up value of 'gtroff' also). The soft hyphen character is the
5347 glyph that is inserted when a word is hyphenated at a line break.
5348 If the soft hyphen character does not exist in the font of the
5349 character immediately preceding a potential break point, then the
5350 line is not broken at that point. Neither definitions (specified
5351 with the 'char' request) nor translations (specified with the 'tr'
5352 request) are considered when finding the soft hyphen character.
5354 -- Request: .hla language
5355 -- Register: \n[.hla]
5356 Set the current hyphenation language to the string LANGUAGE.
5357 Hyphenation exceptions specified with the 'hw' request and
5358 hyphenation patterns specified with the 'hpf' and 'hpfa' requests
5359 are both associated with the current hyphenation language. The
5360 'hla' request is usually invoked by the 'troffrc' or the
5361 'troffrc-end' files; 'troffrc' sets the default language to 'us'.
5363 The current hyphenation language is available as a string in the
5364 read-only number register '.hla'.
5366 .ds curr_language \n[.hla]
5371 File: groff.info, Node: Manipulating Hyphenation-Footnotes, Up: Manipulating Hyphenation
5373 (1) "Soft hyphen character" is a misnomer since it is an output
5377 File: groff.info, Node: Manipulating Spacing, Next: Tabs and Fields, Prev: Manipulating Hyphenation, Up: gtroff Reference
5379 5.9 Manipulating Spacing
5380 ========================
5382 -- Request: .sp [distance]
5383 Space downwards DISTANCE. With no argument it advances 1 line. A
5384 negative argument causes 'gtroff' to move up the page the specified
5385 distance. If the argument is preceded by a '|' then 'gtroff' moves
5386 that distance from the top of the page. This request causes a line
5387 break, and that adds the current line spacing to the space you have
5388 just specified. The default scaling indicator is 'v'.
5390 For convenience you may wish to use the following macros to set the
5391 height of the next line at a given distance from the top or the
5399 . sp |\\n[.p]u-\\$1-\\n[.v]u
5402 A call to '.y-from-bot-up 10c' means that the bottom of the next
5403 line will be at 10cm from the paper edge at the bottom.
5405 If a vertical trap is sprung during execution of 'sp', the amount
5406 of vertical space after the trap is discarded. For example, this
5429 The amount of discarded space is available in the number register
5432 To protect 'sp' against vertical traps, use the 'vpt' request:
5438 -- Request: .ls [nnn]
5440 Output NNN-1 blank lines after each line of text. With no
5441 argument, 'gtroff' uses the previous value before the last 'ls'
5444 .ls 2 \" This causes double-spaced output
5445 .ls 3 \" This causes triple-spaced output
5446 .ls \" Again double-spaced
5448 The line spacing is associated with the current environment (*note
5451 The read-only number register '.L' contains the current line
5454 *Note Changing Type Sizes::, for the requests 'vs' and 'pvs' as
5455 alternatives to 'ls'.
5457 -- Escape: \x'spacing'
5459 Sometimes, extra vertical spacing is only needed occasionally, e.g.
5460 to allow space for a tall construct (like an equation). The '\x'
5461 escape does this. The escape is given a numerical argument,
5462 usually enclosed in quotes (like '\x'3p''); the default scaling
5463 indicator is 'v'. If this number is positive extra vertical space
5464 is inserted below the current line. A negative number adds space
5465 above. If this escape is used multiple times on the same line, the
5466 maximum of the values is used.
5468 *Note Escapes::, for details on parameter delimiting characters.
5470 The '.a' read-only number register contains the most recent
5471 (nonnegative) extra vertical line space.
5473 Using '\x' can be necessary in combination with the '\b' escape, as
5474 the following example shows.
5476 This is a test with the \[rs]b escape.
5478 This is a test with the \[rs]b escape.
5480 This is a test with \b'xyz'\x'-1m'\x'1m'.
5482 This is a test with the \[rs]b escape.
5484 This is a test with the \[rs]b escape.
5488 This is a test with the \b escape.
5489 This is a test with the \b escape.
5491 This is a test with y.
5493 This is a test with the \b escape.
5494 This is a test with the \b escape.
5498 -- Register: \n[.ns]
5499 Enable "no-space mode". In this mode, spacing (either via 'sp' or
5500 via blank lines) is disabled. The 'bp' request to advance to the
5501 next page is also disabled, except if it is accompanied by a page
5502 number (see *note Page Control::, for more information). This mode
5503 ends when actual text is output or the 'rs' request is encountered,
5504 which ends no-space mode. The read-only number register '.ns' is
5505 set to 1 as long as no-space mode is active.
5507 This request is useful for macros that conditionally insert
5508 vertical space before the text starts (for example, a paragraph
5509 macro could insert some space except when it is the first paragraph
5510 after a section header).
5513 File: groff.info, Node: Tabs and Fields, Next: Character Translations, Prev: Manipulating Spacing, Up: gtroff Reference
5515 5.10 Tabs and Fields
5516 ====================
5518 A tab character (ASCII char 9, EBCDIC char 5) causes a horizontal
5519 movement to the next tab stop (much like it did on a typewriter).
5522 This escape is a non-interpreted tab character. In copy mode
5523 (*note Copy-in Mode::), '\t' is the same as a real tab character.
5525 -- Request: .ta [n1 n2 ... nn T r1 r2 ... rn]
5526 -- Register: \n[.tabs]
5527 Change tab stop positions. This request takes a series of tab
5528 specifiers as arguments (optionally divided into two groups with
5529 the letter 'T') that indicate where each tab stop is to be
5530 (overriding any previous settings).
5532 Tab stops can be specified absolutely, i.e., as the distance from
5533 the left margin. For example, the following sets 6 tab stops every
5536 .ta 1i 2i 3i 4i 5i 6i
5538 Tab stops can also be specified using a leading '+', which means
5539 that the specified tab stop is set relative to the previous tab
5540 stop. For example, the following is equivalent to the previous
5543 .ta 1i +1i +1i +1i +1i +1i
5545 'gtroff' supports an extended syntax to specify repeat values after
5546 the 'T' mark (these values are always taken as relative) - this is
5547 the usual way to specify tabs set at equal intervals. The
5548 following is, yet again, the same as the previous examples. It
5549 does even more since it defines an infinite number of tab stops
5550 separated by one inch.
5554 Now we are ready to interpret the full syntax given at the
5555 beginning: Set tabs at positions N1, N2, ..., NN and then set tabs
5556 at NN+R1, NN+R2, ..., NN+RN and then at NN+RN+R1, NN+RN+R2, ...,
5557 NN+RN+RN, and so on.
5559 Example: '4c +6c T 3c 5c 2c' is equivalent to '4c 10c 13c 18c 20c
5562 The material in each tab column (i.e., the column between two tab
5563 stops) may be justified to the right or left or centered in the
5564 column. This is specified by appending 'R', 'L', or 'C' to the tab
5565 specifier. The default justification is 'L'. Example:
5571 * The default unit of the 'ta' request is 'm'.
5573 * A tab stop is converted into a non-breakable horizontal
5574 movement that can be neither stretched nor squeezed. For
5581 creates a single line, which is a bit longer than 10 inches (a
5582 string is used to show exactly where the tab characters are).
5583 Now consider the following:
5589 'gtroff' first converts the tab stops of the line into
5590 unbreakable horizontal movements, then splits the line after
5591 the second 'b' (assuming a sufficiently short line length).
5592 Usually, this isn't what the user wants.
5594 * Superfluous tabs (i.e., tab characters that do not correspond
5595 to a tab stop) are ignored except the first one, which
5596 delimits the characters belonging to the last tab stop for
5597 right-justifying or centering. Consider the following example
5600 .ds ZZ foo\tbar\tfoobar
5601 .ds ZZZ foo\tbar\tfoo\tbar
5610 which produces the following output:
5616 The first line right-justifies the second 'foo' relative to
5617 the tab stop. The second line right-justifies 'foobar'. The
5618 third line finally right-justifies only 'foo' because of the
5619 additional tab character, which marks the end of the string
5620 belonging to the last defined tab stop.
5622 * Tab stops are associated with the current environment (*note
5625 * Calling 'ta' without an argument removes all tab stops.
5627 * The start-up value of 'gtroff' is 'T 0.8i'.
5629 The read-only number register '.tabs' contains a string
5630 representation of the current tab settings suitable for use as an
5631 argument to the 'ta' request.
5633 .ds tab-string \n[.tabs]
5637 The 'troff' version of the Plan 9 operating system uses register
5638 '.S' for the same purpose.
5640 -- Request: .tc [fill-glyph]
5641 Normally 'gtroff' fills the space to the next tab stop with
5642 whitespace. This can be changed with the 'tc' request. With no
5643 argument 'gtroff' reverts to using whitespace, which is the
5644 default. The value of this "tab repetition character" is
5645 associated with the current environment (*note Environments::).(1)
5646 (*note Tabs and Fields-Footnote-1::)
5648 -- Request: .linetabs n
5649 -- Register: \n[.linetabs]
5650 If N is missing or not zero, enable "line-tabs" mode, or disable it
5651 otherwise (the default). In line-tabs mode, 'gtroff' computes tab
5652 distances relative to the (current) output line instead of the
5655 For example, the following code:
5665 in normal mode, results in the output
5669 in line-tabs mode, the same code outputs
5673 Line-tabs mode is associated with the current environment. The
5674 read-only register '.linetabs' is set to 1 if in line-tabs mode,
5675 and 0 in normal mode.
5683 File: groff.info, Node: Tabs and Fields-Footnotes, Up: Tabs and Fields
5685 (1) "Tab repetition character" is a misnomer since it is an output
5689 File: groff.info, Node: Leaders, Next: Fields, Prev: Tabs and Fields, Up: Tabs and Fields
5694 Sometimes it may may be desirable to use the 'tc' request to fill a
5695 particular tab stop with a given glyph (for example dots in a table of
5696 contents), but also normal tab stops on the rest of the line. For this
5697 'gtroff' provides an alternate tab mechanism, called "leaders", which
5700 A leader character (character code 1) behaves similarly to a tab
5701 character: It moves to the next tab stop. The only difference is that
5702 for this movement, the fill glyph defaults to a period character and not
5706 This escape is a non-interpreted leader character. In copy mode
5707 (*note Copy-in Mode::), '\a' is the same as a real leader
5710 -- Request: .lc [fill-glyph]
5711 Declare the "leader repetition character".(1) (*note
5712 Leaders-Footnote-1::) Without an argument, leaders act the same as
5713 tabs (i.e., using whitespace for filling). 'gtroff''s start-up
5714 value is a dot ('.'). The value of the leader repetition character
5715 is associated with the current environment (*note Environments::).
5717 For a table of contents, to name an example, tab stops may be defined
5718 so that the section number is one tab stop, the title is the second with
5719 the remaining space being filled with a line of dots, and then the page
5720 number slightly separated from the dots.
5722 .ds entry 1.1\tFoo\a\t12
5729 1.1 Foo.......................................... 12
5732 File: groff.info, Node: Leaders-Footnotes, Up: Leaders
5734 (1) "Leader repetition character" is a misnomer since it is an output
5738 File: groff.info, Node: Fields, Prev: Leaders, Up: Tabs and Fields
5743 "Fields" are a more general way of laying out tabular data. A field is
5744 defined as the data between a pair of "delimiting characters". It
5745 contains substrings that are separated by "padding characters". The
5746 width of a field is the distance on the _input_ line from the position
5747 where the field starts to the next tab stop. A padding character
5748 inserts stretchable space similar to TeX's '\hss' command (thus it can
5749 even be negative) to make the sum of all substring lengths plus the
5750 stretchable space equal to the field width. If more than one padding
5751 character is inserted, the available space is evenly distributed among
5754 -- Request: .fc [delim-char [padding-char]]
5755 Define a delimiting and a padding character for fields. If the
5756 latter is missing, the padding character defaults to a space
5757 character. If there is no argument at all, the field mechanism is
5758 disabled (which is the default). Note that contrary to e.g. the
5759 tab repetition character, delimiting and padding characters are
5760 _not_ associated to the current environment (*note Environments::).
5770 and here the result:
5776 File: groff.info, Node: Character Translations, Next: Troff and Nroff Mode, Prev: Tabs and Fields, Up: gtroff Reference
5778 5.11 Character Translations
5779 ===========================
5781 The control character ('.') and the no-break control character (''') can
5782 be changed with the 'cc' and 'c2' requests, respectively.
5785 Set the control character to C. With no argument the default
5786 control character '.' is restored. The value of the control
5787 character is associated with the current environment (*note
5791 Set the no-break control character to C. With no argument the
5792 default control character ''' is restored. The value of the
5793 no-break control character is associated with the current
5794 environment (*note Environments::).
5799 Disable the escape mechanism completely. After executing this
5800 request, the backslash character '\' no longer starts an escape
5803 This request can be very helpful in writing macros since it is not
5804 necessary then to double the escape character. Here an example:
5806 .\" This is a simplified version of the
5807 .\" .BR request from the man macro package
5811 . while (\n[.$] >= 2) \{\
5812 . as result \fB\$1\fR\$2
5815 . if \n[.$] .as result \fB\$1
5822 Set the escape character to C. With no argument the default escape
5823 character '\' is restored. It can be also used to re-enable the
5824 escape mechanism after an 'eo' request.
5826 Note that changing the escape character globally likely breaks
5827 macro packages since 'gtroff' has no mechanism to 'intern' macros,
5828 i.e., to convert a macro definition into an internal form that is
5829 independent of its representation (TeX has this mechanism). If a
5830 macro is called, it is executed literally.
5834 The 'ecs' request saves the current escape character in an internal
5835 register. Use this request in combination with the 'ec' request to
5836 temporarily change the escape character.
5838 The 'ecr' request restores the escape character saved with 'ecs'.
5839 Without a previous call to 'ecs', this request sets the escape
5845 Print the current escape character (which is the backslash
5846 character '\' by default).
5848 '\\' is a 'delayed' backslash; more precisely, it is the default
5849 escape character followed by a backslash, which no longer has
5850 special meaning due to the leading escape character. It is _not_
5851 an escape sequence in the usual sense! In any unknown escape
5852 sequence '\X' the escape character is ignored and X is printed.
5853 But if X is equal to the current escape character, no warning is
5856 As a consequence, only at top-level or in a diversion a backslash
5857 glyph is printed; in copy-in mode, it expands to a single
5858 backslash, which then combines with the following character to an
5861 The '\E' escape differs from '\e' by printing an escape character
5862 that is not interpreted in copy mode. Use this to define strings
5863 with escapes that work when used in copy mode (for example, as a
5864 macro argument). The following example defines strings to begin
5865 and end a superscript:
5867 .ds { \v'-.3m'\s'\En[.s]*60/100'
5870 Another example to demonstrate the differences between the various
5871 escape sequences, using a strange escape character, '-'.
5880 The result is surprising for most users, expecting '1' since 'foo'
5881 is a valid identifier. What has happened? As mentioned above, the
5882 leading escape character makes the following character ordinary.
5883 Written with the default escape character the sequence '--' becomes
5884 '\-' - this is the minus sign.
5886 If the escape character followed by itself is a valid escape
5887 sequence, only '\E' yields the expected result:
5897 Similar to '\\', the sequence '\.' isn't a real escape sequence.
5898 As before, a warning message is suppressed if the escape character
5899 is followed by a dot, and the dot itself is printed.
5913 The first backslash is consumed while the macro is read, and the
5914 second is swallowed while executing macro 'foo'.
5916 A "translation" is a mapping of an input character to an output
5917 glyph. The mapping occurs at output time, i.e., the input character
5918 gets assigned the metric information of the mapped output character
5919 right before input tokens are converted to nodes (*note Gtroff
5920 Internals::, for more on this process).
5922 -- Request: .tr abcd...
5923 -- Request: .trin abcd...
5924 Translate character A to glyph B, character C to glyph D, etc. If
5925 there is an odd number of arguments, the last one is translated to
5926 an unstretchable space ('\ ').
5928 The 'trin' request is identical to 'tr', but when you unformat a
5929 diversion with 'asciify' it ignores the translation. *Note
5930 Diversions::, for details about the 'asciify' request.
5934 * Special characters ('\(XX', '\[XXX]', '\C'XXX'', '\'', '\`',
5935 '\-', '\_'), glyphs defined with the 'char' request, and
5936 numbered glyphs ('\N'XXX'') can be translated also.
5938 * The '\e' escape can be translated also.
5940 * Characters can be mapped onto the '\%' and '\~' escapes (but
5941 '\%' and '\~' can't be mapped onto another glyph).
5943 * The following characters can't be translated: space (with one
5944 exception, see below), backspace, newline, leader (and '\a'),
5947 * Translations are not considered for finding the soft hyphen
5948 character set with the 'shc' request.
5950 * The pair 'C\&' (this is an arbitrary character C followed by
5951 the zero width space character) maps this character to
5958 It is even possible to map the space character to nothing:
5964 As shown in the example, the space character can't be the
5965 first character/glyph pair as an argument of 'tr'.
5966 Additionally, it is not possible to map the space character to
5967 any other glyph; requests like '.tr aa x' undo '.tr aa \&'
5970 If justification is active, lines are justified in spite of
5971 the 'empty' space character (but there is no minimal distance,
5972 i.e. the space character, between words).
5974 * After an output glyph has been constructed (this happens at
5975 the moment immediately before the glyph is appended to an
5976 output glyph list, either by direct output, in a macro,
5977 diversion, or string), it is no longer affected by 'tr'.
5979 * Translating character to glyphs where one of them or both are
5980 undefined is possible also; 'tr' does not check whether the
5981 entities in its argument do exist.
5983 *Note Gtroff Internals::.
5985 * 'troff' no longer has a hard-coded dependency on Latin-1; all
5986 'charXXX' entities have been removed from the font description
5987 files. This has a notable consequence that shows up in
5988 warnings like 'can't find character with input code XXX' if
5989 the 'tr' request isn't handled properly.
5991 Consider the following translation:
5995 This maps input character 'é' onto glyph 'É', which is
5996 identical to glyph 'char201'. But this glyph intentionally
5997 doesn't exist! Instead, '\[char201]' is treated as an input
5998 character entity and is by default mapped onto '\['E]', and
5999 'gtroff' doesn't handle translations of translations.
6001 The right way to write the above translation is
6005 In other words, the first argument of 'tr' should be an input
6006 character or entity, and the second one a glyph entity.
6008 * Without an argument, the 'tr' request is ignored.
6010 -- Request: .trnt abcd...
6011 'trnt' is the same as the 'tr' request except that the translations
6012 do not apply to text that is transparently throughput into a
6013 diversion with '\!'. *Note Diversions::, for more information.
6023 prints 'b' to the standard error stream; if 'trnt' is used instead
6024 of 'tr' it prints 'a'.
6027 File: groff.info, Node: Troff and Nroff Mode, Next: Line Layout, Prev: Character Translations, Up: gtroff Reference
6029 5.12 Troff and Nroff Mode
6030 =========================
6032 Originally, 'nroff' and 'troff' were two separate programs, the former
6033 for TTY output, the latter for everything else. With GNU 'troff', both
6034 programs are merged into one executable, sending its output to a device
6035 driver ('grotty' for TTY devices, 'grops' for POSTSCRIPT, etc.) which
6036 interprets the intermediate output of 'gtroff'. For UNIX 'troff' it
6037 makes sense to talk about "Nroff mode" and "Troff mode" since the
6038 differences are hardcoded. For GNU 'troff', this distinction is not
6039 appropriate because 'gtroff' simply takes the information given in the
6040 font files for a particular device without handling requests specially
6041 if a TTY output device is used.
6043 Usually, a macro package can be used with all output devices.
6044 Nevertheless, it is sometimes necessary to make a distinction between
6045 TTY and non-TTY devices: 'gtroff' provides two built-in conditions 'n'
6046 and 't' for the 'if', 'ie', and 'while' requests to decide whether
6047 'gtroff' shall behave like 'nroff' or like 'troff'.
6050 Make the 't' built-in condition true (and the 'n' built-in
6051 condition false) for 'if', 'ie', and 'while' conditional requests.
6052 This is the default if 'gtroff' (_not_ 'groff') is started with the
6053 '-R' switch to avoid loading of the start-up files 'troffrc' and
6054 'troffrc-end'. Without '-R', 'gtroff' stays in troff mode if the
6055 output device is not a TTY (e.g. 'ps').
6058 Make the 'n' built-in condition true (and the 't' built-in
6059 condition false) for 'if', 'ie', and 'while' conditional requests.
6060 This is the default if 'gtroff' uses a TTY output device; the code
6061 for switching to nroff mode is in the file 'tty.tmac', which is
6062 loaded by the start-up file 'troffrc'.
6064 *Note Conditionals and Loops::, for more details on built-in
6068 File: groff.info, Node: Line Layout, Next: Line Control, Prev: Troff and Nroff Mode, Up: gtroff Reference
6073 The following drawing shows the dimensions that 'gtroff' uses for
6074 placing a line of output onto the page. They are labeled with the
6075 request that manipulates each dimension.
6078 |<-----------ll------------>|
6079 +----+----+----------------------+----+
6081 +----+----+----------------------+----+
6083 |<--------paper width---------------->|
6085 These dimensions are:
6088 "Page offset" - this is the leftmost position of text on the final
6089 output, defining the "left margin".
6092 "Indentation" - this is the distance from the left margin where
6096 "Line length" - this is the distance from the left margin to right
6099 A simple demonstration:
6102 This is text without indentation.
6103 The line length has been set to 3\~inch.
6106 Now the left and right margins are both increased.
6109 Calling .in and .ll without parameters restore
6110 the previous values.
6114 This is text without indenta-
6115 tion. The line length has
6120 Calling .in and .ll without
6121 parameters restore the previ-
6124 -- Request: .po [offset]
6125 -- Request: .po +offset
6126 -- Request: .po -offset
6128 Set horizontal page offset to OFFSET (or increment or decrement the
6129 current value by OFFSET). Note that this request does not cause a
6130 break, so changing the page offset in the middle of text being
6131 filled may not yield the expected result. The initial value is 1i.
6132 For TTY output devices, it is set to 0 in the startup file
6133 'troffrc'; the default scaling indicator is 'm' (and not 'v' as
6134 incorrectly documented in the original UNIX troff manual).
6136 The current page offset can be found in the read-only number
6139 If 'po' is called without an argument, the page offset is reset to
6140 the previous value before the last call to 'po'.
6152 -- Request: .in [indent]
6153 -- Request: .in +indent
6154 -- Request: .in -indent
6156 Set indentation to INDENT (or increment or decrement the current
6157 value by INDENT). This request causes a break. Initially, there
6160 If 'in' is called without an argument, the indentation is reset to
6161 the previous value before the last call to 'in'. The default
6162 scaling indicator is 'm'.
6164 The indentation is associated with the current environment (*note
6167 If a negative indentation value is specified (which is not
6168 allowed), 'gtroff' emits a warning of type 'range' and sets the
6169 indentation to zero.
6171 The effect of 'in' is delayed until a partially collected line (if
6172 it exists) is output. A temporary indentation value is reset to
6175 The current indentation (as set by 'in') can be found in the
6176 read-only number register '.i'.
6178 -- Request: .ti offset
6179 -- Request: .ti +offset
6180 -- Request: .ti -offset
6181 -- Register: \n[.in]
6182 Temporarily indent the next output line by OFFSET. If an increment
6183 or decrement value is specified, adjust the temporary indentation
6184 relative to the value set by the 'in' request.
6186 This request causes a break; its value is associated with the
6187 current environment (*note Environments::). The default scaling
6188 indicator is 'm'. A call of 'ti' without an argument is ignored.
6190 If the total indentation value is negative (which is not allowed),
6191 'gtroff' emits a warning of type 'range' and sets the temporary
6192 indentation to zero. 'Total indentation' is either OFFSET if
6193 specified as an absolute value, or the temporary plus normal
6194 indentation, if OFFSET is given as a relative value.
6196 The effect of 'ti' is delayed until a partially collected line (if
6197 it exists) is output.
6199 The read-only number register '.in' is the indentation that applies
6200 to the current output line.
6202 The difference between '.i' and '.in' is that the latter takes into
6203 account whether a partially collected line still uses the old
6204 indentation value or a temporary indentation value is active.
6206 -- Request: .ll [length]
6207 -- Request: .ll +length
6208 -- Request: .ll -length
6210 -- Register: \n[.ll]
6211 Set the line length to LENGTH (or increment or decrement the
6212 current value by LENGTH). Initially, the line length is set to
6213 6.5i. The effect of 'll' is delayed until a partially collected
6214 line (if it exists) is output. The default scaling indicator is
6217 If 'll' is called without an argument, the line length is reset to
6218 the previous value before the last call to 'll'. If a negative
6219 line length is specified (which is not allowed), 'gtroff' emits a
6220 warning of type 'range' and sets the line length to zero.
6222 The line length is associated with the current environment (*note
6225 The current line length (as set by 'll') can be found in the
6226 read-only number register '.l'. The read-only number register
6227 '.ll' is the line length that applies to the current output line.
6229 Similar to '.i' and '.in', the difference between '.l' and '.ll' is
6230 that the latter takes into account whether a partially collected
6231 line still uses the old line length value.
6234 File: groff.info, Node: Line Control, Next: Page Layout, Prev: Line Layout, Up: gtroff Reference
6239 It is important to understand how 'gtroff' handles input and output
6242 Many escapes use positioning relative to the input line. For
6245 This is a \h'|1.2i'test.
6256 The main usage of this feature is to define macros that act exactly
6257 at the place where called.
6259 .\" A simple macro to underline a word
6261 . nop \\$1\l'|0\[ul]'
6264 In the above example, '|0' specifies a negative distance from the
6265 current position (at the end of the just emitted argument '\$1') back to
6266 the beginning of the input line. Thus, the '\l' escape draws a line
6269 'gtroff' makes a difference between input and output line
6270 continuation; the latter is also called "interrupting" a line.
6274 -- Register: \n[.int]
6275 Continue a line. '\<RET>' (this is a backslash at the end of a
6276 line immediately followed by a newline) works on the input level,
6277 suppressing the effects of the following newline in the input.
6283 The '|' operator is also affected.
6285 '\c' works on the output level. Anything after this escape on the
6286 same line is ignored except '\R', which works as usual. Anything
6287 before '\c' on the same line is appended to the current partial
6288 output line. The next non-command line after an interrupted line
6289 counts as a new input line.
6291 The visual results depend on whether no-fill mode is active.
6293 * If no-fill mode is active (using the 'nf' request), the next
6294 input text line after '\c' is handled as a continuation of the
6295 same input text line.
6302 * If fill mode is active (using the 'fi' request), a word
6303 interrupted with '\c' is continued with the text on the next
6304 input text line, without an intervening space.
6310 Note that an intervening control line that causes a break is
6311 stronger than '\c', flushing out the current partial line in the
6314 The '.int' register contains a positive value if the last output
6315 line was interrupted with '\c'; this is associated with the current
6316 environment (*note Environments::).
6319 File: groff.info, Node: Page Layout, Next: Page Control, Prev: Line Control, Up: gtroff Reference
6324 'gtroff' provides some very primitive operations for controlling page
6327 -- Request: .pl [length]
6328 -- Request: .pl +length
6329 -- Request: .pl -length
6331 Set the "page length" to LENGTH (or increment or decrement the
6332 current value by LENGTH). This is the length of the physical
6333 output page. The default scaling indicator is 'v'.
6335 The current setting can be found in the read-only number register
6338 Note that this only specifies the size of the page, not the top and
6339 bottom margins. Those are not set by 'gtroff' directly. *Note
6340 Traps::, for further information on how to do this.
6342 Negative 'pl' values are possible also, but not very useful: No
6343 trap is sprung, and each line is output on a single page (thus
6344 suppressing all vertical spacing).
6346 If no argument or an invalid argument is given, 'pl' sets the page
6349 'gtroff' provides several operations that help in setting up top and
6350 bottom titles (or headers and footers).
6352 -- Request: .tl 'left'center'right'
6353 Print a "title line". It consists of three parts: a left justified
6354 portion, a centered portion, and a right justified portion. The
6355 argument separator ''' can be replaced with any character not
6356 occurring in the title line. The '%' character is replaced with
6357 the current page number. This character can be changed with the
6358 'pc' request (see below).
6360 Without argument, 'tl' is ignored.
6364 * The line length set by the 'll' request is not honoured by
6365 'tl'; use the 'lt' request (described below) instead, to
6366 control line length for text set by 'tl'.
6368 * A title line is not restricted to the top or bottom of a page.
6370 * 'tl' prints the title line immediately, ignoring a partially
6371 filled line (which stays untouched).
6373 * It is not an error to omit closing delimiters. For example,
6374 '.tl /foo' is equivalent to '.tl /foo///': It prints a title
6375 line with the left justified word 'foo'; the centered and
6376 right justfied parts are empty.
6378 * 'tl' accepts the same parameter delimiting characters as the
6379 '\A' escape; see *note Escapes::.
6381 -- Request: .lt [length]
6382 -- Request: .lt +length
6383 -- Request: .lt -length
6384 -- Register: \n[.lt]
6385 The title line is printed using its own line length, which is
6386 specified (or incremented or decremented) with the 'lt' request.
6387 Initially, the title line length is set to 6.5i. If a negative
6388 line length is specified (which is not allowed), 'gtroff' emits a
6389 warning of type 'range' and sets the title line length to zero.
6390 The default scaling indicator is 'm'. If 'lt' is called without an
6391 argument, the title length is reset to the previous value before
6392 the last call to 'lt'.
6394 The current setting of this is available in the '.lt' read-only
6395 number register; it is associated with the current environment
6396 (*note Environments::).
6398 -- Request: .pn page
6399 -- Request: .pn +page
6400 -- Request: .pn -page
6401 -- Register: \n[.pn]
6402 Change (increase or decrease) the page number of the _next_ page.
6403 The only argument is the page number; the request is ignored
6404 without a parameter.
6406 The read-only number register '.pn' contains the number of the next
6407 page: either the value set by a 'pn' request, or the number of the
6408 current page plus 1.
6410 -- Request: .pc [char]
6411 Change the page number character (used by the 'tl' request) to a
6412 different character. With no argument, this mechanism is disabled.
6413 Note that this doesn't affect the number register '%'.
6418 File: groff.info, Node: Page Control, Next: Fonts and Symbols, Prev: Page Layout, Up: gtroff Reference
6423 -- Request: .bp [page]
6424 -- Request: .bp +page
6425 -- Request: .bp -page
6427 Stop processing the current page and move to the next page. This
6428 request causes a break. It can also take an argument to set
6429 (increase, decrease) the page number of the next page (which
6430 actually becomes the current page after 'bp' has finished). The
6431 difference between 'bp' and 'pn' is that 'pn' does not cause a
6432 break or actually eject a page. *Note Page Layout::.
6434 .de newpage \" define macro
6436 'sp .5i \" vertical space
6437 .tl 'left top'center top'right top' \" title
6438 'sp .3i \" vertical space
6441 'bp' has no effect if not called within the top-level diversion
6442 (*note Diversions::).
6444 The read-write register '%' holds the current page number.
6446 The number register '.pe' is set to 1 while 'bp' is active. *Note
6447 Page Location Traps::.
6449 -- Request: .ne [space]
6450 It is often necessary to force a certain amount of space before a
6451 new page occurs. This is most useful to make sure that there is
6452 not a single "orphan" line left at the bottom of a page. The 'ne'
6453 request ensures that there is a certain distance, specified by the
6454 first argument, before the next page is triggered (see *note
6455 Traps::, for further information). The default scaling indicator
6456 for 'ne' is 'v'; the default value of SPACE is 1v if no argument is
6459 For example, to make sure that no fewer than 2 lines get orphaned,
6460 do the following before each paragraph:
6465 'ne' then automatically causes a page break if there is space for
6468 -- Request: .sv [space]
6470 'sv' is similar to the 'ne' request; it reserves the specified
6471 amount of vertical space. If the desired amount of space exists
6472 before the next trap (or the bottom page boundary if no trap is
6473 set), the space is output immediately (ignoring a partially filled
6474 line, which stays untouched). If there is not enough space, it is
6475 stored for later output via the 'os' request. The default value
6476 is 1v if no argument is given; the default scaling indicator is
6479 Both 'sv' and 'os' ignore no-space mode. While the 'sv' request
6480 allows negative values for SPACE, 'os' ignores them.
6483 This register contains the current vertical position. If the
6484 vertical position is zero and the top of page transition hasn't
6485 happened yet, 'nl' is set to negative value. 'gtroff' itself does
6486 this at the very beginning of a document before anything has been
6487 printed, but the main usage is to plant a header trap on a page if
6488 this page has already started.
6490 Consider the following:
6516 Without resetting 'nl' to a negative value, the just planted trap
6517 would be active beginning with the _next_ page, not the current
6520 *Note Diversions::, for a comparison with the '.h' and '.d'
6524 File: groff.info, Node: Fonts and Symbols, Next: Sizes, Prev: Page Control, Up: gtroff Reference
6526 5.17 Fonts and Symbols
6527 ======================
6529 'gtroff' can switch fonts at any point in the text.
6531 The basic set of fonts is 'R', 'I', 'B', and 'BI'. These are Times
6532 Roman, Italic, Bold, and Bold Italic. For non-TTY devices, there is
6533 also at least one symbol font that contains various special symbols
6534 (Greek, mathematics).
6542 * Character Classes::
6544 * Artificial Fonts::
6545 * Ligatures and Kerning::
6548 File: groff.info, Node: Changing Fonts, Next: Font Families, Prev: Fonts and Symbols, Up: Fonts and Symbols
6550 5.17.1 Changing Fonts
6551 ---------------------
6553 -- Request: .ft [font]
6557 -- Register: \n[.sty]
6558 The 'ft' request and the '\f' escape change the current font to
6559 FONT (one-character name F, two-character name FN).
6561 If FONT is a style name (as set with the 'sty' request or with the
6562 'styles' command in the 'DESC' file), use it within the current
6563 font family (as set with the 'fam' request, '\F' escape, or with
6564 the 'family' command in the 'DESC' file).
6566 It is not possible to switch to a font with the name 'DESC'
6567 (whereas this name could be used as a style name; however, this is
6570 With no argument or using 'P' as an argument, '.ft' switches to the
6571 previous font. Use '\f[]' to do this with the escape. The old
6572 syntax forms '\fP' or '\f[P]' are also supported.
6574 Fonts are generally specified as upper-case strings, which are
6575 usually 1 to 4 characters representing an abbreviation or acronym
6576 of the font name. This is no limitation, just a convention.
6578 The example below produces two identical lines.
6586 eggs, bacon, \fBspam\fP and sausage.
6588 Note that '\f' doesn't produce an input token in 'gtroff'. As a
6589 consequence, it can be used in requests like 'mc' (which expects a
6590 single character as an argument) to change the font on the fly:
6594 The current style name is available in the read-only number
6595 register '.sty' (this is a string-valued register); if the current
6596 font isn't a style, the empty string is returned. It is associated
6597 with the current environment.
6599 *Note Font Positions::, for an alternative syntax.
6601 -- Request: .ftr f [g]
6602 Translate font F to font G. Whenever a font named F is referred to
6603 in a '\f' escape sequence, in the 'F' and 'S' conditional
6604 operators, or in the 'ft', 'ul', 'bd', 'cs', 'tkf', 'special',
6605 'fspecial', 'fp', or 'sty' requests, font G is used. If G is
6606 missing or equal to F the translation is undone.
6608 Note that it is not possible to chain font translations. Example:
6613 => warning: can't find font `XXX'
6615 -- Request: .fzoom f [zoom]
6616 -- Register: \n[.zoom]
6617 Set magnification of font F to factor ZOOM, which must be a
6618 non-negative integer multiple of 1/1000th. This request is useful
6619 to adjust the optical size of a font in relation to the others. In
6620 the example below, font 'CR' is magnified by 10% (the zoom factor
6626 Palatino and \f[CR]Courier\f[]
6628 A missing or zero value of ZOOM is the same as a value of 1000,
6629 which means no magnification. F must be a real font name, not a
6632 Note that the magnification of a font is completely transparent to
6633 troff; a change of the zoom factor doesn't cause any effect except
6634 that the dimensions of glyphs, (word) spaces, kerns, etc., of the
6635 affected font are adjusted accordingly.
6637 The zoom factor of the current font is available in the read-only
6638 number register '.zoom', in multiples of 1/1000th. It returns zero
6639 if there is no magnification.
6642 File: groff.info, Node: Font Families, Next: Font Positions, Prev: Changing Fonts, Up: Fonts and Symbols
6644 5.17.2 Font Families
6645 --------------------
6647 Due to the variety of fonts available, 'gtroff' has added the concept of
6648 "font families" and "font styles". The fonts are specified as the
6649 concatenation of the font family and style. Specifying a font without
6650 the family part causes 'gtroff' to use that style of the current family.
6652 Currently, fonts for the devices '-Tps', '-Tpdf', '-Tdvi', '-Tlj4',
6653 '-Tlbp', and the X11 fonts are set up to this mechanism. By default,
6654 'gtroff' uses the Times family with the four styles 'R', 'I', 'B', and
6657 This way, it is possible to use the basic four fonts and to select a
6658 different font family on the command line (*note Groff Options::).
6660 -- Request: .fam [family]
6661 -- Register: \n[.fam]
6664 -- Escape: \F[family]
6665 -- Register: \n[.fn]
6666 Switch font family to FAMILY (one-character name F, two-character
6667 name FM). If no argument is given, switch back to the previous
6668 font family. Use '\F[]' to do this with the escape. Note that
6669 '\FP' doesn't work; it selects font family 'P' instead.
6671 The value at start-up is 'T'. The current font family is available
6672 in the read-only number register '.fam' (this is a string-valued
6673 register); it is associated with the current environment.
6676 .fam H \" helvetica family
6677 spam, \" used font is family H + style R = HR
6678 .ft B \" family H + style B = font HB
6680 .fam T \" times family
6681 spam, \" used font is family T + style B = TB
6682 .ft AR \" font AR (not a style)
6684 .ft R \" family T + style R = font TR
6687 Note that '\F' doesn't produce an input token in 'gtroff'. As a
6688 consequence, it can be used in requests like 'mc' (which expects a
6689 single character as an argument) to change the font family on the
6694 The '.fn' register contains the current "real font name" of the
6695 current font. This is a string-valued register. If the current
6696 font is a style, the value of '\n[.fn]' is the proper concatenation
6697 of family and style name.
6699 -- Request: .sty n style
6700 Associate STYLE with font position N. A font position can be
6701 associated either with a font or with a style. The current font is
6702 the index of a font position and so is also either a font or a
6703 style. If it is a style, the font that is actually used is the
6704 font which name is the concatenation of the name of the current
6705 family and the name of the current style. For example, if the
6706 current font is 1 and font position 1 is associated with style 'R'
6707 and the current font family is 'T', then font 'TR' is used. If the
6708 current font is not a style, then the current family is ignored.
6709 If the requests 'cs', 'bd', 'tkf', 'uf', or 'fspecial' are applied
6710 to a style, they are instead applied to the member of the current
6711 family corresponding to that style.
6713 N must be a non-negative integer value.
6715 The default family can be set with the '-f' option (*note Groff
6716 Options::). The 'styles' command in the 'DESC' file controls which
6717 font positions (if any) are initially associated with styles rather
6718 than fonts. For example, the default setting for POSTSCRIPT fonts
6729 'fam' and '\F' always check whether the current font position is
6730 valid; this can give surprising results if the current font
6731 position is associated with a style.
6733 In the following example, we want to access the POSTSCRIPT font
6734 'FooBar' from the font family 'Foo':
6738 => warning: can't find font `FooR'
6740 The default font position at start-up is 1; for the POSTSCRIPT
6741 device, this is associated with style 'R', so 'gtroff' tries to
6744 A solution to this problem is to use a dummy font like the
6747 .fp 0 dummy TR \" set up dummy font at position 0
6748 .sty \n[.fp] Bar \" register style `Bar'
6749 .ft 0 \" switch to font at position 0
6750 .fam Foo \" activate family `Foo'
6751 .ft Bar \" switch to font `FooBar'
6753 *Note Font Positions::.
6756 File: groff.info, Node: Font Positions, Next: Using Symbols, Prev: Font Families, Up: Fonts and Symbols
6758 5.17.3 Font Positions
6759 ---------------------
6761 For the sake of old phototypesetters and compatibility with old versions
6762 of 'troff', 'gtroff' has the concept of font "positions", on which
6763 various fonts are mounted.
6765 -- Request: .fp pos font [external-name]
6767 -- Register: \n[.fp]
6768 Mount font FONT at position POS (which must be a non-negative
6769 integer). This numeric position can then be referred to with font
6770 changing commands. When 'gtroff' starts it is using font
6771 position 1 (which must exist; position 0 is unused usually at
6774 The current font in use, as a font position, is available in the
6775 read-only number register '.f'. This can be useful to remember the
6776 current font for later recall. It is associated with the current
6777 environment (*note Environments::).
6779 .nr save-font \n[.f]
6781 ... text text text ...
6784 The number of the next free font position is available in the
6785 read-only number register '.fp'. This is useful when mounting a
6788 .fp \n[.fp] NEATOFONT
6790 Fonts not listed in the 'DESC' file are automatically mounted on
6791 the next available font position when they are referenced. If a
6792 font is to be mounted explicitly with the 'fp' request on an unused
6793 font position, it should be mounted on the first unused font
6794 position, which can be found in the '.fp' register. Although
6795 'gtroff' does not enforce this strictly, it is not allowed to mount
6796 a font at a position whose number is much greater (approx. 1000
6797 positions) than that of any currently used position.
6799 The 'fp' request has an optional third argument. This argument
6800 gives the external name of the font, which is used for finding the
6801 font description file. The second argument gives the internal name
6802 of the font, which is used to refer to the font in 'gtroff' after
6803 it has been mounted. If there is no third argument then the
6804 internal name is used as the external name. This feature makes it
6805 possible to use fonts with long names in compatibility mode.
6807 Both the 'ft' request and the '\f' escape have alternative syntax
6808 forms to access font positions.
6814 Change the current font position to NNN (one-digit position N,
6815 two-digit position NN), which must be a non-negative integer.
6817 If NNN is associated with a style (as set with the 'sty' request or
6818 with the 'styles' command in the 'DESC' file), use it within the
6819 current font family (as set with the 'fam' request, the '\F'
6820 escape, or with the 'family' command in the 'DESC' file).
6825 .ft \" switch back to font 1
6829 this is font 1 again
6831 *Note Changing Fonts::, for the standard syntax form.
6834 File: groff.info, Node: Using Symbols, Next: Character Classes, Prev: Font Positions, Up: Fonts and Symbols
6836 5.17.4 Using Symbols
6837 --------------------
6839 A "glyph" is a graphical representation of a "character". While a
6840 character is an abstract entity containing semantic information, a glyph
6841 is something that can be actually seen on screen or paper. It is
6842 possible that a character has multiple glyph representation forms (for
6843 example, the character 'A' can be either written in a roman or an italic
6844 font, yielding two different glyphs); sometimes more than one character
6845 maps to a single glyph (this is a "ligature" - the most common is 'fi').
6847 A "symbol" is simply a named glyph. Within 'gtroff', all glyph names
6848 of a particular font are defined in its font file. If the user requests
6849 a glyph not available in this font, 'gtroff' looks up an ordered list of
6850 "special fonts". By default, the POSTSCRIPT output device supports the
6851 two special fonts 'SS' (slanted symbols) and 'S' (symbols) (the former
6852 is looked up before the latter). Other output devices use different
6853 names for special fonts. Fonts mounted with the 'fonts' keyword in the
6854 'DESC' file are globally available. To install additional special fonts
6855 locally (i.e. for a particular font), use the 'fspecial' request.
6857 Here the exact rules how 'gtroff' searches a given symbol:
6859 * If the symbol has been defined with the 'char' request, use it.
6860 This hides a symbol with the same name in the current font.
6862 * Check the current font.
6864 * If the symbol has been defined with the 'fchar' request, use it.
6866 * Check whether the current font has a font-specific list of special
6867 fonts; test all fonts in the order of appearance in the last
6868 'fspecial' call if appropriate.
6870 * If the symbol has been defined with the 'fschar' request for the
6871 current font, use it.
6873 * Check all fonts in the order of appearance in the last 'special'
6876 * If the symbol has been defined with the 'schar' request, use it.
6878 * As a last resort, consult all fonts loaded up to now for special
6879 fonts and check them, starting with the lowest font number. Note
6880 that this can sometimes lead to surprising results since the
6881 'fonts' line in the 'DESC' file often contains empty positions,
6882 which are filled later on. For example, consider the following:
6886 This mounts font 'foo' at font position 3. We assume that 'FOO' is
6887 a special font, containing glyph 'foo', and that no font has been
6888 loaded yet. The line
6892 makes font 'BAZ' special only if font 'BAR' is active. We further
6893 assume that 'BAZ' is really a special font, i.e., the font
6894 description file contains the 'special' keyword, and that it also
6895 contains glyph 'foo' with a special shape fitting to font 'BAR'.
6896 After executing 'fspecial', font 'BAR' is loaded at font
6897 position 1, and 'BAZ' at position 2.
6899 We now switch to a new font 'XXX', trying to access glyph 'foo'
6900 that is assumed to be missing. There are neither font-specific
6901 special fonts for 'XXX' nor any other fonts made special with the
6902 'special' request, so 'gtroff' starts the search for special fonts
6903 in the list of already mounted fonts, with increasing font
6904 positions. Consequently, it finds 'BAZ' before 'FOO' even for
6905 'XXX', which is not the intended behaviour.
6907 *Note Font Files::, and *note Special Fonts::, for more details.
6909 The list of available symbols is device dependent; see the
6910 'groff_char(7)' man page for a complete list of all glyphs. For
6913 man -Tdvi groff_char > groff_char.dvi
6915 for a list using the default DVI fonts (not all versions of the 'man'
6916 program support the '-T' option). If you want to use an additional
6917 macro package to change the used fonts, 'groff' must be called directly:
6919 groff -Tdvi -mec -man groff_char.7 > groff_char.dvi
6921 Glyph names not listed in groff_char(7) are derived algorithmically,
6922 using a simplified version of the Adobe Glyph List (AGL) algorithm,
6923 which is described in
6924 <http://partners.adobe.com/public/developer/opentype/index_glyph.html>.
6925 The (frozen) set of glyph names that can't be derived algorithmically is
6926 called "groff glyph list (GGL)".
6928 * A glyph for Unicode character U+XXXX[X[X]], which is not a
6929 composite character is named 'uXXXX[X[X]]'. X must be an uppercase
6930 hexadecimal digit. Examples: 'u1234', 'u008E', 'u12DB8'. The
6931 largest Unicode value is 0x10FFFF. There must be at least four 'X'
6932 digits; if necessary, add leading zeroes (after the 'u'). No zero
6933 padding is allowed for character codes greater than 0xFFFF.
6934 Surrogates (i.e., Unicode values greater than 0xFFFF represented
6935 with character codes from the surrogate area U+D800-U+DFFF) are not
6938 * A glyph representing more than a single input character is named
6940 'u' COMPONENT1 '_' COMPONENT2 '_' COMPONENT3 ...
6942 Example: 'u0045_0302_0301'.
6944 For simplicity, all Unicode characters that are composites must be
6945 decomposed maximally (this is normalization form D in the Unicode
6946 standard); for example, 'u00CA_0301' is not a valid glyph name
6947 since U+00CA (LATIN CAPITAL LETTER E WITH CIRCUMFLEX) can be
6948 further decomposed into U+0045 (LATIN CAPITAL LETTER E) and U+0302
6949 (COMBINING CIRCUMFLEX ACCENT). 'u0045_0302_0301' is thus the glyph
6950 name for U+1EBE, LATIN CAPITAL LETTER E WITH CIRCUMFLEX AND ACUTE.
6952 * groff maintains a table to decompose all algorithmically derived
6953 glyph names that are composites itself. For example, 'u0100'
6954 (LATIN LETTER A WITH MACRON) is automatically decomposed into
6955 'u0041_0304'. Additionally, a glyph name of the GGL is preferred
6956 to an algorithmically derived glyph name; groff also automatically
6957 does the mapping. Example: The glyph 'u0045_0302' is mapped to
6960 * glyph names of the GGL can't be used in composite glyph names; for
6961 example, '^E_u0301' is invalid.
6965 -- Escape: \[component1 component2 ...]
6966 Insert a symbol NAME (two-character name NM) or a composite glyph
6967 with component glyphs COMPONENT1, COMPONENT2, ... There is no
6968 special syntax for one-character names - the natural form '\N'
6969 would collide with escapes.(1) (*note Using Symbols-Footnote-1::)
6971 If NAME is undefined, a warning of type 'char' is generated, and
6972 the escape is ignored. *Note Debugging::, for information about
6975 groff resolves '\[...]' with more than a single component as
6978 * Any component that is found in the GGL is converted to the
6981 * Any component 'uXXXX' that is found in the list of
6982 decomposable glyphs is decomposed.
6984 * The resulting elements are then concatenated with '_' in
6985 between, dropping the leading 'u' in all elements but the
6988 No check for the existence of any component (similar to 'tr'
6994 'A' maps to 'u0041', 'ho' maps to 'u02DB', thus the final
6995 glyph name would be 'u0041_02DB'. Note this is not the
6996 expected result: The ogonek glyph 'ho' is a spacing ogonek,
6997 but for a proper composite a non-spacing ogonek (U+0328) is
6998 necessary. Looking into the file 'composite.tmac' one can
6999 find '.composite ho u0328', which changes the mapping of 'ho'
7000 while a composite glyph name is constructed, causing the final
7001 glyph name to be 'u0041_0328'.
7007 '^E' maps to 'u0045_0302', thus the final glyph name is
7008 'u0045_0302_0301' in all forms (assuming proper calls of the
7009 'composite' request).
7011 It is not possible to define glyphs with names like 'A ho' within a
7012 groff font file. This is not really a limitation; instead, you
7013 have to define 'u0041_0328'.
7016 Typeset the glyph named XXX.(2) (*note Using Symbols-Footnote-2::)
7017 Normally it is more convenient to use '\[XXX]', but '\C' has the
7018 advantage that it is compatible with newer versions of AT&T 'troff'
7019 and is available in compatibility mode.
7021 -- Request: .composite from to
7022 Map glyph name FROM to glyph name TO if it is used in '\[...]' with
7023 more than one component. See above for examples.
7025 This mapping is based on glyph names only; no check for the
7026 existence of either glyph is done.
7028 A set of default mappings for many accents can be found in the file
7029 'composite.tmac', which is loaded at start-up.
7032 Typeset the glyph with code N in the current font ('n' is *not* the
7033 input character code). The number N can be any non-negative
7034 decimal integer. Most devices only have glyphs with codes between
7035 0 and 255; the Unicode output device uses codes in the range
7036 0-65535. If the current font does not contain a glyph with that
7037 code, special fonts are _not_ searched. The '\N' escape sequence
7038 can be conveniently used in conjunction with the 'char' request:
7040 .char \[phone] \f[ZD]\N'37'
7042 The code of each glyph is given in the fourth column in the font
7043 description file after the 'charset' command. It is possible to
7044 include unnamed glyphs in the font description file by using a name
7045 of '---'; the '\N' escape sequence is the only way to use these.
7047 No kerning is applied to glyphs accessed with '\N'.
7049 Some escape sequences directly map onto special glyphs.
7052 This is a backslash followed by the apostrophe character, ASCII
7053 character '0x27' (EBCDIC character '0x7D'). The same as '\[aa]',
7057 This is a backslash followed by ASCII character '0x60' (EBCDIC
7058 character '0x79' usually). The same as '\[ga]', the grave accent.
7061 This is the same as '\[-]', the minus sign in the current font.
7064 This is the same as '\[ul]', the underline character.
7066 -- Request: .cflags n c1 c2 ...
7067 Input characters and symbols have certain properties associated
7068 with it.(3) (*note Using Symbols-Footnote-3::) These properties
7069 can be modified with the 'cflags' request. The first argument is
7070 the sum of the desired flags and the remaining arguments are the
7071 characters or symbols to have those properties. It is possible to
7072 omit the spaces between the characters or symbols. Instead of
7073 single characters or symbols you can also use character classes
7074 (see *note Character Classes:: for more details).
7077 The character ends sentences (initially characters '.?!' have
7081 Lines can be broken before the character (initially no
7082 characters have this property). This only works if both the
7083 characters before and after have non-zero hyphenation codes
7084 (as set with the 'hcode' request). Use value 64 to override
7088 Lines can be broken after the character (initially the
7089 character '-' and the symbols '\[hy]' and '\[em]' have this
7090 property). This only works if both the characters before and
7091 after have non-zero hyphenation codes (as set with the 'hcode'
7092 request). Use value 64 to override this behaviour.
7095 The character overlaps horizontally if used as a horizontal
7096 line building element. Initially the symbols '\[ul]',
7097 '\[rn]', '\[ru]', '\[radicalex]', and '\[sqrtex]' have this
7101 The character overlaps vertically if used as vertical line
7102 building element. Initially symbol '\[br]' has this property.
7105 An end-of-sentence character followed by any number of
7106 characters with this property is treated as the end of a
7107 sentence if followed by a newline or two spaces; in other
7108 words the character is "transparent" for the purposes of
7109 end-of-sentence recognition - this is the same as having a
7110 zero space factor in TeX (initially characters '"')]*' and the
7111 symbols '\[dg]', '\[rq]', and '\[cq]' have this property).
7114 Ignore hyphenation code values of the surrounding characters.
7115 Use this in combination with values 2 and 4 (initially no
7116 characters have this property). For example, if you need an
7117 automatic break point after the hyphen in number ranges like
7122 into your document. Note, however, that this can lead to bad
7123 layout if done without thinking; in most situations, a better
7124 solution instead of changing the 'cflags' value is to insert
7125 '\:' right after the hyphen at the places that really need a
7129 Prohibit a line break before the character, but allow a line
7130 break after the character. This works only in combination
7131 with flags 256 and 512 (see below) and has no effect
7135 Prohibit a line break after the character, but allow a line
7136 break before the character. This works only in combination
7137 with flags 128 and 512 (see below) and has no effect
7141 Allow line break before or after the character. This works
7142 only in combination with flags 128 and 256 and has no effect
7145 Contrary to flag values 2 and 4, the flags 128, 256, and 512
7146 work pairwise. If, for example, the left character has value
7147 512, and the right character 128, no line break gets inserted.
7148 If we use value 6 instead for the left character, a line break
7149 after the character can't be suppressed since the right
7150 neighbour character doesn't get examined.
7152 -- Request: .char g [string]
7153 -- Request: .fchar g [string]
7154 -- Request: .fschar f g [string]
7155 -- Request: .schar g [string]
7156 Define a new glyph G to be STRING (which can be empty).(4) (*note
7157 Using Symbols-Footnote-4::) Every time glyph G needs to be printed,
7158 STRING is processed in a temporary environment and the result is
7159 wrapped up into a single object. Compatibility mode is turned off
7160 and the escape character is set to '\' while STRING is being
7161 processed. Any emboldening, constant spacing or track kerning is
7162 applied to this object rather than to individual characters in
7165 A glyph defined by these requests can be used just like a normal
7166 glyph provided by the output device. In particular, other
7167 characters can be translated to it with the 'tr' or 'trin'
7168 requests; it can be made the leader character by the 'lc' request;
7169 repeated patterns can be drawn with the glyph using the '\l' and
7170 '\L' escape sequences; words containing the glyph can be hyphenated
7171 correctly if the 'hcode' request is used to give the glyph's symbol
7174 There is a special anti-recursion feature: Use of 'g' within the
7175 glyph's definition is handled like normal characters and symbols
7176 not defined with 'char'.
7178 Note that the 'tr' and 'trin' requests take precedence if 'char'
7179 accesses the same symbol.
7191 The 'fchar' request defines a fallback glyph: 'gtroff' only checks
7192 for glyphs defined with 'fchar' if it cannot find the glyph in the
7193 current font. 'gtroff' carries out this test before checking
7196 'fschar' defines a fallback glyph for font F: 'gtroff' checks for
7197 glyphs defined with 'fschar' after the list of fonts declared as
7198 font-specific special fonts with the 'fspecial' request, but before
7199 the list of fonts declared as global special fonts with the
7202 Finally, the 'schar' request defines a global fallback glyph:
7203 'gtroff' checks for glyphs defined with 'schar' after the list of
7204 fonts declared as global special fonts with the 'special' request,
7205 but before the already mounted special fonts.
7207 *Note Using Symbols::, for a detailed description of the glyph
7208 searching mechanism in 'gtroff'.
7210 -- Request: .rchar c1 c2 ...
7211 -- Request: .rfschar f c1 c2 ...
7212 Remove the definitions of glyphs C1, C2, ... This undoes the
7213 effect of a 'char', 'fchar', or 'schar' request.
7215 It is possible to omit the whitespace between arguments.
7217 The request 'rfschar' removes glyph definitions defined with
7218 'fschar' for glyph f.
7220 *Note Special Characters::.
7223 File: groff.info, Node: Using Symbols-Footnotes, Up: Using Symbols
7225 (1) Note that a one-character symbol is not the same as an input
7226 character, i.e., the character 'a' is not the same as '\[a]'. By
7227 default, 'groff' defines only a single one-character symbol, '\[-]'; it
7228 is usually accessed as '\-'. On the other hand, 'gtroff' has the
7229 special feature that '\[charXXX]' is the same as the input character
7230 with character code XXX. For example, '\[char97]' is identical to the
7231 letter 'a' if ASCII encoding is active.
7233 (2) '\C' is actually a misnomer since it accesses an output glyph.
7235 (3) Note that the output glyphs themselves don't have such
7236 properties. For 'gtroff', a glyph is a numbered box with a given width,
7237 depth, and height, nothing else. All manipulations with the 'cflags'
7238 request work on the input level.
7240 (4) 'char' is a misnomer since an output glyph is defined.
7243 File: groff.info, Node: Character Classes, Next: Special Fonts, Prev: Using Symbols, Up: Fonts and Symbols
7245 5.17.5 Character Classes
7246 ------------------------
7248 Classes are particularly useful for East Asian languages such as
7249 Chinese, Japanese, and Korean, where the number of needed characters is
7250 much larger than in European languages, and where large sets of
7251 characters share the same properties.
7253 -- Request: .class n c1 c2 ...
7254 In 'groff', a "character class" (or simply "class") is a set of
7255 characters, grouped by some user aspect. The 'class' request
7256 defines such classes so that other requests can refer to all
7257 characters belonging to this set with a single class name.
7258 Currently, only the 'cflags' request can handle character classes.
7260 A 'class' request takes a class name followed by a list of
7261 entities. In its simplest form, the entities are characters or
7264 .class [prepunct] , : ; > }
7266 Since class and glyph names share the same namespace, it is
7267 recommended to start and end the class name with '[' and ']',
7268 respectively, to avoid collisions with normal 'groff' symbols (and
7269 symbols defined by the user). In particular, the presence of ']'
7270 in the symbol name intentionally prevents the usage of '\[...]',
7271 thus you must use the '\C' escape to access a class with such a
7274 You can also use a special character range notation, consisting of
7275 a start character or symbol, followed by '-', and an end character
7276 or symbol. Internally, 'gtroff' converts these two symbol names to
7277 Unicode values (according to the groff glyph gist), which then give
7278 the start and end value of the range. If that fails, the class
7279 definition is skipped.
7281 Finally, classes can be nested, too.
7283 Here is a more complex example:
7285 .class [prepunctx] \C'[prepunct]' \[u2013]-\[u2016]
7287 The class 'prepunctx' now contains the contents of the class
7288 'prepunct' as defined above (the set ', : ; > }'), and characters
7289 in the range between 'U+2013' and 'U+2016'.
7291 If you want to add '-' to a class, it must be the first character
7292 value in the argument list, otherwise it gets misinterpreted as a
7295 Note that it is not possible to use class names within range
7298 Typical use of the 'class' request is to control line-breaking and
7299 hyphenation rules as defined by the 'cflags' request. For example,
7300 to inhibit line breaks before the characters belonging to the
7301 'prepunctx' class, you can write:
7303 .cflags 2 \C'[prepunctx]'
7305 See the 'cflags' request in *note Using Symbols::, for more
7309 File: groff.info, Node: Special Fonts, Next: Artificial Fonts, Prev: Character Classes, Up: Fonts and Symbols
7311 5.17.6 Special Fonts
7312 --------------------
7314 Special fonts are those that 'gtroff' searches when it cannot find the
7315 requested glyph in the current font. The Symbol font is usually a
7318 'gtroff' provides the following two requests to add more special
7319 fonts. *Note Using Symbols::, for a detailed description of the glyph
7320 searching mechanism in 'gtroff'.
7322 Usually, only non-TTY devices have special fonts.
7324 -- Request: .special [s1 s2 ...]
7325 -- Request: .fspecial f [s1 s2 ...]
7326 Use the 'special' request to define special fonts. Initially, this
7329 Use the 'fspecial' request to designate special fonts only when
7330 font F is active. Initially, this list is empty.
7332 Previous calls to 'special' or 'fspecial' are overwritten; without
7333 arguments, the particular list of special fonts is set to empty.
7334 Special fonts are searched in the order they appear as arguments.
7336 All fonts that appear in a call to 'special' or 'fspecial' are
7339 *Note Using Symbols::, for the exact search order of glyphs.
7342 File: groff.info, Node: Artificial Fonts, Next: Ligatures and Kerning, Prev: Special Fonts, Up: Fonts and Symbols
7344 5.17.7 Artificial Fonts
7345 -----------------------
7347 There are a number of requests and escapes for artificially creating
7348 fonts. These are largely vestiges of the days when output devices did
7349 not have a wide variety of fonts, and when 'nroff' and 'troff' were
7350 separate programs. Most of them are no longer necessary in GNU 'troff'.
7351 Nevertheless, they are supported.
7353 -- Escape: \H'height'
7354 -- Escape: \H'+height'
7355 -- Escape: \H'-height'
7356 -- Register: \n[.height]
7357 Change (increment, decrement) the height of the current font, but
7358 not the width. If HEIGHT is zero, restore the original height.
7359 Default scaling indicator is 'z'.
7361 The read-only number register '.height' contains the font height as
7364 Currently, only the '-Tps' and '-Tpdf' devices support this
7367 Note that '\H' doesn't produce an input token in 'gtroff'. As a
7368 consequence, it can be used in requests like 'mc' (which expects a
7369 single character as an argument) to change the font on the fly:
7373 In compatibility mode, 'gtroff' behaves differently: If an
7374 increment or decrement is used, it is always taken relative to the
7375 current point size and not relative to the previously selected font
7379 \H'+5'test \H'+5'test
7381 prints the word 'test' twice with the same font height (five points
7382 larger than the current font size).
7384 -- Escape: \S'slant'
7385 -- Register: \n[.slant]
7386 Slant the current font by SLANT degrees. Positive values slant to
7387 the right. Only integer values are possible.
7389 The read-only number register '.slant' contains the font slant as
7392 Currently, only the '-Tps' and '-Tpdf' devices support this
7395 Note that '\S' doesn't produce an input token in 'gtroff'. As a
7396 consequence, it can be used in requests like 'mc' (which expects a
7397 single character as an argument) to change the font on the fly:
7401 This request is incorrectly documented in the original UNIX troff
7402 manual; the slant is always set to an absolute value.
7404 -- Request: .ul [lines]
7405 The 'ul' request normally underlines subsequent lines if a TTY
7406 output device is used. Otherwise, the lines are printed in italics
7407 (only the term 'underlined' is used in the following). The single
7408 argument is the number of input lines to be underlined; with no
7409 argument, the next line is underlined. If LINES is zero or
7410 negative, stop the effects of 'ul' (if it was active). Requests
7411 and empty lines do not count for computing the number of underlined
7412 input lines, even if they produce some output like 'tl'. Lines
7413 inserted by macros (e.g. invoked by a trap) do count.
7415 At the beginning of 'ul', the current font is stored and the
7416 underline font is activated. Within the span of a 'ul' request, it
7417 is possible to change fonts, but after the last line affected by
7418 'ul' the saved font is restored.
7420 This number of lines still to be underlined is associated with the
7421 current environment (*note Environments::). The underline font can
7422 be changed with the 'uf' request.
7424 The 'ul' request does not underline spaces.
7426 -- Request: .cu [lines]
7427 The 'cu' request is similar to 'ul' but underlines spaces as well
7428 (if a TTY output device is used).
7430 -- Request: .uf font
7431 Set the underline font (globally) used by 'ul' and 'cu'. By
7432 default, this is the font at position 2. FONT can be either a
7433 non-negative font position or the name of a font.
7435 -- Request: .bd font [offset]
7436 -- Request: .bd font1 font2 [offset]
7438 Artificially create a bold font by printing each glyph twice,
7441 Two syntax forms are available.
7443 * Imitate a bold font unconditionally. The first argument
7444 specifies the font to embolden, and the second is the number
7445 of basic units, minus one, by which the two glyphs are offset.
7446 If the second argument is missing, emboldening is turned off.
7448 FONT can be either a non-negative font position or the name of
7451 OFFSET is available in the '.b' read-only register if a
7452 special font is active; in the 'bd' request, its default unit
7455 * Imitate a bold form conditionally. Embolden FONT1 by OFFSET
7456 only if font FONT2 is the current font. This command can be
7457 issued repeatedly to set up different emboldening values for
7458 different current fonts. If the second argument is missing,
7459 emboldening is turned off for this particular current font.
7461 This affects special fonts only (either set up with the
7462 'special' command in font files or with the 'fspecial'
7465 -- Request: .cs font [width [em-size]]
7466 Switch to and from "constant glyph space mode". If activated, the
7467 width of every glyph is WIDTH/36 ems. The em size is given
7468 absolutely by EM-SIZE; if this argument is missing, the em value is
7469 taken from the current font size (as set with the 'ps' request)
7470 when the font is effectively in use. Without second and third
7471 argument, constant glyph space mode is deactivated.
7473 Default scaling indicator for EM-SIZE is 'z'; WIDTH is an integer.
7476 File: groff.info, Node: Ligatures and Kerning, Prev: Artificial Fonts, Up: Fonts and Symbols
7478 5.17.8 Ligatures and Kerning
7479 ----------------------------
7481 Ligatures are groups of characters that are run together, i.e, producing
7482 a single glyph. For example, the letters 'f' and 'i' can form a
7483 ligature 'fi' as in the word 'file'. This produces a cleaner look
7484 (albeit subtle) to the printed output. Usually, ligatures are not
7485 available in fonts for TTY output devices.
7487 Most POSTSCRIPT fonts support the fi and fl ligatures. The C/A/T
7488 typesetter that was the target of AT&T 'troff' also supported 'ff',
7489 'ffi', and 'ffl' ligatures. Advanced typesetters or 'expert' fonts may
7490 include ligatures for 'ft' and 'ct', although GNU 'troff' does not
7491 support these (yet).
7493 Only the current font is checked for ligatures and kerns; neither
7494 special fonts nor entities defined with the 'char' request (and its
7495 siblings) are taken into account.
7497 -- Request: .lg [flag]
7498 -- Register: \n[.lg]
7499 Switch the ligature mechanism on or off; if the parameter is
7500 non-zero or missing, ligatures are enabled, otherwise disabled.
7501 Default is on. The current ligature mode can be found in the
7502 read-only number register '.lg' (set to 1 or 2 if ligatures are
7503 enabled, 0 otherwise).
7505 Setting the ligature mode to 2 enables the two-character ligatures
7506 (fi, fl, and ff) and disables the three-character ligatures (ffi
7509 "Pairwise kerning" is another subtle typesetting mechanism that
7510 modifies the distance between a glyph pair to improve readability. In
7511 most cases (but not always) the distance is decreased. Typewriter-like
7512 fonts and fonts for terminals where all glyphs have the same width don't
7515 -- Request: .kern [flag]
7516 -- Register: \n[.kern]
7517 Switch kerning on or off. If the parameter is non-zero or missing,
7518 enable pairwise kerning, otherwise disable it. The read-only
7519 number register '.kern' is set to 1 if pairwise kerning is enabled,
7522 If the font description file contains pairwise kerning information,
7523 glyphs from that font are kerned. Kerning between two glyphs can
7524 be inhibited by placing '\&' between them: 'V\&A'.
7526 *Note Font File Format::.
7528 "Track kerning" expands or reduces the space between glyphs. This
7529 can be handy, for example, if you need to squeeze a long word onto a
7530 single line or spread some text to fill a narrow column. It must be
7531 used with great care since it is usually considered bad typography if
7532 the reader notices the effect.
7534 -- Request: .tkf f s1 n1 s2 n2
7535 Enable track kerning for font F. If the current font is F the
7536 width of every glyph is increased by an amount between N1 and N2
7537 (N1, N2 can be negative); if the current point size is less than or
7538 equal to S1 the width is increased by N1; if it is greater than or
7539 equal to S2 the width is increased by N2; if the point size is
7540 greater than or equal to S1 and less than or equal to S2 the
7541 increase in width is a linear function of the point size.
7543 The default scaling indicator is 'z' for S1 and S2, 'p' for N1 and
7546 Note that the track kerning amount is added even to the rightmost
7547 glyph in a line; for large values it is thus recommended to
7548 increase the line length by the same amount to compensate it.
7550 Sometimes, when typesetting letters of different fonts, more or less
7551 space at such boundaries are needed. There are two escapes to help with
7555 Increase the width of the preceding glyph so that the spacing
7556 between that glyph and the following glyph is correct if the
7557 following glyph is a roman glyph. For example, if an italic 'f' is
7558 immediately followed by a roman right parenthesis, then in many
7559 fonts the top right portion of the 'f' overlaps the top left of the
7560 right parenthesis. Use this escape sequence whenever an italic
7561 glyph is immediately followed by a roman glyph without any
7562 intervening space. This small amount of space is also called
7563 "italic correction".
7566 Modify the spacing of the following glyph so that the spacing
7567 between that glyph and the preceding glyph is correct if the
7568 preceding glyph is a roman glyph. Use this escape sequence
7569 whenever a roman glyph is immediately followed by an italic glyph
7570 without any intervening space. In analogy to above, this space
7571 could be called "left italic correction", but this term isn't used
7575 Insert a zero-width character, which is invisible. Its intended
7576 use is to stop interaction of a character with its surrounding.
7578 * It prevents the insertion of extra space after an
7579 end-of-sentence character.
7588 * It prevents interpretation of a control character at the
7589 beginning of an input line.
7592 => warning: `Test' not defined
7596 * It prevents kerning between two glyphs.
7598 * It is needed to map an arbitrary character to nothing in the
7599 'tr' request (*note Character Translations::).
7602 This escape is similar to '\&' except that it behaves like a
7603 character declared with the 'cflags' request to be transparent for
7604 the purposes of an end-of-sentence character.
7606 Its main usage is in macro definitions to protect against arguments
7607 starting with a control character.
7618 =>This is a test.' This is a test.
7622 =>This is a test.' This is a test.
7625 File: groff.info, Node: Sizes, Next: Strings, Prev: Fonts and Symbols, Up: gtroff Reference
7630 'gtroff' uses two dimensions with each line of text, type size and
7631 vertical spacing. The "type size" is approximately the height of the
7632 tallest glyph.(1) (*note Sizes-Footnote-1::) "Vertical spacing" is the
7633 amount of space 'gtroff' allows for a line of text; normally, this is
7634 about 20% larger than the current type size. Ratios smaller than this
7635 can result in hard-to-read text; larger than this, it spreads the text
7636 out more vertically (useful for term papers). By default, 'gtroff' uses
7637 10 point type on 12 point spacing.
7639 The difference between type size and vertical spacing is known, by
7640 typesetters, as "leading" (this is pronounced 'ledding').
7644 * Changing Type Sizes::
7645 * Fractional Type Sizes::
7648 File: groff.info, Node: Sizes-Footnotes, Up: Sizes
7650 (1) This is usually the parenthesis. Note that in most cases the
7651 real dimensions of the glyphs in a font are _not_ related to its type
7652 size! For example, the standard POSTSCRIPT font families 'Times Roman',
7653 'Helvetica', and 'Courier' can't be used together at 10pt; to get
7654 acceptable output, the size of 'Helvetica' has to be reduced by one
7655 point, and the size of 'Courier' must be increased by one point.
7658 File: groff.info, Node: Changing Type Sizes, Next: Fractional Type Sizes, Prev: Sizes, Up: Sizes
7660 5.18.1 Changing Type Sizes
7661 --------------------------
7663 -- Request: .ps [size]
7664 -- Request: .ps +size
7665 -- Request: .ps -size
7668 Use the 'ps' request or the '\s' escape to change (increase,
7669 decrease) the type size (in points). Specify SIZE as either an
7670 absolute point size, or as a relative change from the current size.
7671 The size 0 (for both '.ps' and '\s'), or no argument (for '.ps'
7672 only), goes back to the previous size.
7674 Default scaling indicator of 'size' is 'z'. If 'size' is negative,
7677 The read-only number register '.s' returns the point size in points
7678 as a decimal fraction. This is a string. To get the point size in
7679 scaled points, use the '.ps' register instead.
7681 '.s' is associated with the current environment (*note
7688 wink, wink, \s+2nudge, nudge,\s+8 say no more!
7691 The '\s' escape may be called in a variety of ways. Much like
7692 other escapes there must be a way to determine where the argument
7693 ends and the text begins. Any of the following forms are valid:
7696 Set the point size to N points. N must be either 0 or in the
7701 Increase or decrease the point size by N points. N must be
7705 Set the point size to NN points. NN must be exactly two
7712 Increase or decrease the point size by NN points. NN must be
7715 Note that '\s' doesn't produce an input token in 'gtroff'. As a
7716 consequence, it can be used in requests like 'mc' (which expects a
7717 single character as an argument) to change the font on the fly:
7721 *Note Fractional Type Sizes::, for yet another syntactical form of
7722 using the '\s' escape.
7724 -- Request: .sizes s1 s2 ... sn [0]
7725 Some devices may only have certain permissible sizes, in which case
7726 'gtroff' rounds to the nearest permissible size. The 'DESC' file
7727 specifies which sizes are permissible for the device.
7729 Use the 'sizes' request to change the permissible sizes for the
7730 current output device. Arguments are in scaled points; the
7731 'sizescale' line in the 'DESC' file for the output device provides
7732 the scaling factor. For example, if the scaling factor is 1000,
7733 then the value 12000 is 12 points.
7735 Each argument can be a single point size (such as '12000'), or a
7736 range of sizes (such as '4000-72000'). You can optionally end the
7739 -- Request: .vs [space]
7740 -- Request: .vs +space
7741 -- Request: .vs -space
7743 Change (increase, decrease) the vertical spacing by SPACE. The
7744 default scaling indicator is 'p'.
7746 If 'vs' is called without an argument, the vertical spacing is
7747 reset to the previous value before the last call to 'vs'.
7749 'gtroff' creates a warning of type 'range' if SPACE is negative;
7750 the vertical spacing is then set to smallest positive value, the
7751 vertical resolution (as given in the '.V' register).
7753 Note that '.vs 0' isn't saved in a diversion since it doesn't
7754 result in a vertical motion. You explicitly have to repeat this
7755 command before inserting the diversion.
7757 The read-only number register '.v' contains the current vertical
7758 spacing; it is associated with the current environment (*note
7761 The effective vertical line spacing consists of four components.
7762 Breaking a line causes the following actions (in the given order).
7764 * Move the current point vertically by the "extra pre-vertical line
7765 space". This is the minimum value of all '\x' escapes with a
7766 negative argument in the current output line.
7768 * Move the current point vertically by the vertical line spacing as
7769 set with the 'vs' request.
7771 * Output the current line.
7773 * Move the current point vertically by the "extra post-vertical line
7774 space". This is the maximum value of all '\x' escapes with a
7775 positive argument in the line that has just been output.
7777 * Move the current point vertically by the "post-vertical line
7778 spacing" as set with the 'pvs' request.
7780 It is usually better to use 'vs' or 'pvs' instead of 'ls' to produce
7781 double-spaced documents: 'vs' and 'pvs' have a finer granularity for the
7782 inserted vertical space compared to 'ls'; furthermore, certain
7783 preprocessors assume single-spacing.
7785 *Note Manipulating Spacing::, for more details on the '\x' escape and
7788 -- Request: .pvs [space]
7789 -- Request: .pvs +space
7790 -- Request: .pvs -space
7791 -- Register: \n[.pvs]
7792 Change (increase, decrease) the post-vertical spacing by SPACE.
7793 The default scaling indicator is 'p'.
7795 If 'pvs' is called without an argument, the post-vertical spacing
7796 is reset to the previous value before the last call to 'pvs'.
7798 'gtroff' creates a warning of type 'range' if SPACE is zero or
7799 negative; the vertical spacing is then set to zero.
7801 The read-only number register '.pvs' contains the current
7802 post-vertical spacing; it is associated with the current
7803 environment (*note Environments::).
7806 File: groff.info, Node: Fractional Type Sizes, Prev: Changing Type Sizes, Up: Sizes
7808 5.18.2 Fractional Type Sizes
7809 ----------------------------
7811 A "scaled point" is equal to 1/SIZESCALE points, where SIZESCALE is
7812 specified in the 'DESC' file (1 by default). There is a new scale
7813 indicator 'z', which has the effect of multiplying by SIZESCALE.
7814 Requests and escape sequences in 'gtroff' interpret arguments that
7815 represent a point size as being in units of scaled points, but they
7816 evaluate each such argument using a default scale indicator of 'z'.
7817 Arguments treated in this way are the argument to the 'ps' request, the
7818 third argument to the 'cs' request, the second and fourth arguments to
7819 the 'tkf' request, the argument to the '\H' escape sequence, and those
7820 variants of the '\s' escape sequence that take a numeric expression as
7821 their argument (see below).
7823 For example, suppose SIZESCALE is 1000; then a scaled point is
7824 equivalent to a millipoint; the request '.ps 10.25' is equivalent to
7825 '.ps 10.25z' and thus sets the point size to 10250 scaled points, which
7826 is equal to 10.25 points.
7828 'gtroff' disallows the use of the 'z' scale indicator in instances
7829 where it would make no sense, such as a numeric expression whose default
7830 scale indicator was neither 'u' nor 'z'. Similarly it would make no
7831 sense to use a scaling indicator other than 'z' or 'u' in a numeric
7832 expression whose default scale indicator was 'z', and so 'gtroff'
7833 disallows this as well.
7835 There is also new scale indicator 's', which multiplies by the number
7836 of units in a scaled point. So, for example, '\n[.ps]s' is equal to
7837 '1m'. Be sure not to confuse the 's' and 'z' scale indicators.
7839 -- Register: \n[.ps]
7840 A read-only number register returning the point size in scaled
7843 '.ps' is associated with the current environment (*note
7846 -- Register: \n[.psr]
7847 -- Register: \n[.sr]
7848 The last-requested point size in scaled points is contained in the
7849 '.psr' read-only number register. The last requested point size in
7850 points as a decimal fraction can be found in '.sr'. This is a
7851 string-valued read-only number register.
7853 Note that the requested point sizes are device-independent, whereas
7854 the values returned by the '.ps' and '.s' registers are not. For
7855 example, if a point size of 11pt is requested, and a 'sizes'
7856 request (or a 'sizescale' line in a 'DESC' file) specifies 10.95pt
7857 instead, this value is actually used.
7859 Both registers are associated with the current environment (*note
7862 The '\s' escape has the following syntax for working with fractional
7867 Set the point size to N scaled points; N is a numeric expression
7868 with a default scale indicator of 'z'.
7878 Increase or or decrease the point size by N scaled points; N is a
7879 numeric expression (which may start with a minus sign) with a
7880 default scale indicator of 'z'.
7885 File: groff.info, Node: Strings, Next: Conditionals and Loops, Prev: Sizes, Up: gtroff Reference
7890 'gtroff' has string variables, which are entirely for user convenience
7891 (i.e. there are no built-in strings exept '.T', but even this is a
7892 read-write string variable).
7894 Although the following requests can be used to create strings, simply
7895 using an undefined string will cause it to be defined as empty. *Note
7898 -- Request: .ds name [string]
7899 -- Request: .ds1 name [string]
7902 -- Escape: \*[name arg1 arg2 ...]
7903 Define and access a string variable NAME (one-character name N,
7904 two-character name NM). If NAME already exists, 'ds' overwrites
7905 the previous definition. Only the syntax form using brackets can
7906 take arguments that are handled identically to macro arguments; the
7907 single exception is that a closing bracket as an argument must be
7908 enclosed in double quotes. *Note Request and Macro Arguments::,
7909 and *note Parameters::.
7915 This is \*[foo nice].
7916 => This is a nice test.
7918 The '\*' escape "interpolates" (expands in-place) a
7919 previously-defined string variable. To be more precise, the stored
7920 string is pushed onto the input stack, which is then parsed by
7921 'gtroff'. Similar to number registers, it is possible to nest
7922 strings, i.e., string variables can be called within string
7925 If the string named by the '\*' escape does not exist, it is
7926 defined as empty, and a warning of type 'mac' is emitted (see *note
7927 Debugging::, for more details).
7929 *Caution:* Unlike other requests, the second argument to the 'ds'
7930 request takes up the entire line including trailing spaces. This
7931 means that comments on a line with such a request can introduce
7932 unwanted space into a string.
7934 .ds UX \s-1UNIX\s0\u\s-3tm\s0\d \" UNIX trademark
7936 Instead the comment should be put on another line or have the
7937 comment escape adjacent with the end of the string.
7939 .ds UX \s-1UNIX\s0\u\s-3tm\s0\d\" UNIX trademark
7941 To produce leading space the string can be started with a double
7942 quote. No trailing quote is needed; in fact, any trailing quote is
7943 included in your string.
7945 .ds sign " Yours in a white wine sauce,
7947 Strings are not limited to a single line of text. A string can
7948 span several lines by escaping the newlines with a backslash. The
7949 resulting string is stored _without_ the newlines.
7951 .ds foo lots and lots \
7952 of text are on these \
7955 It is not possible to have real newlines in a string. To put a
7956 single double quote character into a string, use two consecutive
7957 double quote characters.
7959 The 'ds1' request turns off compatibility mode while interpreting a
7960 string. To be more precise, a "compatibility save" input token is
7961 inserted at the beginning of the string, and a "compatibility
7962 restore" input token at the end.
7965 .ds aa The value of xxx is \\n[xxx].
7966 .ds1 bb The value of xxx ix \\n[xxx].
7971 => warning: number register `[' not defined
7972 => The value of xxx is 0xxx].
7974 => The value of xxx ix 12345.
7976 Strings, macros, and diversions (and boxes) share the same name
7977 space. Internally, even the same mechanism is used to store them.
7978 This has some interesting consequences. For example, it is
7979 possible to call a macro with string syntax and vice versa.
7985 => This is a funny test.
7987 .ds yyy a funny test
7990 => This is a funny test.
7992 In particular, interpolating a string does not hide existing macro
7993 arguments. Thus in a macro, a more efficient way of doing
8001 Note that the latter calling syntax doesn't change the value of
8002 '\$0', which is then inherited from the calling macro.
8004 Diversions and boxes can be also called with string syntax.
8006 Another consequence is that you can copy one-line diversions or
8013 .ds yyy This is \*[xxx]\c
8017 As the previous example shows, it is possible to store formatted
8018 output in strings. The '\c' escape prevents the insertion of an
8019 additional blank line in the output.
8021 Copying diversions longer than a single output line produces
8030 .ds yyy This is \*[xxx]\c
8032 => test This is a funny.
8034 Usually, it is not predictable whether a diversion contains one or
8035 more output lines, so this mechanism should be avoided. With UNIX
8036 'troff', this was the only solution to strip off a final newline
8037 from a diversion. Another disadvantage is that the spaces in the
8038 copied string are already formatted, making them unstretchable.
8039 This can cause ugly results.
8041 A clean solution to this problem is available in GNU 'troff', using
8042 the requests 'chop' to remove the final newline of a diversion, and
8043 'unformat' to make the horizontal spaces stretchable again.
8054 => This is a funny test.
8056 *Note Gtroff Internals::, for more information.
8058 -- Request: .as name [string]
8059 -- Request: .as1 name [string]
8060 The 'as' request is similar to 'ds' but appends STRING to the
8061 string stored as NAME instead of redefining it. If NAME doesn't
8062 exist yet, it is created.
8064 .as sign " with shallots, onions and garlic,
8066 The 'as1' request is similar to 'as', but compatibility mode is
8067 switched off while the appended string is interpreted. To be more
8068 precise, a "compatibility save" input token is inserted at the
8069 beginning of the appended string, and a "compatibility restore"
8070 input token at the end.
8072 Rudimentary string manipulation routines are given with the next two
8075 -- Request: .substring str n1 [n2]
8076 Replace the string named STR with the substring defined by the
8077 indices N1 and N2. The first character in the string has index 0.
8078 If N2 is omitted, it is implicitly set to the largest valid value
8079 (the string length minus one). If the index value N1 or N2 is
8080 negative, it is counted from the end of the string, going
8081 backwards: The last character has index -1, the character before
8082 the last character has index -2, etc.
8092 -- Request: .length reg str
8093 Compute the number of characters of STR and return it in the number
8094 register REG. If REG doesn't exist, it is created. 'str' is read
8097 .ds xxx abcd\h'3i'efgh
8102 -- Request: .rn xx yy
8103 Rename the request, macro, diversion, or string XX to YY.
8106 Remove the request, macro, diversion, or string XX. 'gtroff'
8107 treats subsequent invocations as if the object had never been
8110 -- Request: .als new old
8111 Create an alias named NEW for the request, string, macro, or
8112 diversion object named OLD. The new name and the old name are
8113 exactly equivalent (it is similar to a hard rather than a soft
8114 link). If OLD is undefined, 'gtroff' generates a warning of type
8115 'mac' and ignores the request.
8117 To understand how the 'als' request works it is probably best to
8118 think of two different pools: one pool for objects (macros,
8119 strings, etc.), and another one for names. As soon as an object is
8120 defined, 'gtroff' adds it to the object pool, adds its name to the
8121 name pool, and creates a link between them. When 'als' creates an
8122 alias, it adds a new name to the name pool that gets linked to the
8123 same object as the old name.
8125 Now consider this example.
8137 => input stack limit exceeded
8139 The definition of macro 'bar' replaces the old object this name is
8140 linked to. However, the alias to 'foo' is still active! In other
8141 words, 'foo' is still linked to the same object as 'bar', and the
8142 result of calling 'bar' is an infinite, recursive loop that finally
8145 To undo an alias, simply call 'rm' on the aliased name. The object
8146 itself is not destroyed until there are no more aliases.
8148 -- Request: .chop xx
8149 Remove (chop) the last character from the macro, string, or
8150 diversion named XX. This is useful for removing the newline from
8151 the end of diversions that are to be interpolated as strings. This
8152 command can be used repeatedly; see *note Gtroff Internals::, for
8153 details on nodes inserted additionally by 'gtroff'.
8155 *Note Identifiers::, and *note Comments::.
8158 File: groff.info, Node: Conditionals and Loops, Next: Writing Macros, Prev: Strings, Up: gtroff Reference
8160 5.20 Conditionals and Loops
8161 ===========================
8165 * Operators in Conditionals::
8170 File: groff.info, Node: Operators in Conditionals, Next: if-else, Prev: Conditionals and Loops, Up: Conditionals and Loops
8172 5.20.1 Operators in Conditionals
8173 --------------------------------
8175 In 'if', 'ie', and 'while' requests, in addition to ordinary *note
8176 Expressions::, there are several more operators available:
8180 True if the current page is even or odd numbered (respectively).
8183 True if the document is being processed in nroff mode (i.e., the
8184 '.nroff' command has been issued). *Note Troff and Nroff Mode::.
8187 True if the document is being processed in troff mode (i.e., the
8188 '.troff' command has been issued). *Note Troff and Nroff Mode::.
8191 Always false. This condition is for compatibility with other
8192 'troff' versions only (identifying a '-Tversatec' device).
8195 True if the output produced by XXX is equal to the output produced
8196 by YYY. Other characters can be used in place of the single
8197 quotes; the same set of delimiters as for the '\D' escape is used
8198 (*note Escapes::). 'gtroff' formats XXX and YYY in separate
8199 environments; after the comparison the resulting data is discarded.
8207 The resulting motions, glyph sizes, and fonts have to match,(1)
8208 (*note Operators in Conditionals-Footnote-1::) and not the
8209 individual motion, size, and font requests. In the previous
8210 example, '|' and '\fR|\fP' both result in a roman '|' glyph with
8211 the same point size and at the same location on the page, so the
8212 strings are equal. If '.ft I' had been added before the '.ie', the
8213 result would be "false" because (the first) '|' produces an italic
8214 '|' rather than a roman one.
8216 To compare strings without processing, surround the data with '\?'.
8218 .ie "\?|\?"\?\fR|\fP\?" \
8224 Since data protected with '\?' is read in copy-in mode it is even
8225 possible to use incomplete input without causing an error.
8229 .ie '\?\*a\?'\?\*b\?' \
8236 True if there is a number register named XXX.
8239 True if there is a string, macro, diversion, or request named XXX.
8242 True if there is a color named XXX.
8245 True if there is a glyph G available(2) (*note Operators in
8246 Conditionals-Footnote-2::); G is either an ASCII character or a
8247 special character ('\N'XXX'', '\(GG' or '\[GGG]'); the condition is
8248 also true if G has been defined by the 'char' request.
8251 True if a font named FONT exists. FONT is handled as if it was
8252 opened with the 'ft' request (this is, font translation and styles
8253 are applied), without actually mounting it.
8255 This test doesn't load the complete font but only its header to
8256 verify its validity.
8259 True if style STYLE has been registered. Font translation is
8262 Note that these operators can't be combined with other operators like
8263 ':' or '&'; only a leading '!' (without whitespace between the
8264 exclamation mark and the operator) can be used to negate the result.
8273 A whitespace after '!' always evaluates to zero (this bizarre
8274 behaviour is due to compatibility with UNIX 'troff').
8283 It is possible to omit the whitespace before the argument to the 'r',
8284 'd', and 'c' operators.
8286 *Note Expressions::.
8289 File: groff.info, Node: Operators in Conditionals-Footnotes, Up: Operators in Conditionals
8291 (1) The created output nodes must be identical. *Note Gtroff
8294 (2) The name of this conditional operator is a misnomer since it
8295 tests names of output glyphs.
8298 File: groff.info, Node: if-else, Next: while, Prev: Operators in Conditionals, Up: Conditionals and Loops
8303 'gtroff' has if-then-else constructs like other languages, although the
8304 formatting can be painful.
8306 -- Request: .if expr anything
8308 Evaluate the expression EXPR, and executes ANYTHING (the remainder
8309 of the line) if EXPR evaluates to a value greater than zero (true).
8310 ANYTHING is interpreted as though it was on a line by itself
8311 (except that leading spaces are swallowed). *Note Operators in
8312 Conditionals::, for more info.
8316 .if ((\n[xxx] == 1) & (\n[yyy] == 2)) true
8319 -- Request: .nop anything
8320 Executes ANYTHING. This is similar to '.if 1'.
8322 -- Request: .ie expr anything
8323 -- Request: .el anything
8324 Use the 'ie' and 'el' requests to write an if-then-else. The first
8325 request is the 'if' part and the latter is the 'else' part.
8327 .ie n .ls 2 \" double-spacing in nroff
8328 .el .ls 1 \" single-spacing in troff
8332 In many cases, an if (or if-else) construct needs to execute more
8333 than one request. This can be done using the escapes '\{' (which
8334 must start the first line) and '\}' (which must end the last line).
8345 *Note Expressions::.
8348 File: groff.info, Node: while, Prev: if-else, Up: Conditionals and Loops
8353 'gtroff' provides a looping construct using the 'while' request, which
8354 is used much like the 'if' (and related) requests.
8356 -- Request: .while expr anything
8357 Evaluate the expression EXPR, and repeatedly execute ANYTHING (the
8358 remainder of the line) until EXPR evaluates to 0.
8361 .while (\na < 9) \{\
8365 => 1, 2, 3, 4, 5, 6, 7, 8, 9, 10
8369 * The body of a 'while' request is treated like the body of a
8370 'de' request: 'gtroff' temporarily stores it in a macro that
8371 is deleted after the loop has been exited. It can
8372 considerably slow down a macro if the body of the 'while'
8373 request (within the macro) is large. Each time the macro is
8374 executed, the 'while' body is parsed and stored again as a
8379 . while (\\n[num] > 0) \{\
8380 . \" many lines of code
8385 The traditional and ofter better solution (UNIX 'troff'
8386 doesn't have the 'while' request) is to use a recursive macro
8387 instead that is parsed only once during its definition.
8390 . if (\\n[num] > 0) \{\
8391 . \" many lines of code
8402 Note that the number of available recursion levels is set
8403 to 1000 (this is a compile-time constant value of 'gtroff').
8405 * The closing brace of a 'while' body must end a line.
8409 . while (\n[a] < 10) \{\
8415 Break out of a 'while' loop. Be sure not to confuse this with the
8416 'br' request (causing a line break).
8418 -- Request: .continue
8419 Finish the current iteration of a 'while' loop, immediately
8420 restarting the next iteration.
8422 *Note Expressions::.
8425 File: groff.info, Node: Writing Macros, Next: Page Motions, Prev: Conditionals and Loops, Up: gtroff Reference
8430 A "macro" is a collection of text and embedded commands that can be
8431 invoked multiple times. Use macros to define common operations. *Note
8432 Strings::, for a (limited) alternative syntax to call macros.
8434 Although the following requests can be used to create macros, simply
8435 using an undefined macro will cause it to be defined as empty. *Note
8438 -- Request: .de name [end]
8439 -- Request: .de1 name [end]
8440 -- Request: .dei name [end]
8441 -- Request: .dei1 name [end]
8442 Define a new macro named NAME. 'gtroff' copies subsequent lines
8443 (starting with the next one) into an internal buffer until it
8444 encounters the line '..' (two dots). If the optional second
8445 argument to 'de' is present it is used as the macro closure request
8448 There can be whitespace after the first dot in the line containing
8449 the ending token (either '.' or macro 'END'). Don't insert a tab
8450 character immediately after the '..', otherwise it isn't recognized
8451 as the end-of-macro symbol.(1) (*note Writing Macros-Footnote-1::)
8453 Here a small example macro called 'P' that causes a break and
8454 inserts some vertical space. It could be used to separate
8462 The following example defines a macro within another. Remember
8463 that expansion must be protected twice; once for reading the macro
8464 and once for executing.
8466 \# a dummy macro to avoid a warning
8472 . nop \f[B]Hallo \\\\$1!\f[]
8480 Since '\f' has no expansion, it isn't necessary to protect its
8481 backslash. Had we defined another macro within 'bar' that takes a
8482 parameter, eight backslashes would be necessary before '$1'.
8484 The 'de1' request turns off compatibility mode while executing the
8485 macro. On entry, the current compatibility mode is saved and
8491 The value of xxx is \\n[xxx].
8494 The value of xxx ix \\n[xxx].
8500 => warning: number register `[' not defined
8501 => The value of xxx is 0xxx].
8503 => The value of xxx ix 12345.
8505 The 'dei' request defines a macro indirectly. That is, it expands
8506 strings whose names are NAME or END before performing the append.
8518 The 'dei1' request is similar to 'dei' but with compatibility mode
8519 switched off during execution of the defined macro.
8521 If compatibility mode is on, 'de' (and 'dei') behave similar to
8522 'de1' (and 'dei1'): A 'compatibility save' token is inserted at the
8523 beginning, and a 'compatibility restore' token at the end, with
8524 compatibility mode switched on during execution. *Note Gtroff
8525 Internals::, for more information on switching compatibility mode
8526 on and off in a single document.
8528 Using 'trace.tmac', you can trace calls to 'de' and 'de1'.
8530 Note that macro identifiers are shared with identifiers for strings
8533 *Note the description of the 'als' request: als, for possible
8534 pitfalls if redefining a macro that has been aliased.
8536 -- Request: .am name [end]
8537 -- Request: .am1 name [end]
8538 -- Request: .ami name [end]
8539 -- Request: .ami1 name [end]
8540 Works similarly to 'de' except it appends onto the macro named
8541 NAME. So, to make the previously defined 'P' macro actually do
8542 indented instead of block paragraphs, add the necessary code to the
8543 existing macro like this:
8549 The 'am1' request turns off compatibility mode while executing the
8550 appended macro piece. To be more precise, a "compatibility save"
8551 input token is inserted at the beginning of the appended code, and
8552 a "compatibility restore" input token at the end.
8554 The 'ami' request appends indirectly, meaning that 'gtroff' expands
8555 strings whose names are NAME or END before performing the append.
8557 The 'ami1' request is similar to 'ami' but compatibility mode is
8558 switched off during execution of the defined macro.
8560 Using 'trace.tmac', you can trace calls to 'am' and 'am1'.
8562 *Note Strings::, for the 'als' and 'rn' request to create an alias
8563 and rename a macro, respectively.
8565 The 'de', 'am', 'di', 'da', 'ds', and 'as' requests (together with
8566 its variants) only create a new object if the name of the macro,
8567 diversion or string diversion is currently undefined or if it is defined
8568 to be a request; normally they modify the value of an existing object.
8570 -- Request: .return [anything]
8571 Exit a macro, immediately returning to the caller.
8573 If called with an argument, exit twice, namely the current macro
8574 and the macro one level higher. This is used to define a wrapper
8575 macro for 'return' in 'trace.tmac'.
8583 File: groff.info, Node: Writing Macros-Footnotes, Up: Writing Macros
8585 (1) While it is possible to define and call a macro '.' with
8591 .. \" This calls macro `.'!
8593 you can't use this as the end-of-macro macro: during a macro definition,
8594 '..' is never handled as a call to '.', even if you say '.de foo .'