* src/roff/groff/groff.man: Completely rewritten.

3 files changed, 1439 insertions, 368 deletions

diff --git a/ChangeLog b/ChangeLog
index f866e273..a27444de 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,11 @@
+2002-01-01  Bernd Warken  <bwarken@mayn.de>
+
+	* src/roff/groff/groff.man: Completely rewritten.
+
+2001-12-31  Werner LEMBERG  <wl@gnu.org>
+
+	* doc/Makefile: Updated.
+
 2001-12-30  Werner LEMBERG  <wl@gnu.org>
 
 	* tmac/www.tmac: Make all names of internal macros/registers/strings
diff --git a/doc/Makefile b/doc/Makefile
index 489a18bf..ede9b400 100755
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -93,8 +93,8 @@ all: $(DOCS)
 groff: groff.texinfo
 	makeinfo groff.texinfo
 
-gnubw.eps: gnubw-master-image
-	pngtopnm gnubw-master-image | pnmscale 0.1 | pnmtops -noturn > gnubw.eps
+gnubw.eps: gnupng
+	pngtopnm gnupng | pnmscale 0.1 | pnmtops -noturn > gnubw.eps
 
 homepage.html: gnubw.eps
 
diff --git a/src/roff/groff/groff.man b/src/roff/groff/groff.man
index 805c6a17..da298c96 100644
--- a/src/roff/groff/groff.man
+++ b/src/roff/groff/groff.man
@@ -1,5 +1,10 @@
 .ig
-Copyright (C) 1989-2000, 2001 Free Software Foundation, Inc.
+groff.man
+
+Last update : 1 Jan 2002
+
+Copyright (C) 1989, 2002 Free Software Foundation, Inc.
+Rewritten in 2002 by Bernd Warken <bwarken@mayn.de>
 
 Permission is granted to make and distribute verbatim copies of
 this manual provided the copyright notice and this permission notice
@@ -16,458 +21,1516 @@ versions, except that this permission notice may be included in
 translations approved by the Free Software Foundation instead of in
 the original English.
 ..
-.de TQ
+.
+.\" --------------------------------------------------------------------
+.\" Setup
+.\" --------------------------------------------------------------------
+.
+.mso www.tmac
+.
+.if n \{\
+.  mso tty-char.tmac
+.  ftr CR R
+.  ftr CI I
+.  ftr CB B
+.\}
+.
+.if '\*[.T]'dvi' \{\
+.  ftr CB CW
+.\}
+.
+.ie t \{\
+.  ds @- "\-\"
+.  ds @-- "\-\^\-\"
+.\}
+.el \{\
+.  ds @- "-\"
+.  ds @-- "--\"
+.\}
+.
+.als Minus @-
+.als MinusMinus @--
+.
+.ds Ellipsis .\|.\|.\"
+.
+.\" set adjust to both
+.ad b
+.
+.
+.\" --------------------------------------------------------------------
+.\" Begin of macro definitions
+.eo
+.
+.\" --------------------------------------------------------------------
+.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.
 .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"
