xref: /netbsd-src/external/gpl2/groff/dist/src/roff/groff/groff.man (revision cef8759bd76c1b621f8eab8faa6f208faabc2e15)
groff.man Last update: 01 Jul 2005 Copyright (C) 1989, 2002, 2003, 2004, 2005 Free Software Foundation, Inc. Rewritten in 2002 by Bernd Warken <bwarken@mayn.de> 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 the Invariant Sections being this .ig-section and AUTHOR, with no Front-Cover Texts, and with no Back-Cover Texts. A copy of the Free Documentation License is included as a file called FDL in the main directory of the groff source package. .. . --------------------------------------------------------------------
Setup
--------------------------------------------------------------------
. .do nr groff_C \n[.C] .cp 0 . .mso www.tmac . set adjust to both
. fonts of fixed length
. . mso tty-char.tmac . ftr CR R . ftr CI I . ftr CB B .\} . . ftr CB CW . --------------------------------------------------------------------
String definitions
. . . . --------------------------------------------------------------------
Begin of macro definitions
this is like a comment request when escape mechanism is off
.. .eo . .c --------------------------------------------------------------------

.ns

\$1 .. .c -------------------------------------------------------------------- .c Like TP, but if specified indent is more than half .c the current line-length - indent, use the default indent. . ie \n[.$]=0:((0\$1)*2u>(\n.lu-\n(.iu)) .TP . el .TP "\$1" .. .c -------------------------------------------------------------------- . nop \)\$* .. .c -------------------------------------------------------------------- . ds @arg1 \$1\" . nr @old_indent \n[.i] . ad l . in +\w'\f[B]\*[@arg1]\0'u . ti \n[@old_indent]u . B \*[@arg1]\0\c . rr @old_indent . rm @arg1 .. .c -------------------------------------------------------------------- . ad . in .. .c -------------------------------------------------------------------- .c ShortOpt[] (name [arg]) .c .c short option in synopsis .c . if \n[.$]=0 \ . return . ds @opt \$1\" . shift . ie \n[.$]=0 \ . Text \f[R][\f[]\f[CB]\*[@-]\*[@opt]\f[]\f[R]]\f[] . el \ . Text \f[R][\f[]\f[CB]\*[@-]\*[@opt]\~\f[]\f[I]\/\$*\f[]\f[R]]\f[] . rm @opt .. .c -------------------------------------------------------------------- .c Option in synopsis (short option) . if \n[.$]=0 \ . return . ds @opt \$1\" . shift . ie \n[.$]=0 \ . Text \f[R][\f[]\f[CB]\*[@-]\*[@opt]\f[]\f[R]]\f[] . el \ . Text \f[R][\f[]\f[CB]\*[@-]\*[@opt]\~\f[]\f[I]\/\$*\f[]\f[R]]\f[] . rm @opt .. .c -------------------------------------------------------------------- .c ShortOpt ([char [punct]]) .c .c `-c' somewhere in the text .c second arg is punctuation .c . ds @opt \$1\" . shift . Text \f[CB]\*[@-]\*[@opt]\f[]\/\$* . rm @opt .. .c -------------------------------------------------------------------- .c LongOpt ([name [punct]]) .c .c `--name' somewhere in the text .c second arg is punctuation .c . ds @opt \$1\" . shift . Text \f[CB]\*[@--]\f[]\f[B]\*[@opt]\f[]\/\$* . rm @opt .. .c -------------------------------------------------------------------- .c OptDef (shortopt [longopt [argument]]) .c .c option documentation .c args : `shortopt', `longopt' can be "" .c . ds @short . ds @long . ds @arg . if \n[.$]>=1 \{\ . ds @arg1 "\$1\" . if !'\*[@arg1]'' \ . ds @short "\f[CB]\*[@-]\*[@arg1]\f[]\" . if \n[.$]>=2 \{\ . if !'\*[@short]'' \ . as @short \f[CW]\0\f[] . ds @arg2 "\$2\" . if !'\*[@arg2]'' \ . ds @long "\f[CB]\*[@--]\f[]\f[B]\*[@arg2]\f[]\" . if \n[.$]>=3 \{\ . if !'\*[@long]'' \ . as @long \|=\|\" . shift 2 . ds @arg \f[I]\$*\" . \} . \} . \} . IP "\f[R]\*[@short]\*[@long]\*[@arg]\f[]" . rm @arg . rm @arg1 . rm @arg2 . rm @short . rm @long .. .c -------------------------------------------------------------------- .c Continuation of an OptDef header. . br . ns . OptDef \$@ .. .c -------------------------------------------------------------------- .c Environment variable . SM . BR \%\$1 \$2 .. .c -------------------------------------------------------------------- .c a shell command line . nr @font \n[.f] . c replace argument separator by unbreakable space . ds @args \$1\"" . shift . while (\n[.$]>0) \{\ . ds @args \*[@args]\~\$1 . shift . \} . br . ad l . nh . Text \f[I]sh#\h'1m'\f[P]\f[CR]\*[@args]\f[P]\" . ft R . ft P . hy . ad . ft \n[@font] . br . rr @font . rm @args .. .c -------------------------------------------------------------------- .c `char or string' . ft CR . Text \[oq]\$*\[cq] . ft .. .c -------------------------------------------------------------------- .c End of macro definitions .ec . . --------------------------------------------------------------------
Title
--------------------------------------------------------------------
.

