1 This is groff, produced by makeinfo version 4.2 from ./groff.texinfo.
3 This manual documents GNU `troff' version 1.18.
5 Copyright (C) 1994-2000, 2001, 2002 Free Software Foundation, Inc.
7 Permission is granted to copy, distribute and/or modify this
8 document under the terms of the GNU Free Documentation License,
9 Version 1.1 or any later version published by the Free Software
10 Foundation; with no Invariant Sections, with the Front-Cover texts
11 being `A GNU Manual," and with the Back-Cover Texts as in (a)
12 below. A copy of the license is included in the section entitled
13 `GNU Free Documentation License."
15 (a) The FSF's Back-Cover Text is: `You have freedom to copy and
16 modify this GNU Manual, like GNU software. Copies published by
17 the Free Software Foundation raise funds for GNU development."
19 INFO-DIR-SECTION Miscellaneous
21 * Groff: (groff). The GNU troff document formatting system.
25 File: groff, Node: Top, Next: Introduction, Prev: (dir), Up: (dir)
30 This manual documents GNU `troff' version 1.18.
32 Copyright (C) 1994-2000, 2001, 2002 Free Software Foundation, Inc.
34 Permission is granted to copy, distribute and/or modify this
35 document under the terms of the GNU Free Documentation License,
36 Version 1.1 or any later version published by the Free Software
37 Foundation; with no Invariant Sections, with the Front-Cover texts
38 being `A GNU Manual," and with the Back-Cover Texts as in (a)
39 below. A copy of the license is included in the section entitled
40 `GNU Free Documentation License."
42 (a) The FSF's Back-Cover Text is: `You have freedom to copy and
43 modify this GNU Manual, like GNU software. Copies published by
44 the Free Software Foundation raise funds for GNU development."
50 * Tutorial for Macro Users::
57 * Copying This Manual::
65 * Font File Keyword Index::
66 * Program and File Index::
70 File: groff, Node: Introduction, Next: Invoking groff, Prev: Top, Up: Top
75 GNU `troff' (or `groff') is a system for typesetting documents.
76 `troff' is very flexible and has been in existence (and use) for about
77 3 decades. It is quite widespread and firmly entrenched in the UNIX
84 * groff Capabilities::
85 * Macro Package Intro::
86 * Preprocessor Intro::
87 * Output device intro::
91 File: groff, Node: What Is groff?, Next: History, Prev: Introduction, Up: Introduction
96 `groff' belongs to an older generation of document preparation
97 systems, which operate more like compilers than the more recent
98 interactive WYSIWYG(1) (*note What Is groff?-Footnote-1::) systems.
99 `groff' and its contemporary counterpart, TeX, both work using a
100 "batch" paradigm: The input (or "source") files are normal text files
101 with embedded formatting commands. These files can then be processed
102 by `groff' to produce a typeset document on a variety of devices.
104 Likewise, `groff' should not be confused with a "word processor",
105 since that term connotes an integrated system that includes an editor
106 and a text formatter. Also, many word processors follow the WYSIWYG
107 paradigm discussed earlier.
109 Although WYSIWYG systems may be easier to use, they have a number of
110 disadvantages compared to `troff':
112 * They must be used on a graphics display to work on a document.
114 * Most of the WYSIWYG systems are either non-free or are not very
117 * `troff' is firmly entrenched in all UNIX systems.
119 * It is difficult to have a wide range of capabilities available
120 within the confines of a GUI/window system.
122 * It is more difficult to make global changes to a document.
124 "GUIs normally make it simple to accomplish simple actions and
125 impossible to accomplish complex actions." -Doug Gwyn (22/Jun/91
126 in `comp.unix.wizards')
129 File: groff, Node: What Is groff?-Footnotes, Up: What Is groff?
131 (1) What You See Is What You Get
134 File: groff, Node: History, Next: groff Capabilities, Prev: What Is groff?, Up: Introduction
139 `troff' can trace its origins back to a formatting program called
140 `runoff', written by J. E. Saltzer, which ran on MIT's CTSS operating
141 system in the mid-sixties. This name came from the common phrase of
142 the time "I'll run off a document." Bob Morris ported it to the 635
143 architecture and called the program `roff' (an abbreviation of
144 `runoff'). It was rewritten as `rf' for the PDP-7 (before having
145 UNIX), and at the same time (1969), Doug McIllroy rewrote an extended
146 and simplified version of `roff' in the BCPL programming language.
148 The first version of UNIX was developed on a PDP-7 which was sitting
149 around Bell Labs. In 1971 the developers wanted to get a PDP-11 for
150 further work on the operating system. In order to justify the cost for
151 this system, they proposed that they would implement a document
152 formatting system for the AT&T patents division. This first formatting
153 program was a reimplementation of McIllroy's `roff', written by
156 When they needed a more flexible language, a new version of `roff'
157 called `nroff' ("Newer `roff'") was written. It had a much more
158 complicated syntax, but provided the basis for all future versions.
159 When they got a Graphic Systems CAT Phototypesetter, Ossanna wrote a
160 version of `nroff' that would drive it. It was dubbed `troff', for
161 "typesetter `roff'", although many people have speculated that it
162 actually means "Times `roff'" because of the use of the Times font
163 family in `troff' by default. As such, the name `troff' is pronounced
164 `t-roff' rather than `trough'.
166 With `troff' came `nroff' (they were actually the same program
167 except for some `#ifdef's), which was for producing output for line
168 printers and character terminals. It understood everything `troff'
169 did, and ignored the commands which were not applicable (e.g. font
172 Since there are several things which cannot be done easily in
173 `troff', work on several preprocessors began. These programs would
174 transform certain parts of a document into `troff', which made a very
175 natural use of pipes in UNIX.
177 The `eqn' preprocessor allowed mathematical formulae to be specified
178 in a much simpler and more intuitive manner. `tbl' is a preprocessor
179 for formatting tables. The `refer' preprocessor (and the similar
180 program, `bib') processes citations in a document according to a
181 bibliographic database.
183 Unfortunately, Ossanna's `troff' was written in PDP-11 assembly
184 language and produced output specifically for the CAT phototypesetter.
185 He rewrote it in C, although it was now 7000 lines of uncommented code
186 and still dependent on the CAT. As the CAT became less common, and was
187 no longer supported by the manufacturer, the need to make it support
188 other devices became a priority. However, before this could be done,
189 Ossanna was killed in a car accident.
191 So, Brian Kernighan took on the task of rewriting `troff'. The
192 newly rewritten version produced device independent code which was very
193 easy for postprocessors to read and translate to the appropriate
194 printer codes. Also, this new version of `troff' (called `ditroff' for
195 "device independent `troff'") had several extensions, which included
198 Due to the additional abilities of the new version of `troff',
199 several new preprocessors appeared. The `pic' preprocessor provides a
200 wide range of drawing functions. Likewise the `ideal' preprocessor did
201 the same, although via a much different paradigm. The `grap'
202 preprocessor took specifications for graphs, but, unlike other
203 preprocessors, produced `pic' code.
205 James Clark began work on a GNU implementation of `ditroff' in
206 early 1989. The first version, `groff' 0.3.1, was released June 1990.
209 * A replacement for `ditroff' with many extensions.
211 * The `soelim', `pic', `tbl', and `eqn' preprocessors.
213 * Postprocessors for character devices, POSTSCRIPT, TeX DVI, and
214 X Windows. GNU `troff' also eliminated the need for a separate
215 `nroff' program with a postprocessor which would produce ASCII
218 * A version of the `me' macros and an implementation of the `man'
221 Also, a front-end was included which could construct the, sometimes
222 painfully long, pipelines required for all the post- and preprocessors.
224 Development of GNU `troff' progressed rapidly, and saw the additions
225 of a replacement for `refer', an implementation of the `ms' and `mm'
226 macros, and a program to deduce how to format a document (`grog').
228 It was declared a stable (i.e. non-beta) package with the release of
229 version 1.04 around November 1991.
231 Beginning in 1999, `groff' has new maintainers (the package was an
232 orphan for a few years). As a result, new features and programs like
233 `grn', a preprocessor for gremlin images, and an output device to
234 produce HTML output have been added.
237 File: groff, Node: groff Capabilities, Next: Macro Package Intro, Prev: History, Up: Introduction
242 So what exactly is `groff' capable of doing? `groff' provides a
243 wide range of low-level text formatting operations. Using these, it is
244 possible to perform a wide range of formatting tasks, such as
245 footnotes, table of contents, multiple columns, etc. Here's a list of
246 the most important operations supported by `groff':
248 * text filling, adjusting, and centering
254 * font and glyph size control
256 * vertical spacing (e.g. double-spacing)
258 * line length and indenting
260 * macros, strings, diversions, and traps
264 * tabs, leaders, and fields
266 * input and output conventions and character translation
268 * overstrike, bracket, line drawing, and zero-width functions
270 * local horizontal and vertical motions and the width function
274 * output line numbering
276 * conditional acceptance of input
278 * environment switching
280 * insertions from the standard input
282 * input/output file switching
284 * output and error messages
287 File: groff, Node: Macro Package Intro, Next: Preprocessor Intro, Prev: groff Capabilities, Up: Introduction
292 Since `groff' provides such low-level facilities, it can be quite
293 difficult to use by itself. However, `groff' provides a "macro"
294 facility to specify how certain routine operations (e.g. starting
295 paragraphs, printing headers and footers, etc.) should be done. These
296 macros can be collected together into a "macro package". There are a
297 number of macro packages available; the most common (and the ones
298 described in this manual) are `man', `mdoc', `me', `ms', and `mm'.
301 File: groff, Node: Preprocessor Intro, Next: Output device intro, Prev: Macro Package Intro, Up: Introduction
306 Although `groff' provides most functions needed to format a
307 document, some operations would be unwieldy (e.g. to draw pictures).
308 Therefore, programs called "preprocessors" were written which
309 understand their own language and produce the necessary `groff'
310 operations. These preprocessors are able to differentiate their own
311 input from the rest of the document via markers.
313 To use a preprocessor, UNIX pipes are used to feed the output from
314 the preprocessor into `groff'. Any number of preprocessors may be used
315 on a given document; in this case, the preprocessors are linked
316 together into one pipeline. However, with `groff', the user does not
317 need to construct the pipe, but only tell `groff' what preprocessors to
320 `groff' currently has preprocessors for producing tables (`tbl'),
321 typesetting equations (`eqn'), drawing pictures (`pic' and `grn'), and
322 for processing bibliographies (`refer'). An associated program which
323 is useful when dealing with preprocessors is `soelim'.
325 A free implementation of `grap', a preprocessor for drawing graphs,
326 can be obtained as an extra package; `groff' can use `grap' also.
328 There are other preprocessors in existence, but, unfortunately, no
329 free implementations are available. Among them are preprocessors for
330 drawing mathematical pictures (`ideal') and chemical structures
334 File: groff, Node: Output device intro, Next: Credits, Prev: Preprocessor Intro, Up: Introduction
339 `groff' actually produces device independent code which may be fed
340 into a postprocessor to produce output for a particular device.
341 Currently, `groff' has postprocessors for POSTSCRIPT devices, character
342 terminals, X Windows (for previewing), TeX DVI format, HP LaserJet 4
343 and Canon LBP printers (which use CAPSL), and HTML.
346 File: groff, Node: Credits, Prev: Output device intro, Up: Introduction
351 Large portions of this manual were taken from existing documents,
352 most notably, the manual pages for the `groff' package by James Clark,
353 and Eric Allman's papers on the `me' macro package.
355 The section on the `man' macro package is partly based on Susan G.
356 Kleinmann's `groff_man' manual page written for the Debian GNU/Linux
359 Larry Kollar contributed the section in the `ms' macro package.
362 File: groff, Node: Invoking groff, Next: Tutorial for Macro Users, Prev: Introduction, Up: Top
367 This section focuses on how to invoke the `groff' front end. This
368 front end takes care of the details of constructing the pipeline among
369 the preprocessors, `gtroff' and the postprocessor.
371 It has become a tradition that GNU programs get the prefix `g' to
372 distinguish it from its original counterparts provided by the host (see
373 *Note Environment::, for more details). Thus, for example, `geqn' is
374 GNU `eqn'. On operating systems like GNU/Linux or the Hurd, which
375 don't contain proprietary versions of `troff', and on
376 MS-DOS/MS-Windows, where `troff' and associated programs are not
377 available at all, this prefix is omitted since GNU `troff' is the only
378 used incarnation of `troff'. Exception: `groff' is never replaced by
381 In this document, we consequently say `gtroff' when talking about
382 the GNU `troff' program. All other implementations of `troff' are
383 called AT&T `troff' which is the common origin of all `troff' derivates
384 (with more or less compatible changes). Similarly, we say `gpic',
391 * Macro Directories::
393 * Invocation Examples::
396 File: groff, Node: Groff Options, Next: Environment, Prev: Invoking groff, Up: Invoking groff
401 `groff' normally runs the `gtroff' program and a postprocessor
402 appropriate for the selected device. The default device is `ps' (but
403 it can be changed when `groff' is configured and built). It can
404 optionally preprocess with any of `gpic', `geqn', `gtbl', `ggrn',
405 `grap', `grefer', or `gsoelim'.
407 This section only documents options to the `groff' front end. Many
408 of the arguments to `groff' are passed on to `gtroff', therefore those
409 are also included. Arguments to pre- or postprocessors can be found in
410 *Note Invoking gpic::, *Note Invoking geqn::, *Note Invoking gtbl::,
411 *Note Invoking ggrn::, *Note Invoking grefer::, *Note Invoking
412 gsoelim::, *Note Invoking grotty::, *Note Invoking grops::, *Note
413 Invoking grohtml::, *Note Invoking grodvi::, *Note Invoking grolj4::,
414 *Note Invoking grolbp::, and *Note Invoking gxditview::.
416 The command line format for `groff' is:
419 groff [ -abceghilpstvzCEGNRSUVXZ ] [ -FDIR ] [ -mNAME ]
420 [ -TDEF ] [ -fFAM ] [ -wNAME ] [ -WNAME ]
421 [ -MDIR ] [ -dCS ] [ -rCN ] [ -nNUM ]
422 [ -oLIST ] [ -PARG ] [ -LARG ] [ -IDIR ]
425 The command line format for `gtroff' is as follows.
428 gtroff [ -abcivzCERU ] [ -wNAME ] [ -WNAME ] [ -dCS ]
429 [ -fFAM ] [ -mNAME ] [ -nNUM ]
430 [ -oLIST ] [ -rCN ] [ -TNAME ]
431 [ -FDIR ] [ -MDIR ] [ FILES... ]
433 Obviously, many of the options to `groff' are actually passed on to
436 Options without an argument can be grouped behind a single `-'. A
437 filename of `-' denotes the standard input. It is possible to have
438 whitespace between an option and its parameter.
440 The `grog' command can be used to guess the correct `groff' command
443 Here's the description of the command-line options:
446 Print a help message.
449 Preprocess with `geqn'.
452 Preprocess with `gtbl'.
455 Preprocess with `ggrn'.
458 Preprocess with `grap'.
461 Preprocess with `gpic'.
464 Preprocess with `gsoelim'.
467 Suppress color output.
470 Preprocess with `grefer'. No mechanism is provided for passing
471 arguments to `grefer' because most `grefer' options have
472 equivalent commands which can be included in the file. *Note
473 grefer::, for more details.
475 Note that `gtroff' also accepts a `-R' option, which is not
476 accessible via `groff'. This option prevents the loading of the
477 `troffrc' and `troffrc-end' files.
480 Make programs run by `groff' print out their version number.
483 Print the pipeline on `stdout' instead of executing it.
486 Suppress output from `gtroff'. Only error messages are printed.
489 Do not postprocess the output of `gtroff'. Normally `groff'
490 automatically runs the appropriate postprocessor.
493 Pass ARG to the postprocessor. Each argument should be passed
494 with a separate `-P' option. Note that `groff' does not prepend
495 `-' to ARG before passing it to the postprocessor.
498 Send the output to a spooler for printing. The command used for
499 this is specified by the `print' command in the device description
500 file (see *Note Font Files::, for more info). If not present,
504 Pass ARG to the spooler. Each argument should be passed with a
505 separate `-L' option. Note that `groff' does not prepend a `-' to
506 ARG before passing it to the postprocessor. If the `print'
507 keyword in the device description file is missing, `-L' is ignored.
510 Prepare output for device DEV. The default device is `ps', unless
511 changed when `groff' was configured and built. The following are
512 the output devices currently available:
515 For POSTSCRIPT printers and previewers.
521 For a 75dpi X11 previewer.
524 For a 75dpi X11 previewer with a 12pt base font in the
528 For a 100dpi X11 previewer.
531 For a 100dpi X11 previewer with a 12pt base font in the
535 For typewriter-like devices using the (7-bit) ASCII character
539 For typewriter-like devices that support the Latin-1
540 (ISO 8859-1) character set.
543 For typewriter-like devices which use the Unicode (ISO 10646)
544 character set with UTF-8 encoding.
547 For typewriter-like devices which use the EBCDIC encoding IBM
551 For HP LaserJet4-compatible (or other PCL5-compatible)
555 For Canon CAPSL printers (LBP-4 and LBP-8 series laser
559 To produce HTML output. Note that the HTML driver consists
560 of two parts, a preprocessor (`pre-grohtml') and a
561 postprocessor (`post-grohtml').
563 The predefined `gtroff' string register `.T' contains the current
564 output device; the read-only number register `.T' is set to 1 if
565 this option is used (which is always true if `groff' is used to
566 call `gtroff'). *Note Built-in Registers::.
568 The postprocessor to be used for a device is specified by the
569 `postpro' command in the device description file. (*Note Font
570 Files::, for more info.) This can be overridden with the `-X'
574 Preview with `gxditview' instead of using the usual postprocessor.
575 This is unlikely to produce good results except with `-Tps'.
577 Note that this is not the same as using `-TX75' or `-TX100' to
578 view a document with `gxditview': The former uses the metrics of
579 the specified device, whereas the latter uses X-specific fonts and
583 Don't allow newlines with `eqn' delimiters. This is the same as
584 the `-N' option in `geqn'.
587 Safer mode. Pass the `-S' option to `gpic' and disable the
588 `open', `opena', `pso', `sy', and `pi' requests. For security
589 reasons, this is enabled by default.
592 Unsafe mode. This enables the `open', `opena', `pso', `sy', and
596 Generate an ASCII approximation of the typeset output. The
597 read-only register `.A' is then set to 1. *Note Built-in
598 Registers::. A typical example is
601 groff -a -man -Tdvi troff.man | less
603 which shows how lines are broken for the DVI device. Note that
604 this option is rather useless today since graphic output devices
605 are available virtually everywhere.
608 Print a backtrace with each warning or error message. This
609 backtrace should help track down the cause of the error. The line
610 numbers given in the backtrace may not always be correct: `gtroff'
611 can get confused by `as' or `am' requests while counting line
615 Read the standard input after all the named input files have been
619 Enable warning NAME. Available warnings are described in *Note
620 Debugging::. Multiple `-w' options are allowed.
623 Inhibit warning NAME. Multiple `-W' options are allowed.
626 Inhibit all error messages.
629 Enable compatibility mode. *Note Implementation Differences::,
630 for the list of incompatibilities between `groff' and AT&T `troff'.
634 Define C or NAME to be a string S. C must be a one-letter name;
635 NAME can be of arbitrary length. All string assignments happen
636 before loading any macro file (including the start-up file).
639 Use FAM as the default font family. *Note Font Families::.
642 Read in the file `NAME.tmac'. Normally `groff' searches for this
643 in its macro directories. If it isn't found, it tries `tmac.NAME'
644 (searching in the same directories).
647 Number the first page NUM.
650 Output only pages in LIST, which is a comma-separated list of page
651 ranges; `N' means print page N, `M-N' means print every page
652 between M and N, `-N' means print every page up to N, `N-' means
653 print every page beginning with N. `gtroff' exits after printing
654 the last page in the list. All the ranges are inclusive on both
657 Within `gtroff', this information can be extracted with the `.P'
658 register. *Note Built-in Registers::.
660 If your document restarts page numbering at the beginning of each
661 chapter, then `gtroff' prints the specified page range for each
666 Set number register C or NAME to the value N. C must be a
667 one-letter name; NAME can be of arbitrary length. N can be any
668 `gtroff' numeric expression. All register assignments happen
669 before loading any macro file (including the start-up file).
672 Search `DIR' for subdirectories `devNAME' (NAME is the name of the
673 device), for the `DESC' file, and for font files before looking in
674 the standard directories (*note Font Directories::). This option
675 is passed to all pre- and postprocessors using the
676 `GROFF_FONT_PATH' environment variable.
679 Search directory `DIR' for macro files before the standard
680 directories (*note Macro Directories::).
683 This option is as described in *Note gsoelim::. It implies the
687 File: groff, Node: Environment, Next: Macro Directories, Prev: Groff Options, Up: Invoking groff
692 There are also several environment variables (of the operating
693 system, not within `gtroff') which can modify the behavior of `groff'.
695 `GROFF_COMMAND_PREFIX'
696 If this is set to X, then `groff' runs `Xtroff' instead of
697 `gtroff'. This also applies to `tbl', `pic', `eqn', `grn',
698 `refer', and `soelim'. It does not apply to `grops', `grodvi',
699 `grotty', `pre-grohtml', `post-grohtml', `grolj4', and `gxditview'.
701 The default command prefix is determined during the installation
702 process. If a non-GNU troff system is found, prefix `g' is used,
706 A colon-separated list of directories in which to search for macro
707 files (before the default directories are tried). *Note Macro
711 The default output device.
714 A colon-separated list of directories in which to search for the
715 `dev'NAME directory (before the default directories are tried).
716 *Note Font Directories::.
719 This search path, followed by `PATH', is used for commands executed
723 The directory in which `groff' creates temporary files. If this is
724 not set and `TMPDIR' is set, temporary files are created in that
725 directory. Otherwise temporary files are created in a
726 system-dependent default directory (on Unix and GNU/Linux systems,
727 this is usually `/tmp'). `grops', `grefer', `pre-grohtml', and
728 `post-grohtml' can create temporary files in this directory.
730 Note that MS-DOS and MS-Windows ports of `groff' use semi-colons,
731 rather than colons, to separate the directories in the lists described
735 File: groff, Node: Macro Directories, Next: Font Directories, Prev: Environment, Up: Invoking groff
740 All macro file names must be named `NAME.tmac' or `tmac.NAME' to
741 make the `-mNAME' command line option work. The `mso' request doesn't
742 have this restriction; any file name can be used, and `gtroff' won't
743 try to append or prepend the `tmac' string.
745 Macro files are kept in the "tmac directories", all of which
746 constitute the "tmac path". The elements of the search path for macro
747 files are (in that order):
749 * The directories specified with `gtroff''s or `groff''s `-M'
752 * The directories given in the `GROFF_TMAC_PATH' environment
755 * The current directory (only if in unsafe mode using the `-U'
756 command line switch).
758 * The home directory.
760 * A platform-dependent directory, a site-specific
761 (platform-independent) directory, and the main tmac directory; the
762 default locations are
765 /usr/local/lib/groff/site-tmac
766 /usr/local/share/groff/site-tmac
767 /usr/local/share/groff/1.18/tmac
769 assuming that the version of `groff' is 1.18, and the installation
770 prefix was `/usr/local'. It is possible to fine-tune those
771 directories during the installation process.
774 File: groff, Node: Font Directories, Next: Invocation Examples, Prev: Macro Directories, Up: Invoking groff
779 Basically, there is no restriction how font files for `groff' are
780 named and how long font names are; however, to make the font family
781 mechanism work (*note Font Families::), fonts within a family should
782 start with the family name, followed by the shape. For example, the
783 Times family uses `T' for the family name and `R', `B', `I', and `BI'
784 to indicate the shapes `roman', `bold', `italic', and `bold italic',
785 respectively. Thus the final font names are `TR', `TB', `TI', and
788 All font files are kept in the "font directories" which constitute
789 the "font path". The file search functions will always append the
790 directory `dev'NAME, where NAME is the name of the output device.
791 Assuming, say, DVI output, and `/foo/bar' as a font directory, the font
792 files for `grodvi' must be in `/foo/bar/devdvi'.
794 The elements of the search path for font files are (in that order):
796 * The directories specified with `gtroff''s or `groff''s `-F'
797 command line option. All device drivers and some preprocessors
798 also have this option.
800 * The directories given in the `GROFF_FONT_PATH' environment
803 * A site-specific directory and the main font directory; the default
807 /usr/local/share/groff/site-font
808 /usr/local/share/groff/1.18/font
810 assuming that the version of `groff' is 1.18, and the installation
811 prefix was `/usr/local'. It is possible to fine-tune those
812 directories during the installation process.
815 File: groff, Node: Invocation Examples, Prev: Font Directories, Up: Invoking groff
820 This section lists several common uses of `groff' and the
821 corresponding command lines.
826 This command processes `file' without a macro package or a
827 preprocessor. The output device is the default, `ps', and the output
831 groff -t -mandoc -Tascii file | less
833 This is basically what a call to the `man' program does. `gtroff'
834 processes the manual page `file' with the `mandoc' macro file (which in
835 turn either calls the `man' or the `mdoc' macro package), using the
836 `tbl' preprocessor and the ASCII output device. Finally, the `less'
837 pager displays the result.
842 Preview `file' with `gxditview', using the `me' macro package. Since
843 no `-T' option is specified, use the default device (`ps'). Note that
844 you can either say `-m me' or `-me'; the latter is an anachronism from
845 the early days of UNIX.(1) (*note Invocation Examples-Footnote-1::)
848 groff -man -rD1 -z file
850 Check `file' with the `man' macro package, forcing double-sided
851 printing - don't produce any output.
858 File: groff, Node: Invocation Examples-Footnotes, Up: Invocation Examples
860 (1) The same is true for the other main macro packages that come
861 with `groff': `man', `mdoc', `ms', `mm', and `mandoc'. This won't work
862 in general; for example, to load `trace.tmac', either `-mtrace' or
863 `-m trace' must be used.
866 File: groff, Node: grog, Prev: Invocation Examples, Up: Invocation Examples
871 `grog' reads files, guesses which of the `groff' preprocessors
872 and/or macro packages are required for formatting them, and prints the
873 `groff' command including those options on the standard output. It
874 generates one or more of the options `-e', `-man', `-me', `-mm',
875 `-mom', `-ms', `-mdoc', `-mdoc-old', `-p', `-R', `-g', `-G', `-s', and
878 A special file name `-' refers to the standard input. Specifying no
879 files also means to read the standard input. Any specified options are
880 included in the printed command. No space is allowed between options
881 and their arguments. The only options recognized are `-C' (which is
882 also passed on) to enable compatibility mode, and `-v' to print the
883 version number and exit.
890 guesses the appropriate command to print `paper.ms' and then prints it
891 to the command line after adding the `-Tdvi' option. For direct
892 execution, enclose the call to `grog' in backquotes at the UNIX shell
896 `grog -Tdvi paper.ms` > paper.dvi
898 As seen in the example, it is still necessary to redirect the output to
899 something meaningful (i.e. either a file or a pager program like
903 File: groff, Node: Tutorial for Macro Users, Next: Macro Packages, Prev: Invoking groff, Up: Top
905 Tutorial for Macro Users
906 ************************
908 Most users tend to use a macro package to format their papers. This
909 means that the whole breadth of `groff' is not necessary for most
910 people. This chapter covers the material needed to efficiently use a
919 File: groff, Node: Basics, Next: Common Features, Prev: Tutorial for Macro Users, Up: Tutorial for Macro Users
924 This section covers some of the basic concepts necessary to
925 understand how to use a macro package.(1) (*note Basics-Footnote-1::)
926 References are made throughout to more detailed information, if desired.
928 `gtroff' reads an input file prepared by the user and outputs a
929 formatted document suitable for publication or framing. The input
930 consists of text, or words to be printed, and embedded commands
931 ("requests" and "escapes"), which tell `gtroff' how to format the
932 output. For more detail on this, see *Note Embedded Commands::.
934 The word "argument" is used in this chapter to mean a word or number
935 which appears on the same line as a request, and which modifies the
936 meaning of that request. For example, the request
946 spaces four lines. The number 4 is an argument to the `sp' request
947 which says to space four lines instead of one. Arguments are separated
948 from the request and from each other by spaces (_no_ tabs). More
949 details on this can be found in *Note Request Arguments::.
951 The primary function of `gtroff' is to collect words from input
952 lines, fill output lines with those words, justify the right-hand margin
953 by inserting extra spaces in the line, and output the result. For
964 is read, packed onto output lines, and justified to produce:
966 Now is the time for all good men to come to the aid of their party.
967 Four score and seven years ago, etc.
969 Sometimes a new output line should be started even though the current
970 line is not yet full; for example, at the end of a paragraph. To do
971 this it is possible to cause a "break", which starts a new output line.
972 Some requests cause a break automatically, as normally do blank input
973 lines and input lines beginning with a space.
975 Not all input lines are text to be formatted. Some input lines are
976 requests which describe how to format the text. Requests always have a
977 period (`.') or an apostrophe (`'') as the first character of the input
980 The text formatter also does more complex things, such as
981 automatically numbering pages, skipping over page boundaries, putting
982 footnotes in the correct place, and so forth.
984 Here are a few hints for preparing text for input to `gtroff'.
986 * First, keep the input lines short. Short input lines are easier to
987 edit, and `gtroff' packs words onto longer lines anyhow.
989 * In keeping with this, it is helpful to begin a new line after every
990 comma or phrase, since common corrections are to add or delete
991 sentences or phrases.
993 * End each sentence with two spaces - or better, start each sentence
994 on a new line. `gtroff' recognizes characters that usually end a
995 sentence, and inserts sentence space accordingly.
997 * Do not hyphenate words at the end of lines - `gtroff' is smart
998 enough to hyphenate words as needed, but is not smart enough to
999 take hyphens out and join a word back together. Also, words such
1000 as "mother-in-law" should not be broken over a line, since then a
1001 space can occur where not wanted, such as "mother- in-law".
1003 `gtroff' double-spaces output text automatically if you use the
1004 request `.ls 2'. Reactivate single-spaced mode by typing `.ls 1'.(2)
1005 (*note Basics-Footnote-2::)
1007 A number of requests allow to change the way the output looks,
1008 sometimes called the "layout" of the output page. Most of these
1009 requests adjust the placing of "whitespace" (blank lines or spaces).
1011 The `bp' request starts a new page, causing a line break.
1013 The request `.sp N' leaves N lines of blank space. N can be omitted
1014 (meaning skip a single line) or can be of the form Ni (for N inches) or
1015 Nc (for N centimeters). For example, the input:
1019 My thoughts on the subject
1022 leaves one and a half inches of space, followed by the line "My
1023 thoughts on the subject", followed by a single blank line (more
1024 measurement units are available, see *Note Measurements::).
1026 Text lines can be centered by using the `ce' request. The line
1027 after `ce' is centered (horizontally) on the page. To center more than
1028 one line, use `.ce N' (where N is the number of lines to center),
1029 followed by the N lines. To center many lines without counting them,
1037 The `.ce 0' request tells `groff' to center zero more lines, in other
1038 words, stop centering.
1040 All of these requests cause a break; that is, they always start a new
1041 line. To start a new line without performing any other action, use
1045 File: groff, Node: Basics-Footnotes, Up: Basics
1047 (1) This section is derived from `Writing Papers with nroff using
1048 -me' by Eric P. Allman.
1050 (2) If you need finer granularity of the vertical space, use the
1051 `pvs' request (*note Changing Type Sizes::).
1054 File: groff, Node: Common Features, Prev: Basics, Up: Tutorial for Macro Users
1059 `gtroff' provides very low-level operations for formatting a
1060 document. There are many common routine operations which are done in
1061 all documents. These common operations are written into "macros" and
1062 collected into a "macro package".
1064 All macro packages provide certain common capabilities which fall
1065 into the following categories.
1070 * Sections and Chapters::
1071 * Headers and Footers::
1072 * Page Layout Adjustment::
1074 * Footnotes and Annotations::
1075 * Table of Contents::
1078 * Multiple Columns::
1079 * Font and Size Changes::
1080 * Predefined Strings::
1081 * Preprocessor Support::
1082 * Configuration and Customization::
1085 File: groff, Node: Paragraphs, Next: Sections and Chapters, Prev: Common Features, Up: Common Features
1090 One of the most common and most used capability is starting a
1091 paragraph. There are a number of different types of paragraphs, any of
1092 which can be initiated with macros supplied by the macro package.
1093 Normally, paragraphs start with a blank line and the first line
1094 indented, like the text in this manual. There are also block style
1095 paragraphs, which omit the indentation:
1098 Some men look at constitutions with sanctimonious
1099 reverence, and deem them like the ark of the covenant, too
1100 sacred to be touched.
1102 And there are also indented paragraphs which begin with a tag or label
1103 at the margin and the remaining text indented.
1106 one This is the first paragraph. Notice how the first
1107 line of the resulting paragraph lines up with the
1108 other lines in the paragraph.
1112 This paragraph had a long label. The first
1113 character of text on the first line does not line up
1114 with the text on second and subsequent lines,
1115 although they line up with each other.
1117 A variation of this is a bulleted list.
1120 . Bulleted lists start with a bullet. It is possible
1121 to use other glyphs instead of the bullet. In nroff
1122 mode using the ASCII character set for output, a dot
1123 is used instead of a real bullet.
1126 File: groff, Node: Sections and Chapters, Next: Headers and Footers, Prev: Paragraphs, Up: Common Features
1128 Sections and Chapters
1129 ---------------------
1131 Most macro packages supply some form of section headers. The
1132 simplest kind is simply the heading on a line by itself in bold type.
1133 Others supply automatically numbered section heading or different
1134 heading styles at different levels. Some, more sophisticated, macro
1135 packages supply macros for starting chapters and appendices.
1138 File: groff, Node: Headers and Footers, Next: Page Layout Adjustment, Prev: Sections and Chapters, Up: Common Features
1143 Every macro package gives some way to manipulate the "headers" and
1144 "footers" (also called "titles") on each page. This is text put at the
1145 top and bottom of each page, respectively, which contain data like the
1146 current page number, the current chapter title, and so on. Its
1147 appearance is not affected by the running text. Some packages allow
1148 for different ones on the even and odd pages (for material printed in a
1151 The titles are called "three-part titles", that is, there is a
1152 left-justified part, a centered part, and a right-justified part. An
1153 automatically generated page number may be put in any of these fields
1154 with the `%' character (see *Note Page Layout::, for more details).
1157 File: groff, Node: Page Layout Adjustment, Next: Displays, Prev: Headers and Footers, Up: Common Features
1162 Most macro packages let the user specify top and bottom margins and
1163 other details about the appearance of the printed pages.
1166 File: groff, Node: Displays, Next: Footnotes and Annotations, Prev: Page Layout Adjustment, Up: Common Features
1171 "Displays" are sections of text to be set off from the body of the
1172 paper. Major quotes, tables, and figures are types of displays, as are
1173 all the examples used in this document.
1175 "Major quotes" are quotes which are several lines long, and hence
1176 are set in from the rest of the text without quote marks around them.
1178 A "list" is an indented, single-spaced, unfilled display. Lists
1179 should be used when the material to be printed should not be filled and
1180 justified like normal text, such as columns of figures or the examples
1183 A "keep" is a display of lines which are kept on a single page if
1184 possible. An example for a keep might be a diagram. Keeps differ from
1185 lists in that lists may be broken over a page boundary whereas keeps are
1188 "Floating keeps" move relative to the text. Hence, they are good for
1189 things which are referred to by name, such as "See figure 3". A
1190 floating keep appears at the bottom of the current page if it fits;
1191 otherwise, it appears at the top of the next page. Meanwhile, the
1192 surrounding text `flows' around the keep, thus leaving no blank areas.
1195 File: groff, Node: Footnotes and Annotations, Next: Table of Contents, Prev: Displays, Up: Common Features
1197 Footnotes and Annotations
1198 -------------------------
1200 There are a number of requests to save text for later printing.
1202 "Footnotes" are printed at the bottom of the current page.
1204 "Delayed text" is very similar to a footnote except that it is
1205 printed when called for explicitly. This allows a list of references to
1206 appear (for example) at the end of each chapter, as is the convention in
1209 Most macro packages which supply this functionality also supply a
1210 means of automatically numbering either type of annotation.
1213 File: groff, Node: Table of Contents, Next: Indices, Prev: Footnotes and Annotations, Up: Common Features
1218 "Tables of contents" are a type of delayed text having a tag
1219 (usually the page number) attached to each entry after a row of dots.
1220 The table accumulates throughout the paper until printed, usually after
1221 the paper has ended. Many macro packages provide the ability to have
1222 several tables of contents (e.g. a standard table of contents, a list
1226 File: groff, Node: Indices, Next: Paper Formats, Prev: Table of Contents, Up: Common Features
1231 While some macro packages use the term "index", none actually
1232 provide that functionality. The facilities they call indices are
1233 actually more appropriate for tables of contents.
1235 To produce a real index in a document, external tools like the
1236 `makeindex' program are necessary.
1239 File: groff, Node: Paper Formats, Next: Multiple Columns, Prev: Indices, Up: Common Features
1244 Some macro packages provide stock formats for various kinds of
1245 documents. Many of them provide a common format for the title and
1246 opening pages of a technical paper. The `mm' macros in particular
1247 provide formats for letters and memoranda.
1250 File: groff, Node: Multiple Columns, Next: Font and Size Changes, Prev: Paper Formats, Up: Common Features
1255 Some macro packages (but not `man') provide the ability to have two
1256 or more columns on a page.
1259 File: groff, Node: Font and Size Changes, Next: Predefined Strings, Prev: Multiple Columns, Up: Common Features
1261 Font and Size Changes
1262 ---------------------
1264 The built-in font and size functions are not always intuitive, so all
1265 macro packages provide macros to make these operations simpler.
1268 File: groff, Node: Predefined Strings, Next: Preprocessor Support, Prev: Font and Size Changes, Up: Common Features
1273 Most macro packages provide various predefined strings for a variety
1274 of uses; examples are sub- and superscripts, printable dates, quotes and
1275 various special characters.
1278 File: groff, Node: Preprocessor Support, Next: Configuration and Customization, Prev: Predefined Strings, Up: Common Features
1280 Preprocessor Support
1281 --------------------
1283 All macro packages provide support for various preprocessors and may
1284 extend their functionality.
1286 For example, all macro packages mark tables (which are processed with
1287 `gtbl') by placing them between `TS' and `TE' macros. The `ms' macro
1288 package has an option, `.TS H', that prints a caption at the top of a
1289 new page (when the table is too long to fit on a single page).
1292 File: groff, Node: Configuration and Customization, Prev: Preprocessor Support, Up: Common Features
1294 Configuration and Customization
1295 -------------------------------
1297 Some macro packages provide means of customizing many of the details
1298 of how the package behaves. This ranges from setting the default type
1299 size to changing the appearance of section headers.
1302 File: groff, Node: Macro Packages, Next: gtroff Reference, Prev: Tutorial for Macro Users, Up: Top
1307 This chapter documents the main macro packages that come with
1319 File: groff, Node: man, Next: mdoc, Prev: Macro Packages, Up: Macro Packages
1324 This is the most popular and probably the most important macro
1325 package of `groff'. It is easy to use, and a vast majority of manual
1326 pages are based on it.
1333 * Miscellaneous man macros::
1334 * Predefined man strings::
1335 * Preprocessors in man pages::
1338 File: groff, Node: Man options, Next: Man usage, Prev: man, Up: man
1343 The command line format for using the `man' macros with `groff' is:
1346 groff -m man [ -rLL=LENGTH ] [ -rLT=LENGTH ]
1347 [ -rcR=1 ] [ -rC1 ] [ -rD1 ] [ -rPNNN ]
1348 [ -rSXX ] [ -rXNNN ] [ FILES... ]
1350 It is possible to use `-man' instead of `-m man'.
1353 Set line length to LENGTH. If not specified, the line length
1354 defaults to 78 en in nroff mode (this is 78 characters per line)
1355 and 6.5 inch otherwise.
1358 Set title length to LENGTH. If not specified, the title length
1359 defaults to 78 en in nroff mode (this is 78 characters per line)
1360 and 6.5 inch otherwise.
1363 This option (the default if a TTY output device is used) creates a
1364 single, very long page instead of multiple pages. Use `-rcR=0' to
1368 If more than one manual page is given on the command line, number
1369 the pages continuously, rather than starting each at 1.
1372 Double-sided printing. Footers for even and odd pages are
1373 formatted differently.
1376 Page numbering starts with NNN rather than with 1.
1379 Use XX (which can be 10, 11, or 12pt) as the base document font
1380 size instead of the default value of 10pt.
1383 After page NNN, number pages as NNNa, NNNb, NNNc, etc. For
1384 example, the option `-rX2' produces the following page numbers: 1,
tuxillo's projects / dragonfly.git / blob