diff options
Diffstat (limited to 'contrib/groff/doc/groff-1')
| -rw-r--r-- | contrib/groff/doc/groff-1 | 1386 |
1 files changed, 1386 insertions, 0 deletions
diff --git a/contrib/groff/doc/groff-1 b/contrib/groff/doc/groff-1 new file mode 100644 index 0000000..0f13ab3 --- /dev/null +++ b/contrib/groff/doc/groff-1 @@ -0,0 +1,1386 @@ +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. + |