GROFF @MAN1EXT@ "@MDATE@" "Groff Version @VERSION@"
NAME
groff - front-end for the groff document formatting system . . --------------------------------------------------------------------
SYNOPSIS
--------------------------------------------------------------------
. .Synopsis groff .ShortOpt[] abcegilpstzCEGNRSUVXZ .ShortOpt[] d cs .ShortOpt[] f fam .ShortOpt[] F dir .ShortOpt[] I dir .ShortOpt[] L arg .ShortOpt[] m name .ShortOpt[] M dir .ShortOpt[] n num .ShortOpt[] o list .ShortOpt[] P arg .ShortOpt[] r cn .ShortOpt[] T dev .ShortOpt[] w name .ShortOpt[] W name [ file .Text \*[Ellipsis]] .EndSynopsis . .Synopsis groff .ShortOpt h | .LongOpt help .EndSynopsis . .Synopsis groff .ShortOpt v | .LongOpt version [ option .Text \*[Ellipsis]] .EndSynopsis .

The command line is parsed according to the usual GNU convention. . The whitespace between a command line option and its argument is optional. . Options can be grouped behind a single .ShortOpt (minus character). . A filename of .ShortOpt (minus character) denotes the standard input. . . --------------------------------------------------------------------

DESCRIPTION
--------------------------------------------------------------------
. This document describes the groff program, the main front-end for the groff document formatting system. . The groff program and macro suite is the implementation of a roff (@MAN7EXT@) system within the free software collection RL http://\:www.gnu.org "GNU" . . The groff system has all features of the classical roff , but adds many extensions. .

The groff program allows to control the whole groff system by command line options. . This is a great simplification in comparison to the classical case (which uses pipes only). . . --------------------------------------------------------------------