+..
+.\" --------------------------------------------------------------------
+.de Text
+.  nop \)\$*
+..
+.\" --------------------------------------------------------------------
+.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
+..
+.\" --------------------------------------------------------------------
+.de EndSynopsis
+.  ad
+.  in
+..
+.\" --------------------------------------------------------------------
+.\" [ShortOpt]  (name [arg])
+.\"
+.\" short option in synopsis
+.\"
+.de [ShortOpt]
+.  if \n[.$]=0 \
+.    return
+.  ds @opt \$1\"
+.  shift
+.  ie \n[.$]=0 \
+.    Text \fR[\fP\f(CB\*[@-]\*[@opt]\fP\fR]\fP
+.  el \
+.    Text \fR[\fP\f(CB\*[@-]\*[@opt]\~\fP\fI\/\$*\fP\fR]\fP
+.  rm @opt
+..
+.\" --------------------------------------------------------------------
+.\" Option in synopsis (short option)
+.de SynOpt
+.  if \n[.$]=0 \
+.    return
+.  ds @opt \$1\"
+.  shift
+.  ie \n[.$]=0 \
+.    Text \fR[\fP\f(CB\*[@-]\*[@opt]\fP\fR]\fP
+.  el \
+.    Text \fR[\fP\f(CB\*[@-]\*[@opt]\~\fP\fI\/\$*\fP\fR]\fP
+.  rm @opt
 ..
+.\" --------------------------------------------------------------------
+.\" ShortOpt ([char [punct]])
+.\"
+.\" `-c' somwhere in the text 
+.\" second arg is punctuation
+.\"
+.de ShortOpt
+.  ds @opt \$1\"
+.  shift
+.  Text \f(CB\*[@-]\*[@opt]\fP\/\$*
+.  rm @opt
+..
+.\" --------------------------------------------------------------------
+.\" LongOpt  ([name [punct]])
+.\"
+.\" `--name' somwhere in the text 
+.\" second arg is punctuation
+.\"
+.de LongOpt
+.  ds @opt \$1\"
+.  shift
+.  Text \f(CB\*[@--]\fP\fB\*[@opt]\fP\/\$*
+.  rm @opt
+..
+.\" --------------------------------------------------------------------
+.\" OptDef  (shortopt [longopt [argument]])
+.\"
+.\" option documentation
+.\" args : `shortopt', `longopt' can be ""
+.\"
+.de OptDef
+.  ds @short
+.  ds @long
+.  ds @arg
+.  if \n[.$]>=1 \{\
+.    ds @arg1 "\$1\"
+.    if !'\*[@arg1]'' \
+.      ds @short "\f(CB\*[@-]\*[@arg1]\fP\"
+.    if \n[.$]>=2 \{\
+.      if !'\*[@short]'' \
+.        as @short \f(CW\0\fP
+.      ds @arg2 "\$2\"
+.      if !'\*[@arg2]'' \
+.        ds @long "\f(CB\*[@--]\fP\fB\*[@arg2]\fP\"
+.      if \n[.$]>=3 \{\
+.        if !'\*[@long]'' \
+.          as @long \|=\|\"
+.        shift 2
+.        ds @arg \fI\$*\"
+.      \}
+.    \}
+.  \}
+.  IP "\fR\*[@short]\*[@long]\*[@arg]\fP"
+.  rm @arg
+.  rm @arg1
+.  rm @arg2
+.  rm @short
+.  rm @long
+..
+.\" --------------------------------------------------------------------
+.\" Continuation of an OptDef header.
+.de OptDef+
+.  br
+.  ns
+.  OptDef \$@
+..
+.\" --------------------------------------------------------------------
+.\" Environment variable
+.de EnvVar
+.  SM
+.  BR \$1 \$2
+..
+.\" --------------------------------------------------------------------
+.\" A shell command line
+.de ShellCommand
+.  ad l
+.  I shell>
+.  nop \f[CB]\$*\f[P]
+.  ad
+..
+.\" --------------------------------------------------------------------
+.\" 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 \-abceghilpstvzCEGNRSUVXZ
-.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 \*[Minus] (minus character).
+.
+A filename of \*[Minus] (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 "GNU" \%http://\:www.gnu.org .
+.
+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
-is a front-end to the groff document formatting system.
-Normally it runs the
+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 "" arg
+Pass
+.I arg
+to the postprocessor.
+.
+Several arguments should be passed with a separate
+.ShortOpt P
+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 postprocessor.
+.
+.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
-program and a postprocessor appropriate for the selected
-device.
-Available devices are:
+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
+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
+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 \fIname\fP\fB.tmac\fP (or \fBtmac.\fP\fIname\fP); 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
-.B ascii
-For typewriter-like devices.
+.BR \%@g@soelim (@MAN1EXT@)
+for including macro files from standard locations,
+.
+.P
+and
 .TP
-.B latin1
-For typewriter-like devices using the ISO Latin-1 (ISO 8859-1) character set.
+.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 utf8
-For typewriter-like devices using the Unicode (ISO 10646) character set with
-UTF-8 encoding.
+.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
+Text output using the
+.BR ascii (7)
+character set.
+.
 .TP
 .B cp1047
-For typewriter-like devices which use the EBCDIC code page IBM cp1047
-(e.g. OS/390 Unix).
+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
+Text output using the ISO Latin-1 (ISO 8859-1) character set; see
+.BR iso_8859_1 (7).
+.
+.TP
+.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 html
-To produce HTML output.
-.LP
+.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 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 \-c
-.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 ,
-and
-.BR soelim .
-It does not apply to
-.BR grap ,
-.BR grops ,
-.BR grodvi ,
-.BR grotty ,
-.BR grolj4 ,
-.BR grohtml ,
+.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 \%indxbib
 and
-.BR gxditview .
+.BR \%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
+.
+.
+.\" --------------------------------------------------------------------
+.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 eqn
+and
+.B pic
+and the
+.B me
+macro set, classical troff had to be called by
+.
+.P
+.ShellCommand pic foo.me | eqn -Tlatin1 | troff -me -Tlatin1 | grotty
+.
+.P
+Using
+.BR groff ,
+this pipe can be shortened to the equivalent command
+.
+.P
+.ShellCommand groff -ep -me -T latin1 foo.me
+.
+.P
+An even easier way to call this is to let
+.BR grog (@MAN1EXT@)
+guess the preprocessor and macro options by
+.
+.P
+.ShellCommand `grog -Tlatin1 foo.me`
+.
+.P
+To view the contents in an automated way, just call
+.
+.P
+.ShellCommand groffer foo.me
+.
+.
+.\" --------------------------------------------------------------------
+.SH BUGS
+.\" --------------------------------------------------------------------
+.
+.P
+On EBCDIC hosts (e.g. OS/390 Unix), output devices
 .BR ascii ,
 .BR latin1 ,
 and
 .B utf8
 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 <jjc@jclark.com>
-.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, 2001 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 "GNU website" http://\:www.gnu.org/\:software/\:groff .
+The most recent released version of groff is available for anonymous
+ftp at the
+.FTP "groff development site" \
+ftp://ftp.ffii.org/\:pub/\:groff/\:devel/\:groff-current.tar.gz .
+.
+.P
+Three groff mailing lists are available:
+.TP
+.MAILTO bug-groff@gnu.org
+for reporting bugs,
+.
+.TP
+.MAILTO groff@gnu.org
+for general discussion of groff,
+.
+.TP
+.MAILTO 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 <faber@lunabase.org>.
-The actual version can be found at
-.IP
-\%http://www.lunabase.org/~faber/Vault/software/grap/
+preprocessor, written by
+.MAILTO faber@lunabase.org " Ted Faber" .
+.
+The actual version can be found at the
+.
+.URL "grap website" \
+http://\:www.lunabase.org/\:~faber/\:Vault/\:software/\:grap/ .
+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 "GNU copyleft site" http://\:www.gnu.org/\:copyleft/\:fdl.html .
+.
+.P
+This document is based on the original groff man-page written by
+.MAILTO jjc@jclark.com "James Clark" .
+.
+It was rewritten, enhanced, and put under the FDL license by
+.MAILTO bwarken@mayn.de "Bernd Warken" .
+.
+It is maintained by
+.MAILTO 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 roff (@MAN7EXT) ;
-this man page provides an exhaustive list of programs and packages related
-to
-.BR groff .
+.\" --------------------------------------------------------------------
+.
+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_ms (@MAN7EXT@),
+.BR \%groff_www (@MAN7EXT@),
+.BR \%mmroff (@MAN7EXT@).
+.
+.TP
+The following utilities are available
+.BR \%addftinfo (@MAN1EXT@),
+.BR \%afmtodit (@MAN1EXT@),
+.BR \%groffer (@MAN1EXT@),
+.BR \%gxditview (@MAN1EXT@),
+.BR \%hpftodit (@MAN1EXT@),
+.BR \%@g@indxbib (@MAN1EXT@),
+.BR \%@g@lookbib (@MAN1EXT@),
+.BR \%pfbtops (@MAN1EXT@),
+.BR \%tfmtodit (@MAN1EXT@).
+.
+.
+.\" --------------------------------------------------------------------
+.\" Emacs setup
+.\" --------------------------------------------------------------------
 .
 .\" Local Variables:
 .\" mode: nroff