This is groff, produced by makeinfo version 4.2 from ./groff.texinfo. This manual documents GNU `troff' version 1.18. Copyright (C) 1994-2000, 2001, 2002 Free Software Foundation, Inc. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections, with the Front-Cover texts being `A GNU Manual," and with the Back-Cover Texts as in (a) below. A copy of the license is included in the section entitled `GNU Free Documentation License." (a) The FSF's Back-Cover Text is: `You have freedom to copy and modify this GNU Manual, like GNU software. Copies published by the Free Software Foundation raise funds for GNU development." INFO-DIR-SECTION Miscellaneous START-INFO-DIR-ENTRY * Groff: (groff). The GNU troff document formatting system. END-INFO-DIR-ENTRY  File: groff, Node: Top, Next: Introduction, Prev: (dir), Up: (dir) GNU troff ********* This manual documents GNU `troff' version 1.18. Copyright (C) 1994-2000, 2001, 2002 Free Software Foundation, Inc. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections, with the Front-Cover texts being `A GNU Manual," and with the Back-Cover Texts as in (a) below. A copy of the license is included in the section entitled `GNU Free Documentation License." (a) The FSF's Back-Cover Text is: `You have freedom to copy and modify this GNU Manual, like GNU software. Copies published by the Free Software Foundation raise funds for GNU development." * Menu: * Introduction:: * Invoking groff:: * Tutorial for Macro Users:: * Macro Packages:: * gtroff Reference:: * Preprocessors:: * Output Devices:: * File formats:: * Installation:: * Copying This Manual:: * Request Index:: * Escape Index:: * Operator Index:: * Register Index:: * Macro Index:: * String Index:: * Glyph Name Index:: * Font File Keyword Index:: * Program and File Index:: * Concept Index::  File: groff, Node: Introduction, Next: Invoking groff, Prev: Top, Up: Top Introduction ************ GNU `troff' (or `groff') is a system for typesetting documents. `troff' is very flexible and has been in existence (and use) for about 3 decades. It is quite widespread and firmly entrenched in the UNIX community. * Menu: * What Is groff?:: * History:: * groff Capabilities:: * Macro Package Intro:: * Preprocessor Intro:: * Output device intro:: * Credits::  File: groff, Node: What Is groff?, Next: History, Prev: Introduction, Up: Introduction What Is `groff'? ================ `groff' belongs to an older generation of document preparation systems, which operate more like compilers than the more recent interactive WYSIWYG(1) (*note What Is groff?-Footnote-1::) systems. `groff' and its contemporary counterpart, TeX, both work using a "batch" paradigm: The input (or "source") files are normal text files with embedded formatting commands. These files can then be processed by `groff' to produce a typeset document on a variety of devices. Likewise, `groff' should not be confused with a "word processor", since that term connotes an integrated system that includes an editor and a text formatter. Also, many word processors follow the WYSIWYG paradigm discussed earlier. Although WYSIWYG systems may be easier to use, they have a number of disadvantages compared to `troff': * They must be used on a graphics display to work on a document. * Most of the WYSIWYG systems are either non-free or are not very portable. * `troff' is firmly entrenched in all UNIX systems. * It is difficult to have a wide range of capabilities available within the confines of a GUI/window system. * It is more difficult to make global changes to a document. "GUIs normally make it simple to accomplish simple actions and impossible to accomplish complex actions." -Doug Gwyn (22/Jun/91 in `comp.unix.wizards')  File: groff, Node: What Is groff?-Footnotes, Up: What Is groff? (1) What You See Is What You Get  File: groff, Node: History, Next: groff Capabilities, Prev: What Is groff?, Up: Introduction History ======= `troff' can trace its origins back to a formatting program called `runoff', written by J. E. Saltzer, which ran on MIT's CTSS operating system in the mid-sixties. This name came from the common phrase of the time "I'll run off a document." Bob Morris ported it to the 635 architecture and called the program `roff' (an abbreviation of `runoff'). It was rewritten as `rf' for the PDP-7 (before having UNIX), and at the same time (1969), Doug McIllroy rewrote an extended and simplified version of `roff' in the BCPL programming language. The first version of UNIX was developed on a PDP-7 which was sitting around Bell Labs. In 1971 the developers wanted to get a PDP-11 for further work on the operating system. In order to justify the cost for this system, they proposed that they would implement a document formatting system for the AT&T patents division. This first formatting program was a reimplementation of McIllroy's `roff', written by J. F. Ossanna. When they needed a more flexible language, a new version of `roff' called `nroff' ("Newer `roff'") was written. It had a much more complicated syntax, but provided the basis for all future versions. When they got a Graphic Systems CAT Phototypesetter, Ossanna wrote a version of `nroff' that would drive it. It was dubbed `troff', for "typesetter `roff'", although many people have speculated that it actually means "Times `roff'" because of the use of the Times font family in `troff' by default. As such, the name `troff' is pronounced `t-roff' rather than `trough'. With `troff' came `nroff' (they were actually the same program except for some `#ifdef's), which was for producing output for line printers and character terminals. It understood everything `troff' did, and ignored the commands which were not applicable (e.g. font changes). Since there are several things which cannot be done easily in `troff', work on several preprocessors began. These programs would transform certain parts of a document into `troff', which made a very natural use of pipes in UNIX. The `eqn' preprocessor allowed mathematical formulae to be specified in a much simpler and more intuitive manner. `tbl' is a preprocessor for formatting tables. The `refer' preprocessor (and the similar program, `bib') processes citations in a document according to a bibliographic database. Unfortunately, Ossanna's `troff' was written in PDP-11 assembly language and produced output specifically for the CAT phototypesetter. He rewrote it in C, although it was now 7000 lines of uncommented code and still dependent on the CAT. As the CAT became less common, and was no longer supported by the manufacturer, the need to make it support other devices became a priority. However, before this could be done, Ossanna was killed in a car accident. So, Brian Kernighan took on the task of rewriting `troff'. The newly rewritten version produced device independent code which was very easy for postprocessors to read and translate to the appropriate printer codes. Also, this new version of `troff' (called `ditroff' for "device independent `troff'") had several extensions, which included drawing functions. Due to the additional abilities of the new version of `troff', several new preprocessors appeared. The `pic' preprocessor provides a wide range of drawing functions. Likewise the `ideal' preprocessor did the same, although via a much different paradigm. The `grap' preprocessor took specifications for graphs, but, unlike other preprocessors, produced `pic' code. James Clark began work on a GNU implementation of `ditroff' in early 1989. The first version, `groff' 0.3.1, was released June 1990. `groff' included: * A replacement for `ditroff' with many extensions. * The `soelim', `pic', `tbl', and `eqn' preprocessors. * Postprocessors for character devices, POSTSCRIPT, TeX DVI, and X Windows. GNU `troff' also eliminated the need for a separate `nroff' program with a postprocessor which would produce ASCII output. * A version of the `me' macros and an implementation of the `man' macros. Also, a front-end was included which could construct the, sometimes painfully long, pipelines required for all the post- and preprocessors. Development of GNU `troff' progressed rapidly, and saw the additions of a replacement for `refer', an implementation of the `ms' and `mm' macros, and a program to deduce how to format a document (`grog'). It was declared a stable (i.e. non-beta) package with the release of version 1.04 around November 1991. Beginning in 1999, `groff' has new maintainers (the package was an orphan for a few years). As a result, new features and programs like `grn', a preprocessor for gremlin images, and an output device to produce HTML output have been added.  File: groff, Node: groff Capabilities, Next: Macro Package Intro, Prev: History, Up: Introduction `groff' Capabilities ==================== So what exactly is `groff' capable of doing? `groff' provides a wide range of low-level text formatting operations. Using these, it is possible to perform a wide range of formatting tasks, such as footnotes, table of contents, multiple columns, etc. Here's a list of the most important operations supported by `groff': * text filling, adjusting, and centering * hyphenation * page control * font and glyph size control * vertical spacing (e.g. double-spacing) * line length and indenting * macros, strings, diversions, and traps * number registers * tabs, leaders, and fields * input and output conventions and character translation * overstrike, bracket, line drawing, and zero-width functions * local horizontal and vertical motions and the width function * three-part titles * output line numbering * conditional acceptance of input * environment switching * insertions from the standard input * input/output file switching * output and error messages  File: groff, Node: Macro Package Intro, Next: Preprocessor Intro, Prev: groff Capabilities, Up: Introduction Macro Packages ============== Since `groff' provides such low-level facilities, it can be quite difficult to use by itself. However, `groff' provides a "macro" facility to specify how certain routine operations (e.g. starting paragraphs, printing headers and footers, etc.) should be done. These macros can be collected together into a "macro package". There are a number of macro packages available; the most common (and the ones described in this manual) are `man', `mdoc', `me', `ms', and `mm'.  File: groff, Node: Preprocessor Intro, Next: Output device intro, Prev: Macro Package Intro, Up: Introduction Preprocessors ============= Although `groff' provides most functions needed to format a document, some operations would be unwieldy (e.g. to draw pictures). Therefore, programs called "preprocessors" were written which understand their own language and produce the necessary `groff' operations. These preprocessors are able to differentiate their own input from the rest of the document via markers. To use a preprocessor, UNIX pipes are used to feed the output from the preprocessor into `groff'. Any number of preprocessors may be used on a given document; in this case, the preprocessors are linked together into one pipeline. However, with `groff', the user does not need to construct the pipe, but only tell `groff' what preprocessors to use. `groff' currently has preprocessors for producing tables (`tbl'), typesetting equations (`eqn'), drawing pictures (`pic' and `grn'), and for processing bibliographies (`refer'). An associated program which is useful when dealing with preprocessors is `soelim'. A free implementation of `grap', a preprocessor for drawing graphs, can be obtained as an extra package; `groff' can use `grap' also. There are other preprocessors in existence, but, unfortunately, no free implementations are available. Among them are preprocessors for drawing mathematical pictures (`ideal') and chemical structures (`chem').  File: groff, Node: Output device intro, Next: Credits, Prev: Preprocessor Intro, Up: Introduction Output Devices ============== `groff' actually produces device independent code which may be fed into a postprocessor to produce output for a particular device. Currently, `groff' has postprocessors for POSTSCRIPT devices, character terminals, X Windows (for previewing), TeX DVI format, HP LaserJet 4 and Canon LBP printers (which use CAPSL), and HTML.  File: groff, Node: Credits, Prev: Output device intro, Up: Introduction Credits ======= Large portions of this manual were taken from existing documents, most notably, the manual pages for the `groff' package by James Clark, and Eric Allman's papers on the `me' macro package. The section on the `man' macro package is partly based on Susan G. Kleinmann's `groff_man' manual page written for the Debian GNU/Linux system. Larry Kollar contributed the section in the `ms' macro package.  File: groff, Node: Invoking groff, Next: Tutorial for Macro Users, Prev: Introduction, Up: Top Invoking `groff' **************** This section focuses on how to invoke the `groff' front end. This front end takes care of the details of constructing the pipeline among the preprocessors, `gtroff' and the postprocessor. It has become a tradition that GNU programs get the prefix `g' to distinguish it from its original counterparts provided by the host (see *Note Environment::, for more details). Thus, for example, `geqn' is GNU `eqn'. On operating systems like GNU/Linux or the Hurd, which don't contain proprietary versions of `troff', and on MS-DOS/MS-Windows, where `troff' and associated programs are not available at all, this prefix is omitted since GNU `troff' is the only used incarnation of `troff'. Exception: `groff' is never replaced by `roff'. In this document, we consequently say `gtroff' when talking about the GNU `troff' program. All other implementations of `troff' are called AT&T `troff' which is the common origin of all `troff' derivates (with more or less compatible changes). Similarly, we say `gpic', `geqn', etc. * Menu: * Groff Options:: * Environment:: * Macro Directories:: * Font Directories:: * Invocation Examples::  File: groff, Node: Groff Options, Next: Environment, Prev: Invoking groff, Up: Invoking groff Options ======= `groff' normally runs the `gtroff' program and a postprocessor appropriate for the selected device. The default device is `ps' (but it can be changed when `groff' is configured and built). It can optionally preprocess with any of `gpic', `geqn', `gtbl', `ggrn', `grap', `grefer', or `gsoelim'. This section only documents options to the `groff' front end. Many of the arguments to `groff' are passed on to `gtroff', therefore those are also included. Arguments to pre- or postprocessors can be found in *Note Invoking gpic::, *Note Invoking geqn::, *Note Invoking gtbl::, *Note Invoking ggrn::, *Note Invoking grefer::, *Note Invoking gsoelim::, *Note Invoking grotty::, *Note Invoking grops::, *Note Invoking grohtml::, *Note Invoking grodvi::, *Note Invoking grolj4::, *Note Invoking grolbp::, and *Note Invoking gxditview::. The command line format for `groff' is: groff [ -abceghilpstvzCEGNRSUVXZ ] [ -FDIR ] [ -mNAME ] [ -TDEF ] [ -fFAM ] [ -wNAME ] [ -WNAME ] [ -MDIR ] [ -dCS ] [ -rCN ] [ -nNUM ] [ -oLIST ] [ -PARG ] [ -LARG ] [ -IDIR ] [ FILES... ] The command line format for `gtroff' is as follows. gtroff [ -abcivzCERU ] [ -wNAME ] [ -WNAME ] [ -dCS ] [ -fFAM ] [ -mNAME ] [ -nNUM ] [ -oLIST ] [ -rCN ] [ -TNAME ] [ -FDIR ] [ -MDIR ] [ FILES... ] Obviously, many of the options to `groff' are actually passed on to `gtroff'. Options without an argument can be grouped behind a single `-'. A filename of `-' denotes the standard input. It is possible to have whitespace between an option and its parameter. The `grog' command can be used to guess the correct `groff' command to format a file. Here's the description of the command-line options: `-h' Print a help message. `-e' Preprocess with `geqn'. `-t' Preprocess with `gtbl'. `-g' Preprocess with `ggrn'. `-G' Preprocess with `grap'. `-p' Preprocess with `gpic'. `-s' Preprocess with `gsoelim'. `-c' Suppress color output. `-R' Preprocess with `grefer'. No mechanism is provided for passing arguments to `grefer' because most `grefer' options have equivalent commands which can be included in the file. *Note grefer::, for more details. Note that `gtroff' also accepts a `-R' option, which is not accessible via `groff'. This option prevents the loading of the `troffrc' and `troffrc-end' files. `-v' Make programs run by `groff' print out their version number. `-V' Print the pipeline on `stdout' instead of executing it. `-z' Suppress output from `gtroff'. Only error messages are printed. `-Z' Do not postprocess the output of `gtroff'. Normally `groff' automatically runs the appropriate postprocessor. `-PARG' Pass ARG to the postprocessor. Each argument should be passed with a separate `-P' option. Note that `groff' does not prepend `-' to ARG before passing it to the postprocessor. `-l' Send the output to a spooler for printing. The command used for this is specified by the `print' command in the device description file (see *Note Font Files::, for more info). If not present, `-l' is ignored. `-LARG' Pass ARG to the spooler. Each argument should be passed with a separate `-L' option. Note that `groff' does not prepend a `-' to ARG before passing it to the postprocessor. If the `print' keyword in the device description file is missing, `-L' is ignored. `-TDEV' Prepare output for device DEV. The default device is `ps', unless changed when `groff' was configured and built. The following are the output devices currently available: `ps' For POSTSCRIPT printers and previewers. `dvi' For TeX DVI format. `X75' For a 75dpi X11 previewer. `X75-12' For a 75dpi X11 previewer with a 12pt base font in the document. `X100' For a 100dpi X11 previewer. `X100-12' For a 100dpi X11 previewer with a 12pt base font in the document. `ascii' For typewriter-like devices using the (7-bit) ASCII character set. `latin1' For typewriter-like devices that support the Latin-1 (ISO 8859-1) character set. `utf8' For typewriter-like devices which use the Unicode (ISO 10646) character set with UTF-8 encoding. `cp1047' For typewriter-like devices which use the EBCDIC encoding IBM cp1047. `lj4' For HP LaserJet4-compatible (or other PCL5-compatible) printers. `lbp' For Canon CAPSL printers (LBP-4 and LBP-8 series laser printers). `html' To produce HTML output. Note that the HTML driver consists of two parts, a preprocessor (`pre-grohtml') and a postprocessor (`post-grohtml'). The predefined `gtroff' string register `.T' contains the current output device; the read-only number register `.T' is set to 1 if this option is used (which is always true if `groff' is used to call `gtroff'). *Note Built-in Registers::. The postprocessor to be used for a device is specified by the `postpro' command in the device description file. (*Note Font Files::, for more info.) This can be overridden with the `-X' option. `-X' Preview with `gxditview' instead of using the usual postprocessor. This is unlikely to produce good results except with `-Tps'. Note that this is not the same as using `-TX75' or `-TX100' to view a document with `gxditview': The former uses the metrics of the specified device, whereas the latter uses X-specific fonts and metrics. `-N' Don't allow newlines with `eqn' delimiters. This is the same as the `-N' option in `geqn'. `-S' Safer mode. Pass the `-S' option to `gpic' and disable the `open', `opena', `pso', `sy', and `pi' requests. For security reasons, this is enabled by default. `-U' Unsafe mode. This enables the `open', `opena', `pso', `sy', and `pi' requests. `-a' Generate an ASCII approximation of the typeset output. The read-only register `.A' is then set to 1. *Note Built-in Registers::. A typical example is groff -a -man -Tdvi troff.man | less which shows how lines are broken for the DVI device. Note that this option is rather useless today since graphic output devices are available virtually everywhere. `-b' Print a backtrace with each warning or error message. This backtrace should help track down the cause of the error. The line numbers given in the backtrace may not always be correct: `gtroff' can get confused by `as' or `am' requests while counting line numbers. `-i' Read the standard input after all the named input files have been processed. `-wNAME' Enable warning NAME. Available warnings are described in *Note Debugging::. Multiple `-w' options are allowed. `-WNAME' Inhibit warning NAME. Multiple `-W' options are allowed. `-E' Inhibit all error messages. `-C' Enable compatibility mode. *Note Implementation Differences::, for the list of incompatibilities between `groff' and AT&T `troff'. `-dCS' `-dNAME=S' Define C or NAME to be a string S. C must be a one-letter name; NAME can be of arbitrary length. All string assignments happen before loading any macro file (including the start-up file). `-fFAM' Use FAM as the default font family. *Note Font Families::. `-mNAME' Read in the file `NAME.tmac'. Normally `groff' searches for this in its macro directories. If it isn't found, it tries `tmac.NAME' (searching in the same directories). `-nNUM' Number the first page NUM. `-oLIST' Output only pages in LIST, which is a comma-separated list of page ranges; `N' means print page N, `M-N' means print every page between M and N, `-N' means print every page up to N, `N-' means print every page beginning with N. `gtroff' exits after printing the last page in the list. All the ranges are inclusive on both ends. Within `gtroff', this information can be extracted with the `.P' register. *Note Built-in Registers::. If your document restarts page numbering at the beginning of each chapter, then `gtroff' prints the specified page range for each chapter. `-rCN' `-rNAME=N' Set number register C or NAME to the value N. C must be a one-letter name; NAME can be of arbitrary length. N can be any `gtroff' numeric expression. All register assignments happen before loading any macro file (including the start-up file). `-FDIR' Search `DIR' for subdirectories `devNAME' (NAME is the name of the device), for the `DESC' file, and for font files before looking in the standard directories (*note Font Directories::). This option is passed to all pre- and postprocessors using the `GROFF_FONT_PATH' environment variable. `-MDIR' Search directory `DIR' for macro files before the standard directories (*note Macro Directories::). `-IDIR' This option is as described in *Note gsoelim::. It implies the `-s' option.  File: groff, Node: Environment, Next: Macro Directories, Prev: Groff Options, Up: Invoking groff Environment =========== There are also several environment variables (of the operating system, not within `gtroff') which can modify the behavior of `groff'. `GROFF_COMMAND_PREFIX' If this is set to X, then `groff' runs `Xtroff' instead of `gtroff'. This also applies to `tbl', `pic', `eqn', `grn', `refer', and `soelim'. It does not apply to `grops', `grodvi', `grotty', `pre-grohtml', `post-grohtml', `grolj4', and `gxditview'. The default command prefix is determined during the installation process. If a non-GNU troff system is found, prefix `g' is used, none otherwise. `GROFF_TMAC_PATH' A colon-separated list of directories in which to search for macro files (before the default directories are tried). *Note Macro Directories::. `GROFF_TYPESETTER' The default output device. `GROFF_FONT_PATH' A colon-separated list of directories in which to search for the `dev'NAME directory (before the default directories are tried). *Note Font Directories::. `GROFF_BIN_PATH' This search path, followed by `PATH', is used for commands executed by `groff'. `GROFF_TMPDIR' The directory in which `groff' creates temporary files. If this is not set and `TMPDIR' is set, temporary files are created in that directory. Otherwise temporary files are created in a system-dependent default directory (on Unix and GNU/Linux systems, this is usually `/tmp'). `grops', `grefer', `pre-grohtml', and `post-grohtml' can create temporary files in this directory. Note that MS-DOS and MS-Windows ports of `groff' use semi-colons, rather than colons, to separate the directories in the lists described above.  File: groff, Node: Macro Directories, Next: Font Directories, Prev: Environment, Up: Invoking groff Macro Directories ================= All macro file names must be named `NAME.tmac' or `tmac.NAME' to make the `-mNAME' command line option work. The `mso' request doesn't have this restriction; any file name can be used, and `gtroff' won't try to append or prepend the `tmac' string. Macro files are kept in the "tmac directories", all of which constitute the "tmac path". The elements of the search path for macro files are (in that order): * The directories specified with `gtroff''s or `groff''s `-M' command line option. * The directories given in the `GROFF_TMAC_PATH' environment variable. * The current directory (only if in unsafe mode using the `-U' command line switch). * The home directory. * A platform-dependent directory, a site-specific (platform-independent) directory, and the main tmac directory; the default locations are /usr/local/lib/groff/site-tmac /usr/local/share/groff/site-tmac /usr/local/share/groff/1.18/tmac assuming that the version of `groff' is 1.18, and the installation prefix was `/usr/local'. It is possible to fine-tune those directories during the installation process.  File: groff, Node: Font Directories, Next: Invocation Examples, Prev: Macro Directories, Up: Invoking groff Font Directories ================ Basically, there is no restriction how font files for `groff' are named and how long font names are; however, to make the font family mechanism work (*note Font Families::), fonts within a family should start with the family name, followed by the shape. For example, the Times family uses `T' for the family name and `R', `B', `I', and `BI' to indicate the shapes `roman', `bold', `italic', and `bold italic', respectively. Thus the final font names are `TR', `TB', `TI', and `TBI'. All font files are kept in the "font directories" which constitute the "font path". The file search functions will always append the directory `dev'NAME, where NAME is the name of the output device. Assuming, say, DVI output, and `/foo/bar' as a font directory, the font files for `grodvi' must be in `/foo/bar/devdvi'. The elements of the search path for font files are (in that order): * The directories specified with `gtroff''s or `groff''s `-F' command line option. All device drivers and some preprocessors also have this option. * The directories given in the `GROFF_FONT_PATH' environment variable. * A site-specific directory and the main font directory; the default locations are /usr/local/share/groff/site-font /usr/local/share/groff/1.18/font assuming that the version of `groff' is 1.18, and the installation prefix was `/usr/local'. It is possible to fine-tune those directories during the installation process.  File: groff, Node: Invocation Examples, Prev: Font Directories, Up: Invoking groff Invocation Examples =================== This section lists several common uses of `groff' and the corresponding command lines. groff file This command processes `file' without a macro package or a preprocessor. The output device is the default, `ps', and the output is sent to `stdout'. groff -t -mandoc -Tascii file | less This is basically what a call to the `man' program does. `gtroff' processes the manual page `file' with the `mandoc' macro file (which in turn either calls the `man' or the `mdoc' macro package), using the `tbl' preprocessor and the ASCII output device. Finally, the `less' pager displays the result. groff -X -m me file Preview `file' with `gxditview', using the `me' macro package. Since no `-T' option is specified, use the default device (`ps'). Note that you can either say `-m me' or `-me'; the latter is an anachronism from the early days of UNIX.(1) (*note Invocation Examples-Footnote-1::) groff -man -rD1 -z file Check `file' with the `man' macro package, forcing double-sided printing - don't produce any output. * Menu: * grog::  File: groff, Node: Invocation Examples-Footnotes, Up: Invocation Examples (1) The same is true for the other main macro packages that come with `groff': `man', `mdoc', `ms', `mm', and `mandoc'. This won't work in general; for example, to load `trace.tmac', either `-mtrace' or `-m trace' must be used.  File: groff, Node: grog, Prev: Invocation Examples, Up: Invocation Examples `grog' ------ `grog' reads files, guesses which of the `groff' preprocessors and/or macro packages are required for formatting them, and prints the `groff' command including those options on the standard output. It generates one or more of the options `-e', `-man', `-me', `-mm', `-mom', `-ms', `-mdoc', `-mdoc-old', `-p', `-R', `-g', `-G', `-s', and `-t'. A special file name `-' refers to the standard input. Specifying no files also means to read the standard input. Any specified options are included in the printed command. No space is allowed between options and their arguments. The only options recognized are `-C' (which is also passed on) to enable compatibility mode, and `-v' to print the version number and exit. For example, grog -Tdvi paper.ms guesses the appropriate command to print `paper.ms' and then prints it to the command line after adding the `-Tdvi' option. For direct execution, enclose the call to `grog' in backquotes at the UNIX shell prompt: `grog -Tdvi paper.ms` > paper.dvi As seen in the example, it is still necessary to redirect the output to something meaningful (i.e. either a file or a pager program like `less').  File: groff, Node: Tutorial for Macro Users, Next: Macro Packages, Prev: Invoking groff, Up: Top Tutorial for Macro Users ************************ Most users tend to use a macro package to format their papers. This means that the whole breadth of `groff' is not necessary for most people. This chapter covers the material needed to efficiently use a macro package. * Menu: * Basics:: * Common Features::  File: groff, Node: Basics, Next: Common Features, Prev: Tutorial for Macro Users, Up: Tutorial for Macro Users Basics ====== This section covers some of the basic concepts necessary to understand how to use a macro package.(1) (*note Basics-Footnote-1::) References are made throughout to more detailed information, if desired. `gtroff' reads an input file prepared by the user and outputs a formatted document suitable for publication or framing. The input consists of text, or words to be printed, and embedded commands ("requests" and "escapes"), which tell `gtroff' how to format the output. For more detail on this, see *Note Embedded Commands::. The word "argument" is used in this chapter to mean a word or number which appears on the same line as a request, and which modifies the meaning of that request. For example, the request .sp spaces one line, but .sp 4 spaces four lines. The number 4 is an argument to the `sp' request which says to space four lines instead of one. Arguments are separated from the request and from each other by spaces (_no_ tabs). More details on this can be found in *Note Request Arguments::. The primary function of `gtroff' is to collect words from input lines, fill output lines with those words, justify the right-hand margin by inserting extra spaces in the line, and output the result. For example, the input: Now is the time for all good men to come to the aid of their party. Four score and seven years ago, etc. is read, packed onto output lines, and justified to produce: Now is the time for all good men to come to the aid of their party. Four score and seven years ago, etc. Sometimes a new output line should be started even though the current line is not yet full; for example, at the end of a paragraph. To do this it is possible to cause a "break", which starts a new output line. Some requests cause a break automatically, as normally do blank input lines and input lines beginning with a space. Not all input lines are text to be formatted. Some input lines are requests which describe how to format the text. Requests always have a period (`.') or an apostrophe (`'') as the first character of the input line. The text formatter also does more complex things, such as automatically numbering pages, skipping over page boundaries, putting footnotes in the correct place, and so forth. Here are a few hints for preparing text for input to `gtroff'. * First, keep the input lines short. Short input lines are easier to edit, and `gtroff' packs words onto longer lines anyhow. * In keeping with this, it is helpful to begin a new line after every comma or phrase, since common corrections are to add or delete sentences or phrases. * End each sentence with two spaces - or better, start each sentence on a new line. `gtroff' recognizes characters that usually end a sentence, and inserts sentence space accordingly. * Do not hyphenate words at the end of lines - `gtroff' is smart enough to hyphenate words as needed, but is not smart enough to take hyphens out and join a word back together. Also, words such as "mother-in-law" should not be broken over a line, since then a space can occur where not wanted, such as "mother- in-law". `gtroff' double-spaces output text automatically if you use the request `.ls 2'. Reactivate single-spaced mode by typing `.ls 1'.(2) (*note Basics-Footnote-2::) A number of requests allow to change the way the output looks, sometimes called the "layout" of the output page. Most of these requests adjust the placing of "whitespace" (blank lines or spaces). The `bp' request starts a new page, causing a line break. The request `.sp N' leaves N lines of blank space. N can be omitted (meaning skip a single line) or can be of the form Ni (for N inches) or Nc (for N centimeters). For example, the input: .sp 1.5i My thoughts on the subject .sp leaves one and a half inches of space, followed by the line "My thoughts on the subject", followed by a single blank line (more measurement units are available, see *Note Measurements::). Text lines can be centered by using the `ce' request. The line after `ce' is centered (horizontally) on the page. To center more than one line, use `.ce N' (where N is the number of lines to center), followed by the N lines. To center many lines without counting them, type: .ce 1000 lines to center .ce 0 The `.ce 0' request tells `groff' to center zero more lines, in other words, stop centering. All of these requests cause a break; that is, they always start a new line. To start a new line without performing any other action, use `br'.  File: groff, Node: Basics-Footnotes, Up: Basics (1) This section is derived from `Writing Papers with nroff using -me' by Eric P. Allman. (2) If you need finer granularity of the vertical space, use the `pvs' request (*note Changing Type Sizes::).  File: groff, Node: Common Features, Prev: Basics, Up: Tutorial for Macro Users Common Features =============== `gtroff' provides very low-level operations for formatting a document. There are many common routine operations which are done in all documents. These common operations are written into "macros" and collected into a "macro package". All macro packages provide certain common capabilities which fall into the following categories. * Menu: * Paragraphs:: * Sections and Chapters:: * Headers and Footers:: * Page Layout Adjustment:: * Displays:: * Footnotes and Annotations:: * Table of Contents:: * Indices:: * Paper Formats:: * Multiple Columns:: * Font and Size Changes:: * Predefined Strings:: * Preprocessor Support:: * Configuration and Customization::  File: groff, Node: Paragraphs, Next: Sections and Chapters, Prev: Common Features, Up: Common Features Paragraphs ---------- One of the most common and most used capability is starting a paragraph. There are a number of different types of paragraphs, any of which can be initiated with macros supplied by the macro package. Normally, paragraphs start with a blank line and the first line indented, like the text in this manual. There are also block style paragraphs, which omit the indentation: Some men look at constitutions with sanctimonious reverence, and deem them like the ark of the covenant, too sacred to be touched. And there are also indented paragraphs which begin with a tag or label at the margin and the remaining text indented. one This is the first paragraph. Notice how the first line of the resulting paragraph lines up with the other lines in the paragraph. longlabel This paragraph had a long label. The first character of text on the first line does not line up with the text on second and subsequent lines, although they line up with each other. A variation of this is a bulleted list. . Bulleted lists start with a bullet. It is possible to use other glyphs instead of the bullet. In nroff mode using the ASCII character set for output, a dot is used instead of a real bullet.  File: groff, Node: Sections and Chapters, Next: Headers and Footers, Prev: Paragraphs, Up: Common Features Sections and Chapters --------------------- Most macro packages supply some form of section headers. The simplest kind is simply the heading on a line by itself in bold type. Others supply automatically numbered section heading or different heading styles at different levels. Some, more sophisticated, macro packages supply macros for starting chapters and appendices.  File: groff, Node: Headers and Footers, Next: Page Layout Adjustment, Prev: Sections and Chapters, Up: Common Features Headers and Footers ------------------- Every macro package gives some way to manipulate the "headers" and "footers" (also called "titles") on each page. This is text put at the top and bottom of each page, respectively, which contain data like the current page number, the current chapter title, and so on. Its appearance is not affected by the running text. Some packages allow for different ones on the even and odd pages (for material printed in a book form). The titles are called "three-part titles", that is, there is a left-justified part, a centered part, and a right-justified part. An automatically generated page number may be put in any of these fields with the `%' character (see *Note Page Layout::, for more details).  File: groff, Node: Page Layout Adjustment, Next: Displays, Prev: Headers and Footers, Up: Common Features Page Layout ----------- Most macro packages let the user specify top and bottom margins and other details about the appearance of the printed pages.  File: groff, Node: Displays, Next: Footnotes and Annotations, Prev: Page Layout Adjustment, Up: Common Features Displays -------- "Displays" are sections of text to be set off from the body of the paper. Major quotes, tables, and figures are types of displays, as are all the examples used in this document. "Major quotes" are quotes which are several lines long, and hence are set in from the rest of the text without quote marks around them. A "list" is an indented, single-spaced, unfilled display. Lists should be used when the material to be printed should not be filled and justified like normal text, such as columns of figures or the examples used in this paper. A "keep" is a display of lines which are kept on a single page if possible. An example for a keep might be a diagram. Keeps differ from lists in that lists may be broken over a page boundary whereas keeps are not. "Floating keeps" move relative to the text. Hence, they are good for things which are referred to by name, such as "See figure 3". A floating keep appears at the bottom of the current page if it fits; otherwise, it appears at the top of the next page. Meanwhile, the surrounding text `flows' around the keep, thus leaving no blank areas.  File: groff, Node: Footnotes and Annotations, Next: Table of Contents, Prev: Displays, Up: Common Features Footnotes and Annotations ------------------------- There are a number of requests to save text for later printing. "Footnotes" are printed at the bottom of the current page. "Delayed text" is very similar to a footnote except that it is printed when called for explicitly. This allows a list of references to appear (for example) at the end of each chapter, as is the convention in some disciplines. Most macro packages which supply this functionality also supply a means of automatically numbering either type of annotation.  File: groff, Node: Table of Contents, Next: Indices, Prev: Footnotes and Annotations, Up: Common Features Table of Contents ----------------- "Tables of contents" are a type of delayed text having a tag (usually the page number) attached to each entry after a row of dots. The table accumulates throughout the paper until printed, usually after the paper has ended. Many macro packages provide the ability to have several tables of contents (e.g. a standard table of contents, a list of tables, etc).  File: groff, Node: Indices, Next: Paper Formats, Prev: Table of Contents, Up: Common Features Indices ------- While some macro packages use the term "index", none actually provide that functionality. The facilities they call indices are actually more appropriate for tables of contents. To produce a real index in a document, external tools like the `makeindex' program are necessary.  File: groff, Node: Paper Formats, Next: Multiple Columns, Prev: Indices, Up: Common Features Paper Formats ------------- Some macro packages provide stock formats for various kinds of documents. Many of them provide a common format for the title and opening pages of a technical paper. The `mm' macros in particular provide formats for letters and memoranda.  File: groff, Node: Multiple Columns, Next: Font and Size Changes, Prev: Paper Formats, Up: Common Features Multiple Columns ---------------- Some macro packages (but not `man') provide the ability to have two or more columns on a page.  File: groff, Node: Font and Size Changes, Next: Predefined Strings, Prev: Multiple Columns, Up: Common Features Font and Size Changes --------------------- The built-in font and size functions are not always intuitive, so all macro packages provide macros to make these operations simpler.  File: groff, Node: Predefined Strings, Next: Preprocessor Support, Prev: Font and Size Changes, Up: Common Features Predefined Strings ------------------ Most macro packages provide various predefined strings for a variety of uses; examples are sub- and superscripts, printable dates, quotes and various special characters.  File: groff, Node: Preprocessor Support, Next: Configuration and Customization, Prev: Predefined Strings, Up: Common Features Preprocessor Support -------------------- All macro packages provide support for various preprocessors and may extend their functionality. For example, all macro packages mark tables (which are processed with `gtbl') by placing them between `TS' and `TE' macros. The `ms' macro package has an option, `.TS H', that prints a caption at the top of a new page (when the table is too long to fit on a single page).  File: groff, Node: Configuration and Customization, Prev: Preprocessor Support, Up: Common Features Configuration and Customization ------------------------------- Some macro packages provide means of customizing many of the details of how the package behaves. This ranges from setting the default type size to changing the appearance of section headers.  File: groff, Node: Macro Packages, Next: gtroff Reference, Prev: Tutorial for Macro Users, Up: Top Macro Packages ************** This chapter documents the main macro packages that come with `groff'. * Menu: * man:: * mdoc:: * ms:: * me:: * mm::  File: groff, Node: man, Next: mdoc, Prev: Macro Packages, Up: Macro Packages `man' ===== This is the most popular and probably the most important macro package of `groff'. It is easy to use, and a vast majority of manual pages are based on it. * Menu: * Man options:: * Man usage:: * Man font macros:: * Miscellaneous man macros:: * Predefined man strings:: * Preprocessors in man pages::  File: groff, Node: Man options, Next: Man usage, Prev: man, Up: man Options ------- The command line format for using the `man' macros with `groff' is: groff -m man [ -rLL=LENGTH ] [ -rLT=LENGTH ] [ -rcR=1 ] [ -rC1 ] [ -rD1 ] [ -rPNNN ] [ -rSXX ] [ -rXNNN ] [ FILES... ] It is possible to use `-man' instead of `-m man'. `-rLL=LENGTH' Set line length to LENGTH. If not specified, the line length defaults to 78 en in nroff mode (this is 78 characters per line) and 6.5 inch otherwise. `-rLT=LENGTH' Set title length to LENGTH. If not specified, the title length defaults to 78 en in nroff mode (this is 78 characters per line) and 6.5 inch otherwise. `-rcR=1' This option (the default if a TTY output device is used) creates a single, very long page instead of multiple pages. Use `-rcR=0' to disable it. `-rC1' If more than one manual page is given on the command line, number the pages continuously, rather than starting each at 1. `-rD1' Double-sided printing. Footers for even and odd pages are formatted differently. `-rPNNN' Page numbering starts with NNN rather than with 1. `-rSXX' Use XX (which can be 10, 11, or 12pt) as the base document font size instead of the default value of 10pt. `-rXNNN' After page NNN, number pages as NNNa, NNNb, NNNc, etc. For example, the option `-rX2' produces the following page numbers: 1, 2, 2a, 2b, 2c, etc.