From 4530aecd628b64d5172a6a964e753f9442ac55a6 Mon Sep 17 00:00:00 2001 From: Ruslan Ermilov Date: Fri, 11 Oct 2002 08:54:44 +0000 Subject: Merge Groff 1.18.1 changes. --- contrib/groff/src/roff/groff/groff.man | 1899 +++++++++++++++++++++++++------- 1 file changed, 1498 insertions(+), 401 deletions(-) (limited to 'contrib/groff/src/roff/groff/groff.man') diff --git a/contrib/groff/src/roff/groff/groff.man b/contrib/groff/src/roff/groff/groff.man index f64044e7fd13..f2fc6ad6f06b 100644 --- a/contrib/groff/src/roff/groff/groff.man +++ b/contrib/groff/src/roff/groff/groff.man @@ -1,495 +1,1592 @@ .ig -Copyright (C) 1989-2000, 2001 Free Software Foundation, Inc. +groff.man -Permission is granted to make and distribute verbatim copies of -this manual provided the copyright notice and this permission notice -are preserved on all copies. +Last update: 14 July 2002 -Permission is granted to copy and distribute modified versions of this -manual under the conditions for verbatim copying, provided that the -entire resulting derived work is distributed under the terms of a -permission notice identical to this one. +Copyright (C) 1989, 2002 Free Software Foundation, Inc. +Rewritten in 2002 by Bernd Warken -Permission is granted to copy and distribute translations of this -manual into another language, under the above conditions for modified -versions, except that this permission notice may be included in -translations approved by the Free Software Foundation instead of in -the original English. +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. - $FreeBSD$ +A copy of the Free Documentation License is included as a file called +FDL in the main directory of the groff source package. +$FreeBSD$ + +.. +. +.\" -------------------------------------------------------------------- +.\" Setup +.\" -------------------------------------------------------------------- +. +.mso www.tmac +. +.\" set adjust to both +.ad b +. +.\" fonts of fixed length +. +.if n \{\ +. mso tty-char.tmac +. ftr CR R +. ftr CI I +. ftr CB B +.\} +. +.if '\*[.T]'dvi' \ +. ftr CB CW +. +.\" -------------------------------------------------------------------- +.\" String definitions +. +.ds @- "\-\" +.ds @-- "\-\^\-\" +. +.ds Ellipsis .\|.\|.\" +. +. +.\" -------------------------------------------------------------------- +.\" Begin of macro definitions +.de c +.\" this is like a comment request when escape mechanism is off .. -.de TQ +.eo +. +.c -------------------------------------------------------------------- +.de TP+ .br .ns -.TP \\$1 +.TP \$1 .. -.\" Like TP, but if specified indent is more than half -.\" the current line-length - indent, use the default indent. +.c -------------------------------------------------------------------- +.c Like TP, but if specified indent is more than half +.c the current line-length - indent, use the default indent. .de Tp -.ie \\n(.$=0:((0\\$1)*2u>(\\n(.lu-\\n(.iu)) .TP -.el .TP "\\$1" +. ie \n[.$]=0:((0\$1)*2u>(\n.lu-\n(.iu)) .TP +. el .TP "\$1" +.. +.c -------------------------------------------------------------------- +.de Text +. nop \)\$* +.. +.c -------------------------------------------------------------------- +.de Synopsis +. 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 -------------------------------------------------------------------- +.de EndSynopsis +. ad +. in +.. +.c -------------------------------------------------------------------- +.c ShortOpt[] (name [arg]) +.c +.c short option in synopsis +.c +.de ShortOpt[] +. 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) +.de SynOpt +. 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' somwhere in the text +.c second arg is punctuation +.c +.de ShortOpt +. ds @opt \$1\" +. shift +. Text \f[CB]\*[@-]\*[@opt]\f[]\/\$* +. rm @opt .. +.c -------------------------------------------------------------------- +.c LongOpt ([name [punct]]) +.c +.c `--name' somwhere in the text +.c second arg is punctuation +.c +.de LongOpt +. 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 +.de OptDef +. 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. +.de OptDef+ +. br +. ns +. OptDef \$@ +.. +.c -------------------------------------------------------------------- +.c Environment variable +.de EnvVar +. SM +. BR \$1 \$2 +.. +.c -------------------------------------------------------------------- +.c a shell command line +.de ShellCommand +. 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' +.de Quoted +. ft CR +. Text \[oq]\$*\[cq] +. ft +.. +.c -------------------------------------------------------------------- +.c End of macro definitions +.ec +. +. +.\" -------------------------------------------------------------------- +.\" Title +.\" -------------------------------------------------------------------- +. .TH GROFF @MAN1EXT@ "@MDATE@" "Groff Version @VERSION@" .SH NAME -groff \- front end for the groff document formatting system +groff \- front-end for the groff document formatting system +. +. +.\" -------------------------------------------------------------------- .SH SYNOPSIS -.nr a \n(.j +.\" -------------------------------------------------------------------- +. .ad l -.nr i \n(.i -.in +\w'\fBgroff 'u -.ti \niu -.B groff -.de OP -.ie \\n(.$-1 .RI "[\ \fB\\$1\fP" "\\$2" "\ ]" -.el .RB "[\ " "\\$1" "\ ]" -.. -.OP \-abeghilpstvzCEGNRSUVXZ -.OP \-w name -.OP \-W name -.OP \-m name -.OP \-F dir -.OP \-I dir -.OP \-T dev -.OP \-f fam -.OP \-M dir -.OP \-d cs -.OP \-r cn -.OP \-n num -.OP \-o list -.OP \-P arg -.OP \-L arg -.RI "[\ " files\|.\|.\|. "\ ]" -.br -.ad \na -.PP -It is possible to have whitespace between a command line option and its -parameter. +.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 +.RI [ file +.Text \*[Ellipsis]] +.EndSynopsis +. +.Synopsis groff +.ShortOpt h +| +.LongOpt help +.EndSynopsis +. +.Synopsis groff +.ShortOpt v +| +.LongOpt version +.RI [ option +.Text \*[Ellipsis]] +.EndSynopsis +. +.P +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. +. +. +.\" -------------------------------------------------------------------- .SH DESCRIPTION +.\" -------------------------------------------------------------------- +. +This document describes the +.B groff +program, the main front-end for the +.I groff +document formatting system. +. +The +.I groff +program and macro suite is the implementation of a +.BR roff (@MAN7EXT@) +system within the free software collection +.URL http://\:www.gnu.org "GNU" . +. +The +.I groff +system has all features of the classical +.IR roff , +but adds many extensions. +. +.P +The +.B groff +program allows to control the whole +.I groff +system by comand line options. +. +This is a great simplification in comparison to the classical case (which +uses pipes only). +. +. +.\" -------------------------------------------------------------------- +.SH OPTIONS +.\" -------------------------------------------------------------------- +. +As +.B groff +is a wrapper program for +.B @g@troff +both programs share a set of options. +. +But the +.B groff +program has some additional, native options and gives a new meaning to +some +.B @g@troff +options. +. +On the other hand, not all +.B @g@troff +options can be fed into +.BR groff . +. +. +.\" -------------------------------------------------------------------- +.SS Native groff Options +.\" -------------------------------------------------------------------- +. +The following options either do not exist for +.B @g@troff +or are differently interpreted by +.BR groff . +. +. +.OptDef e +Preprocess with +.BR @g@eqn . +. +. +.OptDef g +Preprocess with +.BR @g@grn . +. +. +.OptDef G +Preprocess with +.BR grap . +. +. +.OptDef h help +Print a help message. +. +. +.OptDef I "" dir +Add search directory for +.BR \%@g@soelim (@MAN1EXT@). +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 +.B print +command in the device description file, see +.BR \%groff_font (@MAN5EXT@). +If this command is not present, the output is piped into the +.BR lpr (1) +program by default. +. +See options +.ShortOpt L +and +.ShortOpt X . +. +. +.OptDef L "" arg +Pass +.I arg +to the spooler program. +Several arguments should be passed with a separate +.ShortOpt L +option each. +. +Note that +.B groff +does not prepend +.ShortOpt\" just a minus sign +(a minus sign) to +.I arg +before passing it to the spooler program. +. +. +.OptDef N +Don't allow newlines within +.I eqn +delimiters. +. +This is the same as the +.ShortOpt N +option in +.BR @g@eqn . +. +. +.OptDef p +Preprocess with +.BR @g@pic . +. +. +.OptDef P "" "-option" +.OptDef+ P "" "-option \f[CB]-P\f[] arg" +Pass +.I -option +or +.I -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 +.IP +.ShellCommand groff -X -P -title -P 'groff it' \f[I]foo\f[] +.IP +is equivalent to +.IP +.ShellCommand groff -X -Z \f[I]foo\f[] | gxditview -title 'groff it' - +. +. +.OptDef R +Preprocess with +.BR @g@refer . +. +No mechanism is provided for passing arguments to +.B @g@refer +because most +.B @g@refer +options have equivalent language elements that can be specified within +the document. +. +See +.BR \%@g@refer (@MAN1EXT@) +for more details. +. +. +.OptDef s +Preprocess with +.BR @g@soelim . +. +. +.OptDef S +Safer mode. +. +Pass the +.ShortOpt S +option to +.B @g@pic +and disable the following +.B @g@troff +requests: +.BR .open , +.BR .opena , +.BR .pso , +.BR .sy , +and +.BR .pi . +For security reasons, safer mode is enabled by default. +. +. +.OptDef t +Preprocess with +.BR @g@tbl . +. +. +.OptDef T "" dev +Set output device to +.IR dev . +The possible values in +.I groff +are +.BR ascii , +.BR cp1047 , +.BR dvi , +.BR html , +.BR latin1 , +.BR lbp , +.BR lj4 , +.BR ps , +.BR utf8 , +.BR X75 , +and +.BR X100 . +. +Additionally, +.B X75-12 +and +.B X100-12 +are available for documents which use 12\|pt as the base document size. +. +The default device is +.BR @DEVICE@ . +. +. +.OptDef U +Unsafe mode. +. +Reverts to the (old) unsafe behaviour; see option +.ShortOpt S . +. +. +.OptDef v version +Output version information of .B groff -is a front-end to the groff document formatting system. -Normally it runs the +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 +.BR groff +(as a wrapper program), but do not execute it. +. +. +.OptDef X +Use +.B 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 +.BR \%gxditview (@MAN1EXT@) +by determining an argument for the +.B -printCommand +option of +.BR \%gxditview (@MAN1EXT@). +. +This sets the default +.B 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 +.BR gxditview , +for example +. +.IP +.ShellCommand groff -X -P-resolution -P100 -man foo.1 +. +. +.OptDef z +Suppress output generated by +.BR @g@troff . +Only error messages will be printed. +. +. +.OptDef Z +Do not postprocess the output of +.B @g@troff +that is normally +called automatically by +.BR groff . +This will print the intermediate output to standard output; see +.BR \%groff_out (@MAN5EXT@). +. +. +.\" -------------------------------------------------------------------- +.SS Tranparent Options +.\" -------------------------------------------------------------------- +. +The following options are transparently handed over to the formatter +program +.B @g@troff +that is called by groff subsequently. +. +These options are described in more detail in +.BR @g@troff (@MAN1EXT@). +. +.OptDef a +ascii approximation of output. +. +.OptDef b +backtrace on error or warning. +. +.OptDef c +disable color output. +. +.OptDef C +enable compatibility mode. +. +.OptDef d "" cs +.OptDef+ d "" name=s +define string. +. +.OptDef E +disable .B @g@troff -program and a postprocessor appropriate for the selected -device. -Available devices are: +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 +.BR \%groff_tmac (@MAN5EXT@). +. +.OptDef M "" dir +path for macro files. +. +.OptDef n "" num +number the first page +.IR num . +. +.OptDef o "" list +output only pages in +.IR list . +. +.OptDef r "" cn +.OptDef+ r "" name=n +set number register. +. +.OptDef w "" name +enable warning +.IR name . +. +.OptDef W "" name +disable warning +.IR name . +. +. +.\" -------------------------------------------------------------------- +.SH "USING GROFF" +.\" -------------------------------------------------------------------- +. +The +.I groff system +implements the infrastructure of classical roff; see +.BR 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 +.I groff +is much easier than +.IR "classical roff" . +. +This section gives an overview of the parts that consitute the groff +system. +. +It complements +.BR roff (@MAN7EXT@) +with groff-specific features. +. +This section can be regarded as a guide to the documentation around +the groff system. +. +. +.\" -------------------------------------------------------------------- +.SS Front-ends +.\" -------------------------------------------------------------------- +. +The +.B groff +program is a wrapper around the +.BR @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 +.BR roff (@MAN7EXT@) +can be avoided. +. +.P +The +.BR grog (@MAN1EXT@) +program can be used for guessing the correct groff command line to +format a file. +. +.P +The +.BR \%groffer (@MAN1EXT@) +program is an allround-viewer for groff files and man pages. +. +. +.\" -------------------------------------------------------------------- +.SS Preprocessors +.\" -------------------------------------------------------------------- +. +The groff preprocessors are reimplementations of the classical +preprocessors with moderate extensions. +. +The preprocessors distributed with the +.I groff +package are +. .TP -.B ps -For PostScript printers and previewers +.BR @g@eqn (@MAN1EXT@) +for mathematical formul\(ae, .TP -.B dvi -For TeX dvi format. +.BR @g@grn (@MAN1EXT@) +for including +.BR gremlin (1) +pictures, .TP -.B X75 -For a 75dpi X11 previewer. +.BR @g@pic (@MAN1EXT@) +for drawing diagrams, .TP -.B X100 -For a 100dpi X11 previewer. +.BR \%@g@refer (@MAN1EXT@) +for bibliographic references, +.TP +.BR \%@g@soelim (@MAN1EXT@) +for including macro files from standard locations, +. +.P +and +.TP +.BR @g@tbl (@MAN1EXT@) +for tables. +. +.P +Besides these, there are some internal preprocessors that are +automatically run with some devices. +. +These aren't visible to the user. +. +. +.\" -------------------------------------------------------------------- +.SS "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 +.IR groff : +. +.TP +.B man +The traditional man page format; see +.BR \%groff_man (@MAN7EXT@). +It can be specified on the command line as +.ShortOpt man +or +.ShortOpt m +.BR man . +. +.TP +.B mandoc +The general package for man pages; it automatically recognizes +whether the documents uses the +.I man +or the +.I mdoc +format and branches to the corresponding macro package. +. +It can be specified on the command line as +.ShortOpt mandoc +or +.ShortOpt m +.BR mandoc . +. +.TP +.B mdoc +The BSD-style man page format; see +.BR \%groff_mdoc (@MAN7EXT@). +It can be specified on the command line as +.ShortOpt mdoc +or +.ShortOpt m +.BR mdoc . +. +.TP +.B me +The classical +.I me +document format; see +.BR \%groff_me (@MAN7EXT@). +It can be specified on the command line as +.ShortOpt me +or +.ShortOpt m +.BR me . +. +.TP +.B mm +The classical +.I mm +document format; see +.BR \%groff_mm (@MAN7EXT@). +It can be specified on the command line as +.ShortOpt mm +or +.ShortOpt m +.BR mm . +. +.TP +.B ms +The classical +.I ms +document format; see +.BR \%groff_ms (@MAN7EXT@). +It can be specified on the command line as +.ShortOpt ms +or +.ShortOpt m +.BR ms . +. +.TP +.B www +HTML-like macros for inclusion in arbitrary groff documents; see +.BR \%groff_www (@MAN7EXT@). +. +.P +Details on the naming of macro files and their placement can be found +in +.BR \%groff_tmac (@MAN5EXT@). +. +. +.\" -------------------------------------------------------------------- +.SS "Programming Language" +.\" -------------------------------------------------------------------- +. +General concepts common to all roff programming languages are +described in +.BR roff (@MAN7EXT@). +. +.P +The groff extensions to the classical troff language are documented in +.BR \%groff_diff (@MAN7EXT@). +. +.P +The groff language as a whole is described in the (still incomplete) +.IR "groff info file" ; +a short (but complete) reference can be found in +.BR groff (@MAN7EXT@). +. +. +.\" -------------------------------------------------------------------- +.SS Formatters +.\" -------------------------------------------------------------------- +. +The central roff formatter within the groff system is +.BR @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 +.B @g@troff +into +.I "compatibility mode" +which tries to emulate classical roff as much as possible. +. +.P +There is a shell script +.BR @g@nroff (@MAN1EXT@) +that emulates the behavior of classical nroff. +. +It tries to automatically select the proper output encoding, according to +the current locale. +. +.P +The formatter program generates +.IR "intermediate output" ; +see +.BR \%groff_out (@MAN7EXT@). +. +. +.\" -------------------------------------------------------------------- +.SS Devices +.\" -------------------------------------------------------------------- +. +In roff, the output targets are called +.IR 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. +. .TP .B ascii -For typewriter-like devices. +Text output using the +.BR ascii (7) +character set. +. +.TP +.B cp1047 +Text output using the EBCDIC code page IBM cp1047 (e.g. OS/390 Unix). +. +.TP +.B dvi +TeX DVI format. +. +.TP +.B html +HTML output. +. .TP .B latin1 -For typewriter-like devices using the ISO Latin-1 (ISO 8859-1) character set. +Text output using the ISO Latin-1 (ISO 8859-1) character set; see +.BR iso_8859_1 (7). +. .TP .B koi8-r -For typewriter-like devices using the Russian KOI8-R character set. -.TP -.B utf8 -For typewriter-like devices using the Unicode (ISO 10646) character set with -UTF-8 encoding. +Text output using the Russian KOI8-R character set. +. .TP -.B cp1047 -For typewriter-like devices which use the EBCDIC code page IBM cp1047 -(e.g. OS/390 Unix). +.B lbp +Output for Canon CAPSL printers (LBP-4 and LBP-8 series laser printers). +. .TP .B lj4 -For an HP LaserJet4-compatible (or other PCL5-compatible) printer. +HP LaserJet4-compatible (or other PCL5-compatible) printers. +. .TP -.B lbp -For Canon CAPSL printers (LBP-4 and LBP-8 series laser printers). +.B ps +PostScript output; suitable for printers and previewers like +.BR gv (1). +. +.TP +.B utf8 +Text output using the Unicode (ISO 10646) character set with UTF-8 +encoding; see +.BR unicode (7). +. +.TP +.B X75 +75dpi X Window System output suitable for the previewers +.BR xditview (1x) +and +.BR \%gxditview (@MAN1EXT@). +A variant for a 12\|pt document base font is +.BR X75-12 . +. .TP -.B html -To produce HTML output. -.LP +.B X100 +100dpi X Window System output suitable for the previewers +.BR xditview (1x) +and +.BR \%gxditview (@MAN1EXT@). +A variant for a 12\|pt document base font is +.BR X100-12 . +. +.P The postprocessor to be used for a device is specified by the .B postpro -command in the device description file. +command in the device description file; see +.BR \%groff_font (@MAN5EXT@). +. This can be overridden with the .B \-X option. -.LP +. +.P The default device is .BR @DEVICE@ . -It can optionally preprocess with any of -.BR @g@pic , -.BR @g@eqn , -.BR @g@grn , -.BR grap , -.BR @g@tbl , -.BR @g@refer , -or -.B @g@soelim. -.LP -Options without an argument can be grouped behind a single -.BR \- . -A filename of -.B \- -denotes the standard input. -.LP -The -.B grog -command can be used to guess the correct groff command to use to -format a file. -.SH OPTIONS -.TP -.B \-h -Print a help message. -.TP -.B \-e -Preprocess with @g@eqn. -.TP -.B \-t -Preprocess with @g@tbl. +. +. +.\" -------------------------------------------------------------------- +.SS Postprocessors +.\" -------------------------------------------------------------------- +. +groff provides 3\~hardware postprocessors: +. .TP -.B \-g -Preprocess with @g@grn. +.BR \%grolbp (@MAN1EXT@) +for some Canon printers, .TP -.B \-G -Preprocess with grap. +.BR \%grolj4 (@MAN1EXT@) +for printers compatible to the HP LaserJet\~4 and PCL5, .TP -.B \-p -Preprocess with @g@pic. +.BR \%grotty (@MAN1EXT@) +for text output using various encodings, e.g. on text-oriented +terminals or line-printers. +. +.P +Today, most printing or drawing hardware is handled by the operating +system, by device drivers, or by software interfaces, usally accepting +PostScript. +. +Consequently, there isn't an urgent need for more hardware device +postprocessors. +. +.P +The groff software devices for conversion into other document file +formats are +. .TP -.B \-s -Preprocess with @g@soelim. +.BR \%grodvi (@MAN1EXT@) +for the DVI format, .TP -.BI \-I dir -This option is as described in -.BR @g@soelim (@MAN1EXT@). -This option implies the -.B \-s -option. +.BR \%grohtml (@MAN1EXT@) +for HTML format, .TP -.B \-R -Preprocess with @g@refer. -No mechanism is provided for passing arguments to -.B @g@refer -because most @g@refer options have equivalent commands -which can be included in the file. -See -.BR @g@refer (@MAN1EXT@) -for more details. +.BR grops (@MAN1EXT@) +for PostScript. +. +.P +Combined with the many existing free conversion tools this should +be sufficient to convert a troff document into virtually any existing +data format. +. +. +.\" -------------------------------------------------------------------- +.SS Utilities +.\" -------------------------------------------------------------------- +. +The following utility programs around groff are available. +. .TP -.B \-v -Make programs run by -.B groff -print out their version number. +.BR \%addftinfo (@MAN1EXT@) +Add information to troff font description files for use with groff. +. .TP -.B \-V -Print the pipeline on stdout instead of executing it. +.BR \%afmtodit (@MAN1EXT@) +Create font description files for PostScript device. +. .TP -.B \-z -Suppress output from -.BR @g@troff . -Only error messages will be printed. +.BR \%groffer (@MAN1EXT@) +General viewer program for groff files and man pages. +. .TP -.B \-Z -Do not postprocess the output of -.BR @g@troff . -Normally -.B groff -will automatically run the appropriate postprocessor. +.BR \%gxditview (@MAN1EXT@) +The groff X viewer, the GNU version of xditview. +. .TP -.BI \-P arg -Pass -.I arg -to the postprocessor. -Each argument should be passed with a separate -.B \-P -option. -Note that -.B groff -does not prepend -.B \- -to -.I arg -before passing it to the postprocessor. +.BR \%hpftodit (@MAN1EXT@) +Create font description files for lj4 device. +. .TP -.B \-l -Send the output to a spooler for printing. -The command used for this is specified by the -.B print -command in the device description file (if not present, -.B \-l -has no effect). +.BR \%indxbib (@MAN1EXT@) +Make inverted index for bibliographic databases. +. .TP -.BI \-L arg -Pass -.I arg -to the spooler. -Each argument should be passed with a separate -.B \-L -option. -Note that -.B groff -does not prepend -.B \- -to -.I arg -before passing it to the postprocessor. -If there is no -.B print -command in the device description file, -.B \-L -is ignored. +.BR lkbib (@MAN1EXT@) +Search bibliographic databases. +. .TP -.BI \-T dev -Prepare output for device -.IR dev . -The default device is -.BR @DEVICE@ . +.BR \%lookbib (@MAN1EXT@) +Interactively search bibliographic databases. +. .TP -.B \-X -Preview with -.B gxditview -instead of using the usual postprocessor. -.B Groff -passes -.B gxditview -a -.B -printCommand -option which will make the -.B Print -action do what -.B groff -would have done if the -.B -l -option had been given. -This is unlikely to produce good results except with -.BR \-Tps . -.TP -.B \-N -Don't allow newlines with eqn delimiters. -This is the same as the -.B \-N -option in -.BR @g@eqn . +.BR \%pfbtops (@MAN1EXT@) +Translate a PostScript font in .pfb format to ASCII. +. .TP -.B \-S -Safer mode. Pass the -.B \-S -option to -.B @g@pic -and disable the following -.B @g@troff -requests: -.BR .open , -.BR .opena , -.BR .pso , -.BR .sy , -and -.BR .pi . -For security reasons, safer mode is enabled by default. +.BR \%tfmtodit (@MAN1EXT@) +Create font description files for TeX DVI device. +. .TP -.B \-U -Unsafe mode. Reverts to the old unsafe behaviour. -.TP -.B \-a -.TQ -.B \-b -.TQ -.B \-i -.TQ -.B \-C -.TQ -.B \-E -.TQ -.BI \-w name -.TQ -.BI \-W name -.TQ -.BI \-m name -.TQ -.BI \-o list -.TQ -.BI \-d cs -.TQ -.BI \-r cn -.TQ -.BI \-F dir -.TQ -.BI \-M dir -.TQ -.BI \-f fam -.TQ -.BI \-n num -These are as described in -.BR @g@troff (@MAN1EXT@) . +.BR \%xditview (1x) +roff viewer distributed with X window. +. +. +.\" -------------------------------------------------------------------- .SH 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. +. +.TP +.EnvVar GROFF_BIN_PATH +This search path, followed by +.EnvVar $PATH , +will be used for commands that are executed by +.BR groff . +. +If it is not set then the directory where the groff binaries were +installed is prepended to +.EnvVar PATH . +. .TP -.SM -.B GROFF_COMMAND_PREFIX -If this is set -.IR X , +.EnvVar GROFF_COMMAND_PREFIX +When there is a need to run different roff implementations at the same +time +.I 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 +.BR g , +but it can be anything. +. +For example, +.BR gtroff +stood for +.IR groff 's +.BR troff , +.BR gtbl +for the +.I groff +version of +.BR 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 +.I xxx then .B groff -will run -.IB X troff +as a wrapper program will internally call +.IB xxx troff instead of -.BR @g@troff . -This also applies to -.BR tbl , -.BR pic , -.BR eqn , -.BR grn , -.BR refer , +.BR troff . +This also applies to the preprocessors +.BR \%eqn , +.BR \%grn , +.BR \%pic , +.BR \%refer , +.BR \%tbl , +.BR \%soelim , +and to the utilities +.B \%@g@indxbib and -.BR soelim . -It does not apply to -.BR grap , -.BR grops , -.BR grodvi , -.BR grotty , -.BR grolj4 , -.BR grohtml , -and -.BR gxditview . +.BR \%@g@lookbib . +. +This feature does not apply to any programs different from the ones +above (most notably +.B groff +itself) since they are unique to the groff package. +. +. .TP -.SM -.B GROFF_TMAC_PATH -A colon separated list of directories in which to search for -macro files in addition to the default directories. +.EnvVar GROFF_FONT_PATH +A list of directories in which to search for the +.BI dev name +directory in addition to the default ones. +. See -.BR troff (1) +.BR @g@troff (@MAN1EXT@) +and +.BR \%groff_font (@MAN5EXT@) for more details. +. +. .TP -.SM -.B GROFF_TYPESETTER -Default device. -.TP -.SM -.B GROFF_FONT_PATH -A colon separated list of directories in which to search for the -.BI dev name -directory in addition to the default one. +.EnvVar GROFF_TMAC_PATH +A list of directories in which to search for macro files in addition to +the default directories. +. See -.BR troff (1) +.BR @g@troff (@MAN1EXT@) +and +.BR \%groff_tmac (@MAN5EXT@) for more details. +. +. .TP -.SM -.B GROFF_BIN_PATH -This search path, followed by -.BR PATH , -will be used for commands executed by -.BR groff . -If not set, `@BINDIR@' is prepended to -.BR PATH . -.TP -.SM -.B GROFF_TMPDIR +.EnvVar GROFF_TMPDIR The directory in which temporary files will be created. -If this is not set and -.B -.SM TMPDIR -is set, temporary files will be created in that directory. +. +If this is not set but the environment variable +.EnvVar TMPDIR +instead, temporary files will be created in the directory +.EnvVar $TMPDIR . +. Otherwise temporary files will be created in .BR /tmp . The -.BR grops (@MAN1EXT@) +.BR \%@g@refer (@MAN1EXT@), +.BR \%groffer (@MAN1EXT@), +.BR \%grohtml (@MAN1EXT@), and -.BR @g@refer (@MAN1EXT@) -commands can create temporary files. +.BR grops (@MAN1EXT@) +commands use temporary files. +. +. +.TP +.EnvVar GROFF_TYPESETTER +Preset the default device. +. +If this is not set the +.B @DEVICE@ +device is used as default. +. +This device name is overwritten by the option +.ShortOpt T . +. +. +.\" -------------------------------------------------------------------- .SH FILES -.Tp \w'\fB@FONTDIR@/dev\fIname\fB/DESC'u+3n -.BI @FONTDIR@/dev name /DESC -Device description file for device +.\" -------------------------------------------------------------------- +. +There are some directories in which +.I 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. +. +. +.\" -------------------------------------------------------------------- +.SS "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 +.BR \%groff_tmac (@MAN5EXT@). +. +For the groff installation corresponding to this document, it is +located at +.IR @MACRODIR@ . +. +The following files contained in the +.I groff macro directory +have a special meaning: +. +. +.TP +.B troffrc +Initialization file for troff. +. +This is interpreted by +.B @g@troff +before reading the macro sets and any input. +. +. +.TP +.B troffrc-end +Final startup file for troff, it is parsed after all macro sets have +been read. +. +. +.TP +.IB name .tmac +.TP+ +.BI tmac. name +Macro file for macro package .IR name . +. +. +.\" -------------------------------------------------------------------- +.SS "groff Font Directory" +.\" -------------------------------------------------------------------- +. +This contains all information related to output devices. +. +Note that more than a single directory is searched for those files; see +.BR @g@troff (@MAN1EXT@). +. +For the groff installation corresponding to this document, it is +located at +.IR @FONTDIR@ . +. +The following files contained in the +.I groff font directory +have a special meaning: +. +. +.TP +.BI dev name /DESC +Device description file for device +.IR name , +see +.BR \%groff_font (@MAN5EXT@). +. +. .TP -.BI @FONTDIR@/dev name / F +.BI dev name / F Font file for font .I F of device .IR name . -.LP -Note that on EBCDIC hosts, output devices -.BR ascii , -.BR latin1 , +. +. +.\" -------------------------------------------------------------------- +.SH EXAMPLES +.\" -------------------------------------------------------------------- +. +The following example illustrates the power of the +.B groff +program as a wrapper around +.BR @g@troff . +. +.P +To process a roff file using the preprocessors +.B tbl and -.B utf8 +.B pic +and the +.B me +macro set, classical troff had to be called by +. +.P +.ShellCommand pic foo.me | tbl | troff -me -Tlatin1 | grotty +. +.P +Using +.BR groff , +this pipe can be shortened to the equivalent command +.P +.ShellCommand groff -p -t -me -T latin1 foo.me +. +.P +An even easier way to call this is to use +.BR grog (@MAN1EXT@) +to guess the preprocessor and macro options and execute the generated +command (by specifying shell left quotes) +.P +.ShellCommand `grog -Tlatin1 foo.me` +. +.P +The simplest way is to view the contents in an automated way by +calling +. +.P +.ShellCommand groffer foo.me +. +. +.\" -------------------------------------------------------------------- +.SH BUGS +.\" -------------------------------------------------------------------- +. +.P +On EBCDIC hosts (e.g. OS/390 Unix), output devices +.B ascii +and +.B latin1 aren't available. -Similarly, +. +Similarly, output for EBCDIC code page .B cp1047 is not available on ASCII based operating systems. -.SH EXAMPLE -To print the man page -.B foo.1 -to the standard output using the latin-1 output device and -.B less -as the pager, the following command can be used: -.IP -.B groff -mandoc -Tlatin1 foo.1 | less -.PP -Alternatively, you can say -.IP -.B groff -m mandoc -Tlatin1 foo.1 | less -.SH AUTHOR -James Clark -.SH BUGS +. +.P 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. -.SH COPYRIGHT -Copyright \(co 1989-2000 Free Software Foundation, Inc. -.LP -groff is free software; you can redistribute it and/or modify it under -the terms of the GNU General Public License as published by the Free -Software Foundation; either version 2, or (at your option) any later -version. -.LP -groff is distributed in the hope that it will be useful, but WITHOUT ANY -WARRANTY; without even the implied warranty of MERCHANTABILITY or -FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License -for more details. -.LP -You should have received a copy of the GNU General Public License along -with groff; see the file COPYING. If not, write to the Free Software -Foundation, 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. +. +Include a complete, self-contained example that will allow the bug to +be reproduced, and say which version of groff you are using. +. +. +.\" -------------------------------------------------------------------- .SH AVAILABILITY -The most recent released version of groff is always available for -anonymous ftp from ftp.gnu.org in the directory gnu/groff. -.LP -.B groff -only supports the freely available +.\" -------------------------------------------------------------------- +. +Information on how to get groff and related information is available +at the +.URL http://\:www.gnu.org/\:software/\:groff "GNU website" . +The most recent released version of groff is available for anonymous +ftp at the +.URL ftp://ftp.ffii.org/\:pub/\:groff/\:devel/\:groff-current.tar.gz \ + "groff development site" . +. +.P +Three groff mailing lists are available: +.TP +.MTO bug-groff@gnu.org +for reporting bugs, +. +.TP +.MTO groff@gnu.org +for general discussion of groff, +. +.TP +.MTO groff-commit@ffii.org +a read-only list showing logs of commitments to the CVS repository. +. +.P +Details on CVS access and much more can be found in the file +.B README +at the top directory of the groff source package. +. +.P +There is a free implementation of the .B grap -implementation written by Ted Faber . -The actual version can be found at -.IP -\%http://www.lunabase.org/~faber/Vault/software/grap/ +preprocessor, written by +.MTO faber@lunabase.org " Ted Faber" . +. +The actual version can be found at the +. +.URL http://\:www.lunabase.org/\:~faber/\:Vault/\:software/\:grap/ \ + "grap website" . +This is the only grap version supported by groff. +. +. +.\" -------------------------------------------------------------------- +.SH AUTHORS +.\" -------------------------------------------------------------------- +. +Copyright \(co 1989, 2002 Free Software Foundation, Inc. +. +.P +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 +.URL http://\:www.gnu.org/\:copyleft/\:fdl.html "GNU copyleft site" . +. +.P +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 +.MTO bwarken@mayn.de "Bernd Warken" . +. +It is maintained by +.MTO wl@gnu.org "Werner Lemberg" . +. +.P +.I groff +is a GNU free software project. +. +All parts of the +.I 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). +. +. +.\" -------------------------------------------------------------------- .SH "SEE ALSO" -.BR grog (@MAN1EXT@), -.BR @g@troff (@MAN1EXT@), -.BR @g@tbl (@MAN1EXT@), -.BR @g@pic (@MAN1EXT@), -.BR @g@eqn (@MAN1EXT@), -.BR @g@grn (@MAN1EXT@), -.BR grap (1), -.BR @g@soelim (@MAN1EXT@), -.BR @g@refer (@MAN1EXT@), -.BR grops (@MAN1EXT@), -.BR grodvi (@MAN1EXT@), -.BR grotty (@MAN1EXT@), -.BR grolj4 (@MAN1EXT@), -.BR grolbp (@MAN1EXT@), -.BR grohtml (@MAN1EXT@), -.BR gxditview (@MAN1EXT@), -.BR groff_font (@MAN5EXT@), -.BR groff_out (@MAN5EXT@), -.BR groff_man (@MAN7EXT@), -.BR groff_ms (@MAN7EXT@), -.BR groff_me (@MAN7EXT@), -.BR groff_char (@MAN7EXT@) +.\" -------------------------------------------------------------------- +. +The +.IR "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 +.BR info (1) +on how to read it. +. +.P +Due to its complex structure, the groff system has many man pages. +. +They can be read with +.BR man (1) +or +.BR \%groffer (@MAN1EXT@). +. +.TP +Introduction, history and further readings: +.BR roff (@MAN7EXT@). +. +.TP +Viewer for groff files: +.BR \%groffer (@MAN1EXT@), +.BR \%gxditview (@MAN1EXT@), +.BR \%xditview (1x). +. +.TP +Wrapper programs for formatters: +.BR \%groff (@MAN1EXT@), +.BR \%grog (@MAN1EXT@). +. +.TP +Roff preprocessors: +.BR \%@g@eqn (@MAN1EXT@), +.BR \%@g@grn (@MAN1EXT@), +.BR \%@g@pic (@MAN1EXT@), +.BR \%@g@refer (@MAN1EXT@), +.BR \%@g@soelim (@MAN1EXT@), +.BR \%@g@tbl (@MAN1EXT@), +.BR grap (1). +. +.TP +Roff language with the groff extensions: +.BR \%groff (@MAN7EXT@), +.BR \%groff_char (@MAN7EXT@), +.BR \%groff_diff (@MAN7EXT@), +.BR \%groff_font (@MAN5EXT@). +. +.TP +Roff formatter programs: +.BR \%@g@nroff (@MAN1EXT@), +.BR \%@g@troff (@MAN1EXT@), +.BR ditroff (@MAN7EXT@). +. +.TP +The intermediate output language: +.BR \%groff_out (@MAN7EXT@). +. +.TP +Postprocessors for the output devices: +.BR \%grodvi (@MAN1EXT@), +.BR \%grohtml (@MAN1EXT@), +.BR \%grolbp (@MAN1EXT@), +.BR \%grolj4 (@MAN1EXT@), +.BR \%grops (@MAN1EXT@), +.BR \%grotty (@MAN1EXT@). +. +.TP +Groff macro packages and macro-specific utilities: +.BR \%groff_tmac (@MAN5EXT@), +.BR \%groff_man (@MAN7EXT@), +.BR \%groff_mdoc (@MAN7EXT@), +.BR \%groff_me (@MAN7EXT@), +.BR \%groff_mm (@MAN7EXT@), +.BR \%groff_mmse (@MAN7EXT@), +.BR \%groff_mom (@MAN7EXT@), +.BR \%groff_ms (@MAN7EXT@), +.BR \%groff_www (@MAN7EXT@), +.BR \%mmroff (@MAN7EXT@). +. +.TP +The following utilities are available: +.BR \%addftinfo (@MAN1EXT@), +.BR \%afmtodit (@MAN1EXT@), +.BR \%eqn2graph (@MAN1EXT@), +.BR \%groffer (@MAN1EXT@), +.BR \%gxditview (@MAN1EXT@), +.BR \%hpftodit (@MAN1EXT@), +.BR \%@g@indxbib (@MAN1EXT@), +.BR \%@g@lookbib (@MAN1EXT@), +.BR \%pfbtops (@MAN1EXT@), +.BR \%pic2graph (@MAN1EXT@), +.BR \%tfmtodit (@MAN1EXT@). +. +. +.\" -------------------------------------------------------------------- +.\" Emacs setup +.\" -------------------------------------------------------------------- . .\" Local Variables: .\" mode: nroff -- cgit v1.2.3