OPTIONS
--------------------------------------------------------------------
. As groff is a wrapper program for @g@troff both programs share a set of options. . But the groff program has some additional, native options and gives a new meaning to some @g@troff options. . On the other hand, not all @g@troff options can be fed into groff . . . --------------------------------------------------------------------
Native groff Options
--------------------------------------------------------------------
. The following options either do not exist for @g@troff or are differently interpreted by groff . . . .OptDef e Preprocess with @g@eqn . . . .OptDef g Preprocess with @g@grn . . . .OptDef G Preprocess with grap . . . .OptDef h help Print a help message. . . .OptDef I "" dir This option may be used to specify a directory to search for files (both those on the command line and those named in .psbb and .so requests, and \eX'ps: import' and \eX'ps: file' escapes). The current directory is always searched first. This option may be specified more than once; the directories will be searched in the order specified. No directory search is performed for files specified using an absolute path. This option implies the .ShortOpt s option. . . .OptDef l Send the output to a spooler program for printing. . The command that should be used for this is specified by the print command in the device description file, see \%groff_font (@MAN5EXT@). If this command is not present, the output is piped into the lpr (1) program by default. . See options .ShortOpt L and .ShortOpt X . . . .OptDef L "" arg Pass arg to the spooler program. Several arguments should be passed with a separate .ShortOpt L option each. . Note that groff does not prepend .ShortOpt\" just a minus sign (a minus sign) to arg before passing it to the spooler program. . . .OptDef N Don't allow newlines within eqn delimiters. . This is the same as the .ShortOpt N option in @g@eqn . . . .OptDef p Preprocess with @g@pic . . . .OptDef P "" "\*[@-]option" .OptDef+ P "" "\*[@-]option \f[CB]\*[@-]P\f[] arg" Pass \*[@-]option or \*[@-]option arg to the postprocessor. . The option must be specified with the necessary preceding minus sign(s) .Quoted \*[@-] or .Quoted \*[@--] because groff does not prepend any dashes before passing it to the postprocessor. . For example, to pass a title to the \%gxditview postprocessor, the shell command
.ShellCommand groff \*[@-]X \*[@-]P \*[@-]title \*[@-]P 'groff it' \f[I]foo\f[]
is equivalent to
.ShellCommand groff \*[@-]X \*[@-]Z \f[I]foo\f[] | \ gxditview \*[@-]title 'groff it' \*[@-] . . .OptDef R Preprocess with @g@refer . . No mechanism is provided for passing arguments to @g@refer because most @g@refer options have equivalent language elements that can be specified within the document. . See \%@g@refer (@MAN1EXT@) for more details. . . .OptDef s Preprocess with @g@soelim . . . .OptDef S Safer mode. . Pass the .ShortOpt S option to @g@pic and disable the following @g@troff requests: .open , .opena , .pso , .sy , and .pi . For security reasons, safer mode is enabled by default. . . .OptDef t Preprocess with @g@tbl . . . .OptDef T "" dev Set output device to dev . For this device, @g@troff generates the intermediate output ; see \%groff_out (@MAN5EXT@). . Then groff calls a postprocessor to convert @g@troff 's intermediate output to its final format. . Real devices in groff are .

dvi
TeX DVI format (postprocessor is grodvi ).
html
HTML output (preprocessors are @g@soelim and \%pre-grohtml , postprocessor is \%post-grohtml ).
lbp
Canon CAPSL printers (\%LBP-4 and \%LBP-8 series laser printers; postprocessor is grolbp ).
lj4
HP LaserJet4 compatible (or other PCL5 compatible) printers (postprocessor is grolj4 ).
ps
PostScript output (postprocessor is grops ).
.
For the following TTY output devices (postprocessor is always grotty ), .ShortOpt T selects the output encoding:

ascii
7bit ASCII.
cp1047
\%Latin-1 character set for EBCDIC hosts.
latin1
ISO \%8859-1.
utf8
Unicode character set in \%UTF-8 encoding.
.
The following arguments select \%gxditview as the `postprocessor' (it is rather a viewing program): .

X75
75dpi resolution, 10pt document base font.
X75-12
75dpi resolution, 12pt document base font.
X100
100dpi resolution, 10pt document base font.
X100-12
100dpi resolution, 12pt document base font.
.
The default device is @DEVICE@ . . . .OptDef U Unsafe mode. . Reverts to the (old) unsafe behaviour; see option .ShortOpt S . . . .OptDef v version Output version information of groff and of all programs that are run by it; that is, the given command line is parsed in the usual way, passing .ShortOpt v to all subprograms. . . .OptDef V Output the pipeline that would be run by groff (as a wrapper program) on the standard output, but do not execute it. If given more than once, the commands will be both printed on the standard error and run. . . .OptDef X Use \%gxditview instead of using the usual postprocessor to (pre)view a document. . The printing spooler behavior as outlined with options .ShortOpt l and .ShortOpt L is carried over to \%gxditview (@MAN1EXT@) by determining an argument for the \*[@-]printCommand option of \%gxditview (@MAN1EXT@). . This sets the default Print action and the corresponding menu entry to that value. . .ShortOpt X only produces good results with .ShortOpt Tps , .ShortOpt TX75 , .ShortOpt TX75-12 , .ShortOpt TX100 , and .ShortOpt TX100-12 . . The default resolution for previewing .ShortOpt Tps output is 75\|dpi; this can be changed by passing the .ShortOpt resolution option to \%gxditview , for example .
.ShellCommand groff \*[@-]X \*[@-]P\*[@-]resolution \*[@-]P100 \*[@-]man foo.1 . . .OptDef z Suppress output generated by @g@troff . Only error messages will be printed. . . .OptDef Z Print the groff intermediate output to standard output; see \%groff_out (@MAN5EXT@). Normally groff calls automatically a postprocessor. . With this option, the output of @g@troff for the device, the so-called intermediate output is issued without postprocessing. . . --------------------------------------------------------------------
Transparent Options
--------------------------------------------------------------------
. The following options are transparently handed over to the formatter program @g@troff that is called by groff subsequently. . These options are described in more detail in @g@troff (@MAN1EXT@). . .OptDef a ascii approximation of output. . .OptDef b backtrace on error or warning. . .OptDef c disable color output. . Please consult the \%grotty (@MAN1EXT@) man page for more details. . .OptDef C enable compatibility mode. . .OptDef d "" cs .OptDef+ d "" name=s define string. . .OptDef E disable @g@troff error messages. . .OptDef f "" fam set default font family. . .OptDef F "" dir set path for font DESC files. . .OptDef i process standard input after the specified input files. . .OptDef m "" name include macro file \f[I]name\f[]\f[B].tmac\f[] (or \f[B]tmac.\f[]\f[I]name\f[]); see also \%groff_tmac (@MAN5EXT@). . .OptDef M "" dir path for macro files. . .OptDef n "" num number the first page num . . .OptDef o "" list output only pages in list . . .OptDef r "" cn .OptDef+ r "" name=n set number register. . .OptDef w "" name enable warning name . . .OptDef W "" name disable warning name . . . --------------------------------------------------------------------
"USING GROFF"
--------------------------------------------------------------------
. The groff system implements the infrastructure of classical roff; see roff (@MAN7EXT@) for a survey on how a roff system works in general. . Due to the front-end programs available within the groff system, using groff is much easier than "classical roff" . . This section gives an overview of the parts that constitute the groff system. . It complements roff (@MAN7EXT@) with groff-specific features. . This section can be regarded as a guide to the documentation around the groff system. . . --------------------------------------------------------------------
Paper Size
--------------------------------------------------------------------
. The virtual paper size used by troff to format the input is controlled globally with the requests .po , .pl , and .ll . See groff_tmac (@MAN5EXT@) for the `papersize' macro package which provides a convenient interface. .

The physical paper size, giving the actual dimensions of the paper sheets, is controlled by output devices like grops with the command line options -p and -l . See groff_font (@MAN5EXT@) and the man pages of the output devices for more details. groff uses the command line option -P to pass options to output devices; for example, the following selects A4 paper in landscape orientation for the PS device: .

groff -Tps -P-pa4 -P-l .\|.\|.

. . --------------------------------------------------------------------
Front-ends
--------------------------------------------------------------------
. The groff program is a wrapper around the @g@troff (@MAN1EXT@) program. . It allows to specify the preprocessors by command line options and automatically runs the postprocessor that is appropriate for the selected device. . Doing so, the sometimes tedious piping mechanism of classical roff (@MAN7EXT@) can be avoided. .

The grog (@MAN1EXT@) program can be used for guessing the correct groff command line to format a file. .

The \%groffer (@MAN1EXT@) program is an allround-viewer for groff files and man pages. . . --------------------------------------------------------------------

Preprocessors
--------------------------------------------------------------------
. The groff preprocessors are reimplementations of the classical preprocessors with moderate extensions. . The preprocessors distributed with the groff package are .

