Merge Groff 1.18.1 changes.

5 files changed, 1720 insertions, 461 deletions

diff --git a/contrib/groff/src/devices/grotty/grotty.man b/contrib/groff/src/devices/grotty/grotty.man
index 7f38846..0b76887 100644
--- a/contrib/groff/src/devices/grotty/grotty.man
+++ b/contrib/groff/src/devices/grotty/grotty.man
@@ -1,6 +1,6 @@
 .ig
 $FreeBSD$
-Copyright (C) 1989-2000, 2001 Free Software Foundation, Inc.
+Copyright (C) 1989-2000, 2001, 2002 Free Software Foundation, Inc.
 
 Permission is granted to make and distribute verbatim copies of
 this manual provided the copyright notice and this permission notice
@@ -17,22 +17,28 @@ versions, except that this permission notice may be included in
 translations approved by the Free Software Foundation instead of in
 the original English.
 ..
+.
+.
 .TH GROTTY @MAN1EXT@ "@MDATE@" "Groff Version @VERSION@"
 .SH NAME
 grotty \- groff driver for typewriter-like devices
+.
+.
 .SH SYNOPSIS
 .B grotty
 [
-.B \-hfbuodBUv
+.B \-bBcdfhiouUv
 ] [
 .BI \-F dir
 ] [
-.IR files \|.\|.\|.
+.IR files \|.\|.\|.\&
 ]
 .PP
 It is possible to have whitespace between the
 .B \-F
 option and its parameter.
+.
+.
 .SH DESCRIPTION
 .B grotty
 translates the output of GNU
@@ -51,6 +57,8 @@ or
 .B \-Tutf8
 option on ASCII based systems, and with
 .B \-Tcp1047
+and
+.B \-Tutf8
 on EBCDIC based hosts.
 If no files are given,
 .B grotty
@@ -62,21 +70,75 @@ will also cause
 to read the standard input.
 Output is written to the standard output.
 .LP
-Normally
+By default,
 .B grotty
-prints a bold character
+emits SGR escape sequences (from ISO 6429, also called ANSI color escapes)
+to change text attributes (bold, italic, colors).
+This makes it possible to have eight different \M[green]background\M[]
+and \m[red]foreground\m[] colors; additionally, bold and italic
+attributes can be used \f[BI]at the same time\f[] (by using the BI font).
+.LP
+The following colors are defined in
+.BR tty.tmac :
+black, white, red, green, blue, yellow, magenta, cyan.
+Unknown colors are mapped to the default color (which is dependent on the
+settings of the terminal; in most cases, this is black for the foreground
+and white for the background).
+.LP
+Use the
+.B \-c
+switch to revert to the old behaviour, printing a bold character
 .I c
-using the sequence
+with the sequence
 .RI ` c
 .SM BACKSPACE
 .IR c '
-and a italic character
+and an italic character
 .I c
 by the sequence
 .RB ` _
 .SM BACKSPACE
 .IR c '.
-These sequences can be displayed on a terminal
+At the same time, color output is disabled.
+The same effect can be achieved by setting either the
+.B GROFF_NO_SGR
+environment variable or using the `sgr' X command (see below).
+.LP
+For SGR support, it is necessary to use the
+.B \-R
+option of
+.BR less (1)
+to disable the interpretation of
+.BR grotty 's
+old output format.
+Consequently, all programs which use
+.B less
+as the pager program have to pass this option to it.
+For
+.BR man (1)
+in particular, either add
+.B \-R
+to the
+.B $PAGER
+environment variable, e.g.\&
+.RS
+.LP
+.B PAGER="/usr/bin/less -R"
+.br
+.B export PAGER
+.RE
+.LP
+or use the
+.B \-P
+option of
+.B man
+to set the pager executable and its options, or modify the configuration
+file of
+.B man
+in a similar fashion.
+.LP
+.BR grotty 's
+old output format can be displayed on a terminal
 by piping through
 .BR ul (1).
 Pagers such as
@@ -116,11 +178,58 @@ then it will be treated as a bold font.
 The code field in the font description field gives the
 code which will be used to output the character.
 This code can also be used in the
-.B \eN
+.B \[rs]N
 escape sequence in
 .BR troff .
+.
+.
 .SH OPTIONS
 .TP
+.B \-b
+Suppress the use of overstriking for bold characters.
+Ignored if
+.B \-c
+isn't used.
+.
+.TP
+.B \-B
+Use only overstriking for bold-italic characters.
+Ignored if
+.B \-c
+isn't used.
+.
+.TP
+.B \-c
+Use
+.BR grotty 's
+old output format (see above).
+This also disables color output.
+.
+.TP
+.B \-d
+Ignore all
+.B \[rs]D
+commands.
+Without this
+.B grotty
+will render
+.B \[rs]D'l\|.\|.\|.\&'
+commands that have at least one zero argument
+(and so are either horizontal or vertical)
+using
+.BR \- ,
+.BR | ,
+and
+.B +
+characters.
+.
+.TP
+.B \-f
+Use form feeds in the output.
+A form feed will be output at the end of each page that has no output
+on its last line.
+.
+.TP
 .BI \-F dir
 Prepend directory
 .IB dir /dev name
@@ -137,52 +246,69 @@ or
 .B \-h
 Use horizontal tabs in the output.
 Tabs are assumed to be set every 8 columns.
+.
 .TP
-.B \-f
-Use form feeds in the output.
-A form feed will be output at the end of each page that has no output
-on its last line.
+.B \-i
+Use escape sequences to set the italic text attribute instead of the
+underline attribute for italic fonts (`I' and `BI').
+Note that most terminals (including xterm) don't support this.
+Ignored if
+.B \-c
+is active.
+.
 .TP
-.B \-b
-Suppress the use of overstriking for bold characters.
+.B \-o
+Suppress overstriking (other than for bold or underlined characters in
+case the old output format has been activated with
+.BR \-c ).
+.
 .TP
 .B \-u
 Suppress the use of underlining for italic characters.
-.TP
-.B \-B
-Use only overstriking for bold-italic characters.
+Ignored if
+.B \-c
+isn't used.
+.
 .TP
 .B \-U
 Use only underlining for bold-italic characters.
-.TP
-.B \-o
-Suppress overstriking (other than for bold or underlined characters).
-.TP
-.B \-d
-Ignore all
-.B \eD
-commands.
-Without this
-.B grotty
-will render
-.B \eD'l\|.\|.\|.'
-commands that have at least at least one zero argument
-(and so are either horizontal or vertical)
-using
-.BR \- ,
-.B |
-and
-.B +
-characters.
+Ignored if
+.B \-c
+isn't used.
+.
 .TP
 .B \-v
 Print the version number.
+.
+.
+.SH USAGE
+.B grotty
+understands a single X command produced using the
+.B \[rs]X
+escape sequence.
+.TP
+.BI \[rs]X'tty:\ sgr\  n '
+If
+.I n
+is non-zero or missing, enable SGR output (this is the default), otherwise
+use the old drawing scheme for bold and underline.
+.
+.
+.SH ENVIRONMENT
+.TP
+.B GROFF_NO_SGR
+If set, the old drawing scheme for bold and underline (using the
+backspace character) is active.
+Colors are disabled.
+.
+.
 .SH FILES
 .TP
 .B @FONTDIR@/devascii/DESC
 Device description file for
 .B ascii
 device.
+.
 .TP
 .BI @FONTDIR@/devascii/ F
 Font description file for font
@@ -202,11 +328,13 @@ Font description file for font
 of
 .B koi8-r
 device.
+.
 .TP
 .B @FONTDIR@/devlatin1/DESC
 Device description file for
 .B latin1
 device.
+.
 .TP
 .BI @FONTDIR@/devlatin1/ F
 Font description file for font
@@ -214,11 +342,13 @@ Font description file for font
 of
 .B latin1
 device.
+.
 .TP
 .B @FONTDIR@/devutf8/DESC
 Device description file for
 .B utf8
 device.
+.
 .TP
 .BI @FONTDIR@/devutf8/ F
 Font description file for font
@@ -226,11 +356,13 @@ Font description file for font
 of
 .B utf8
 device.
+.
 .TP
 .B @FONTDIR@/devcp1047/DESC
 Device description file for
 .B cp1047
 device.
+.
 .TP
 .BI @FONTDIR@/devcp1047/ F
 Font description file for font
@@ -238,10 +370,12 @@ Font description file for font
 of
 .B cp1047
 device.
+.
 .TP
 .B @MACRODIR@/tty.tmac
 Macros for use with
 .BR grotty .
+.
 .TP
 .B @MACRODIR@/tty-char.tmac
 Additional klugdey character definitions for use with
@@ -250,6 +384,8 @@ Additional klugdey character definitions for use with
 Note that on EBCDIC hosts, only files for the
 .B cp1047
 device will be installed.
+.
+.
 .SH BUGS
 .LP
 .B grotty
@@ -258,12 +394,22 @@ is intended only for simple documents.
 There is no support for fractional horizontal or vertical motions.
 .LP
 There is no support for
-.B \eD
+.B \[rs]D
 commands
 other than horizontal and vertical lines.
 .LP
-Characters above the first line (ie with a vertical position of 0)
+Characters above the first line (ie with a vertical position of\~0)
 cannot be printed.
+.LP
+Color handling is different compared to
+.BR grops (@MAN1EXT@).
+.B \[rs]M
+doesn't set the fill color for closed graphic objects (which
+.B grotty
+doesn't support anyway) but changes the background color of the character
+cell, affecting all subsequent operations.
+.
+.
 .SH "SEE ALSO"
 .BR groff (@MAN1EXT@),
 .BR @g@troff (@MAN1EXT@),
@@ -272,6 +418,7 @@ cannot be printed.
 .BR groff_char (@MAN7EXT@),
 .BR ul (1),
 .BR more (1),
+.BR man (1),
 .BR less (1)
 .
 .\" Local Variables:
diff --git a/contrib/groff/src/roff/groff/groff.man b/contrib/groff/src/roff/groff/groff.man
index f64044e..f2fc6ad 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 <bwarken@mayn.de>
 
-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
-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 "" "-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
-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 \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 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 \-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
-.SM
-.B GROFF_COMMAND_PREFIX
-If this is set
-.IR X ,
+.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
+.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 \%@g@indxbib
 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 <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 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 <faber@lunabase.org>.
-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
diff --git a/contrib/groff/src/roff/nroff/nroff.man b/contrib/groff/src/roff/nroff/nroff.man
index d6e1b6d..a8cfaf6 100644
--- a/contrib/groff/src/roff/nroff/nroff.man
+++ b/contrib/groff/src/roff/nroff/nroff.man
@@ -40,12 +40,12 @@ the original English.
 .OP \-o list
 .OP \-p
 .OP \-r cn
-.OP \-t
 .OP \-S
+.OP \-t
 .OP \-T name
 .OP \-U
 .OP \-v
-.RI "[\ " file\|.\|.\|. "\ ]"
+.RI "[\ " "file" "\ .\|.\|.\ ]"
 .br
 .ad \na
 .SH DESCRIPTION
@@ -82,16 +82,22 @@ environment variable.
 .PP
 The
 .B \-h
-option
-is equivalent to the
+and
+.B \-c
+options
+are equivalent to
 .BR grotty 's
+options
 .B \-h
-option (i.e., using tabs in the output).
+(using tabs in the output) and
+.B \-c
+(using the old output scheme instead of SGR escape sequences).
 The
+.BR \-C ,
 .BR \-i ,
 .BR \-n ,
 .BR \-m ,
-.B \-o
+.BR \-o ,
 and
 .B \-r
 options have the effect described in
@@ -115,8 +121,6 @@ Options
 .B \-U
 (unsafe) are passed to
 .BR groff . 
-.B \-S
-is passed by default.
 .B \-v
 shows the version number.
 .SH ENVIRONMENT
diff --git a/contrib/groff/src/roff/nroff/nroff.sh b/contrib/groff/src/roff/nroff/nroff.sh
index 82f9031..1763134 100755
--- a/contrib/groff/src/roff/nroff/nroff.sh
+++ b/contrib/groff/src/roff/nroff/nroff.sh
@@ -37,13 +37,14 @@ case "`#locale charmap 2>/dev/null`" in
      esac ;;
 esac
 opts=
-safer=-S
 
 # `for i; do' doesn't work with some versions of sh
 
 for i
   do
   case $1 in
+    -c)
+      opts="$opts -P-c" ;;
     -h)
       opts="$opts -P-h" ;;
     -[eq] | -s*)
@@ -52,19 +53,13 @@ for i
     -[mrnoT])
       echo "$prog: option $1 requires an argument" >&2
       exit 1 ;;
-    -[ipt] | -[mrno]*)
+    -[iptSUC] | -[mrno]*)
       opts="$opts $1" ;;
     -Tascii | -Tlatin1 | -Tkoi8-r | -Tutf8 | -Tcp1047)
       T=$1 ;;
     -T*)
       # ignore other devices
       ;;
-    -S)
-      # safer behaviour
-      safer=-S ;;
-    -U)
-      # unsafe behaviour
-      safer=-U ;;
     -u*)
       # Solaris 2.2 `man' uses -u0; ignore it,
       # since `less' and `more' can use the emboldening info.
@@ -73,7 +68,7 @@ for i
       echo "GNU nroff (groff) version @VERSION@"
       exit 0 ;;
     --help)
-      echo "usage: nroff [-h] [-i] [-mNAME] [-nNUM] [-oLIST] [-p] [-rCN] [-t] [-Tname] [FILE...]"
+      echo "usage: nroff [-cChipt] [-mNAME] [-nNUM] [-oLIST] [-rCN] [-Tname] [FILE...]"
       exit 0 ;;
     --)
       shift
@@ -94,6 +89,6 @@ done
 
 : ${GROFF_BIN_PATH=@BINDIR@}
 export GROFF_BIN_PATH
-PATH=$GROFF_BIN_PATH:$PATH groff $safer -Wall -mtty-char $T $opts ${1+"$@"}
+PATH=$GROFF_BIN_PATH:$PATH groff -mtty-char $T $opts ${1+"$@"}
 
 # eof
diff --git a/contrib/groff/tmac/troffrc b/contrib/groff/tmac/troffrc
index ea4ce48..4153a84 100644
--- a/contrib/groff/tmac/troffrc
+++ b/contrib/groff/tmac/troffrc
@@ -1,7 +1,9 @@
 .\" Startup file for troff.
 .\" $FreeBSD$
+.
 .\" This is tested by pic.
 .nr 0p 0
+.
 .\" Use .do here, so that it works with -C.
 .\" The groff command defines the .X string if the -X option was given.
 .ie r.X .do ds troffrc!ps Xps.tmac
@@ -23,16 +25,30 @@
 .	do mso \*[troffrc!\*[.T]]
 .do rm troffrc!ps troffrc!Xps troffrc!dvi troffrc!X75 troffrc!X75-12 \
 troffrc!X100 troffrc!X100-12 troffrc!lj4 troff!lbp troffrc!html
-.ie '\*(.T'cp1047' .do tr \[char65]
-.el .if !"\*[.T]"koi8-r" .do tr \[char160]
+.
+.\" test whether we work under EBCDIC
+.do ie '\[char97]'a' \
+.	if !"\*[.T]"koi8-r" .do tr \[char160]\~
+.el \
+.	do tr \[char65]\~
+.
 .ie "\*[.T]"koi8-r" \{\
+.
+.\" Set the hyphenation language to `us-ru'.
 .do hla us-ru
+.
+.\" Load hyphenation patterns from `hyphen.us-ru' (in the tmac directory).
 .do hpf hyphen.us-ru
+.
 .\}
 .el \{\
+.
 .\" Set the hyphenation language to `us'.
 .do hla us
+.
 .\" Load hyphenation patterns from `hyphen.us' (in the tmac directory).
 .do hpf hyphen.us
+.
 .\}
+.
 .\" Don't let blank lines creep in here.