@g@eqn (@MAN1EXT@) for mathematical formul\(ae,

@g@grn (@MAN1EXT@) for including gremlin (1) pictures,

@g@pic (@MAN1EXT@) for drawing diagrams,

\%@g@refer (@MAN1EXT@) for bibliographic references,

\%@g@soelim (@MAN1EXT@) for including macro files from standard locations, .

and

@g@tbl (@MAN1EXT@) for tables. .

Besides these, there are some internal preprocessors that are automatically run with some devices. . These aren't visible to the user. . . --------------------------------------------------------------------

"Macro Packages"
--------------------------------------------------------------------
. Macro packages can be included by option .ShortOpt m . . The groff system implements and extends all classical macro packages in a compatible way and adds some packages of its own. . Actually, the following macro packages come with groff : .

man The traditional man page format; see \%groff_man (@MAN7EXT@). It can be specified on the command line as .ShortOpt man or .ShortOpt m man . .

mandoc The general package for man pages; it automatically recognizes whether the documents uses the man or the mdoc format and branches to the corresponding macro package. . It can be specified on the command line as .ShortOpt mandoc or .ShortOpt m mandoc . .

mdoc The BSD-style man page format; see \%groff_mdoc (@MAN7EXT@). It can be specified on the command line as .ShortOpt mdoc or .ShortOpt m mdoc . .

me The classical me document format; see \%groff_me (@MAN7EXT@). It can be specified on the command line as .ShortOpt me or .ShortOpt m me . .

mm The classical mm document format; see \%groff_mm (@MAN7EXT@). It can be specified on the command line as .ShortOpt mm or .ShortOpt m mm . .

ms The classical ms document format; see \%groff_ms (@MAN7EXT@). It can be specified on the command line as .ShortOpt ms or .ShortOpt m ms . .

www HTML-like macros for inclusion in arbitrary groff documents; see \%groff_www (@MAN7EXT@). .

Details on the naming of macro files and their placement can be found in \%groff_tmac (@MAN5EXT@); this man page also documents some other, minor auxiliary macro packages not mentioned here. . . --------------------------------------------------------------------

"Programming Language"
--------------------------------------------------------------------
. General concepts common to all roff programming languages are described in roff (@MAN7EXT@). .

The groff extensions to the classical troff language are documented in \%groff_diff (@MAN7EXT@). .

The groff language as a whole is described in the (still incomplete) "groff info file" ; a short (but complete) reference can be found in groff (@MAN7EXT@). . . --------------------------------------------------------------------

Formatters
--------------------------------------------------------------------
. The central roff formatter within the groff system is @g@troff (@MAN1EXT@). It provides the features of both the classical troff and nroff, as well as the groff extensions. . The command line option .ShortOpt C switches @g@troff into "compatibility mode" which tries to emulate classical roff as much as possible. .

There is a shell script @g@nroff (@MAN1EXT@) that emulates the behavior of classical nroff. . It tries to automatically select the proper output encoding, according to the current locale. .

The formatter program generates "intermediate output" ; see \%groff_out (@MAN7EXT@). . . --------------------------------------------------------------------

Devices
--------------------------------------------------------------------
. In roff, the output targets are called devices . A device can be a piece of hardware, e.g. a printer, or a software file format. . A device is specified by the option .ShortOpt T . The groff devices are as follows. .

ascii Text output using the ascii (7) character set. .

cp1047 Text output using the EBCDIC code page IBM cp1047 (e.g. OS/390 Unix). .

dvi TeX DVI format. .

html HTML output. .

latin1 Text output using the ISO \%Latin-1 (ISO \%8859-1) character set; see \%iso_8859_1 (7). .

lbp Output for Canon CAPSL printers (\%LBP-4 and \%LBP-8 series laser printers). .

lj4 HP LaserJet4-compatible (or other PCL5-compatible) printers. .

ps PostScript output; suitable for printers and previewers like gv (1). .

utf8 Text output using the Unicode (ISO 10646) character set with \%UTF-8 encoding; see unicode (7). .

X75 75dpi X Window System output suitable for the previewers \%xditview (1x) and \%gxditview (@MAN1EXT@). A variant for a 12\|pt document base font is \%X75-12 . .

X100 100dpi X Window System output suitable for the previewers \%xditview (1x) and \%gxditview (@MAN1EXT@). A variant for a 12\|pt document base font is \%X100-12 . .

The postprocessor to be used for a device is specified by the postpro command in the device description file; see \%groff_font (@MAN5EXT@). . This can be overridden with the \*[@-]X option. .

The default device is @DEVICE@ . . . --------------------------------------------------------------------

Postprocessors
--------------------------------------------------------------------
. groff provides 3\~hardware postprocessors: .

\%grolbp (@MAN1EXT@) for some Canon printers,

\%grolj4 (@MAN1EXT@) for printers compatible to the HP LaserJet\~4 and PCL5,

\%grotty (@MAN1EXT@) for text output using various encodings, e.g. on text-oriented terminals or line-printers. .

Today, most printing or drawing hardware is handled by the operating system, by device drivers, or by software interfaces, usually accepting PostScript. . Consequently, there isn't an urgent need for more hardware device postprocessors. .

The groff software devices for conversion into other document file formats are .

\%grodvi (@MAN1EXT@) for the DVI format,

\%grohtml (@MAN1EXT@) for HTML format,

grops (@MAN1EXT@) for PostScript. .

Combined with the many existing free conversion tools this should be sufficient to convert a troff document into virtually any existing data format. . . --------------------------------------------------------------------

Utilities
--------------------------------------------------------------------
. The following utility programs around groff are available. .

\%addftinfo (@MAN1EXT@) Add information to troff font description files for use with groff. .

\%afmtodit (@MAN1EXT@) Create font description files for PostScript device. .

\%groffer (@MAN1EXT@) General viewer program for groff files and man pages. .

\%gxditview (@MAN1EXT@) The groff X viewer, the GNU version of xditview. .

\%hpftodit (@MAN1EXT@) Create font description files for lj4 device. .

\%indxbib (@MAN1EXT@) Make inverted index for bibliographic databases. .

lkbib (@MAN1EXT@) Search bibliographic databases. .

\%lookbib (@MAN1EXT@) Interactively search bibliographic databases. .

\%pfbtops (@MAN1EXT@) Translate a PostScript font in .pfb format to ASCII. .

\%tfmtodit (@MAN1EXT@) Create font description files for TeX DVI device. .

\%xditview (1x) roff viewer distributed with X window. . . --------------------------------------------------------------------

ENVIRONMENT
--------------------------------------------------------------------
. Normally, the path separator in the following environment variables is the colon; this may vary depending on the operating system. . For example, DOS and Windows use a semicolon instead. .

.EnvVar GROFF_BIN_PATH This search path, followed by .EnvVar $PATH , will be used for commands that are executed by groff . . If it is not set then the directory where the groff binaries were installed is prepended to .EnvVar PATH . .

.EnvVar GROFF_COMMAND_PREFIX When there is a need to run different roff implementations at the same time groff provides the facility to prepend a prefix to most of its programs that could provoke name clashings at run time (default is to have none). . Historically, this prefix was the character g , but it can be anything. . For example, gtroff stood for groff 's troff , gtbl for the groff version of tbl . . By setting .EnvVar GROFF_COMMAND_PREFIX to different values, the different roff installations can be addressed. . More exactly, if it is set to prefix xxx then groff as a wrapper program will internally call xxx troff instead of troff . This also applies to the preprocessors \%eqn , \%grn , \%pic , \%refer , \%tbl , \%soelim , and to the utilities \%@g@indxbib and \%@g@lookbib . . This feature does not apply to any programs different from the ones above (most notably groff itself) since they are unique to the groff package. . .

.EnvVar GROFF_FONT_PATH A list of directories in which to search for the dev name directory in addition to the default ones. . See @g@troff (@MAN1EXT@) and \%groff_font (@MAN5EXT@) for more details. . .

.EnvVar GROFF_TMAC_PATH A list of directories in which to search for macro files in addition to the default directories. . See @g@troff (@MAN1EXT@) and \%groff_tmac (@MAN5EXT@) for more details. . .

.EnvVar GROFF_TMPDIR The directory in which temporary files will be created. . If this is not set but the environment variable .EnvVar TMPDIR instead, temporary files will be created in the directory .EnvVar $TMPDIR . On MS-DOS and Windows 32 platforms, the environment variables .EnvVar TMP and .EnvVar TEMP (in that order) are searched also, after .EnvVar GROFF_TMPDIR and .EnvVar TMPDIR . . Otherwise, temporary files will be created in /tmp . The \%@g@refer (@MAN1EXT@), \%groffer (@MAN1EXT@), \%grohtml (@MAN1EXT@), and grops (@MAN1EXT@) commands use temporary files. . .

.EnvVar GROFF_TYPESETTER Preset the default device. . If this is not set the @DEVICE@ device is used as default. . This device name is overwritten by the option .ShortOpt T . . . --------------------------------------------------------------------

FILES
--------------------------------------------------------------------
. There are some directories in which groff installs all of its data files. . Due to different installation habits on different operating systems, their locations are not absolutely fixed, but their function is clearly defined and coincides on all systems. . . --------------------------------------------------------------------
"groff Macro Directory"
--------------------------------------------------------------------
. This contains all information related to macro packages. . Note that more than a single directory is searched for those files as documented in \%groff_tmac (@MAN5EXT@). . For the groff installation corresponding to this document, it is located at @MACRODIR@ . . The following files contained in the groff macro directory have a special meaning: . .

troffrc Initialization file for troff. . This is interpreted by @g@troff before reading the macro sets and any input. . .

troffrc-end Final startup file for troff, it is parsed after all macro sets have been read. . .

name .tmac

+ tmac. name Macro file for macro package name . . . --------------------------------------------------------------------

"groff Font Directory"
--------------------------------------------------------------------
. This contains all information related to output devices. . Note that more than a single directory is searched for those files; see @g@troff (@MAN1EXT@). . For the groff installation corresponding to this document, it is located at @FONTDIR@ . . The following files contained in the groff font directory have a special meaning: . .

dev name /DESC Device description file for device name , see \%groff_font (@MAN5EXT@). . .

dev name / F Font file for font F of device name . . . --------------------------------------------------------------------

EXAMPLES
--------------------------------------------------------------------
. The following example illustrates the power of the groff program as a wrapper around @g@troff . .

To process a roff file using the preprocessors tbl and pic and the me macro set, classical troff had to be called by .

.ShellCommand pic foo.me | tbl | troff \*[@-]me \*[@-]Tlatin1 | grotty .

Using groff , this pipe can be shortened to the equivalent command

.ShellCommand groff \*[@-]p \*[@-]t \*[@-]me \*[@-]T latin1 foo.me .

An even easier way to call this is to use grog (@MAN1EXT@) to guess the preprocessor and macro options and execute the generated command (by using backquotes to specify shell command substitution)

.ShellCommand \`grog \*[@-]Tlatin1 foo.me\` .

The simplest way is to view the contents in an automated way by calling .

.ShellCommand groffer foo.me . . --------------------------------------------------------------------

BUGS
--------------------------------------------------------------------
.

On EBCDIC hosts (e.g. OS/390 Unix), output devices ascii and latin1 aren't available. . Similarly, output for EBCDIC code page cp1047 is not available on ASCII based operating systems. .

Report bugs to bug-groff@gnu.org. . Include a complete, self-contained example that will allow the bug to be reproduced, and say which version of groff you are using. . . --------------------------------------------------------------------

AVAILABILITY
--------------------------------------------------------------------
. Information on how to get groff and related information is available at the RL http://\:www.gnu.org/\:software/\:groff "GNU website" . The most recent released version of groff is available for anonymous ftp at the RL ftp://ftp.ffii.org/\:pub/\:groff/\:devel/\:groff-current.tar.gz \ "groff development site" . .

Three groff mailing lists are available:

.MTO bug-groff@gnu.org for reporting bugs, .

.MTO groff@gnu.org for general discussion of groff, .

.MTO groff-commit@ffii.org a read-only list showing logs of commitments to the CVS repository. .

Details on CVS access and much more can be found in the file README at the top directory of the groff source package. .

There is a free implementation of the grap preprocessor, written by .MTO faber@lunabase.org " Ted Faber" . . The actual version can be found at the . RL http://\:www.lunabase.org/\:~faber/\:Vault/\:software/\:grap/ \ "grap website" . This is the only grap version supported by groff. . . --------------------------------------------------------------------

AUTHORS
--------------------------------------------------------------------
. Copyright \(co 1989, 2002, 2003, 2004, 2005 Free Software Foundation, Inc. .

This document is distributed under the terms of the FDL (GNU Free Documentation License) version 1.1 or later. . You should have received a copy of the FDL on your system, it is also available on-line at the RL http://\:www.gnu.org/\:copyleft/\:fdl.html "GNU copyleft site" . .

This document is based on the original groff man page written by .MTO jjc@jclark.com "James Clark" . . It was rewritten, enhanced, and put under the FDL license by \m[blue]Bernd Warken\m[]. . It is maintained by .MTO wl@gnu.org "Werner Lemberg" . .

groff is a GNU free software project. . All parts of the groff package are protected by GNU copyleft licenses. . The software files are distributed under the terms of the GNU General Public License (GPL), while the documentation files mostly use the GNU Free Documentation License (FDL). . . --------------------------------------------------------------------

"SEE ALSO"
--------------------------------------------------------------------
. The "groff info file" contains all information on the groff system within a single document. . Beneath the detailed documentation of all aspects, it provides examples and background information. . See info (1) on how to read it. .

Due to its complex structure, the groff system has many man pages. . They can be read with man (1) or \%groffer (@MAN1EXT@). .

Introduction, history and further readings: roff (@MAN7EXT@). .

Viewer for groff files: \%groffer (@MAN1EXT@), \%gxditview (@MAN1EXT@), \%xditview (1x). .

Wrapper programs for formatters: \%groff (@MAN1EXT@), \%grog (@MAN1EXT@). .

Roff preprocessors: \%@g@eqn (@MAN1EXT@), \%@g@grn (@MAN1EXT@), \%@g@pic (@MAN1EXT@), \%@g@refer (@MAN1EXT@), \%@g@soelim (@MAN1EXT@), \%@g@tbl (@MAN1EXT@), grap (1). .

Roff language with the groff extensions: \%groff (@MAN7EXT@), \%groff_char (@MAN7EXT@), \%groff_diff (@MAN7EXT@), \%groff_font (@MAN5EXT@). .

Roff formatter programs: \%@g@nroff (@MAN1EXT@), \%@g@troff (@MAN1EXT@), ditroff (@MAN7EXT@). .

The intermediate output language: \%groff_out (@MAN7EXT@). .

Postprocessors for the output devices: \%grodvi (@MAN1EXT@), \%grohtml (@MAN1EXT@), \%grolbp (@MAN1EXT@), \%grolj4 (@MAN1EXT@), \%lj4_font (@MAN5EXT@), \%grops (@MAN1EXT@), \%grotty (@MAN1EXT@). .

Groff macro packages and macro-specific utilities: \%groff_tmac (@MAN5EXT@), \%groff_man (@MAN7EXT@), \%groff_mdoc (@MAN7EXT@), \%groff_me (@MAN7EXT@), \%groff_mm (@MAN7EXT@), \%groff_mmse (@MAN7EXT@), \%groff_mom (@MAN7EXT@), \%groff_ms (@MAN7EXT@), \%groff_www (@MAN7EXT@), \%groff_trace (@MAN7EXT@), \%mmroff (@MAN7EXT@). .

The following utilities are available: \%addftinfo (@MAN1EXT@), \%afmtodit (@MAN1EXT@), \%eqn2graph (@MAN1EXT@), \%grap2graph (@MAN1EXT@), \%groffer (@MAN1EXT@), \%gxditview (@MAN1EXT@), \%hpftodit (@MAN1EXT@), \%@g@indxbib (@MAN1EXT@), \%@g@lookbib (@MAN1EXT@), \%pfbtops (@MAN1EXT@), \%pic2graph (@MAN1EXT@), \%tfmtodit (@MAN1EXT@). . .cp \n[groff_C] . --------------------------------------------------------------------
Emacs setup
--------------------------------------------------------------------
. Local Variables:
mode: nroff
End: