This commit was generated by cvs2svn to compensate for changes in r69626,

which included commits to RCS files with non-trunk default branches.

5 files changed, 3358 insertions, 11 deletions

diff --git a/contrib/groff/man/Makefile.sub b/contrib/groff/man/Makefile.sub
index 9b87114..020d20f 100644
--- a/contrib/groff/man/Makefile.sub
+++ b/contrib/groff/man/Makefile.sub
@@ -1,2 +1,7 @@
-MAN5=groff_font.n groff_out.n
-MAN7=groff_char.n
+MAN5=\
+  groff_font.n \
+  groff_out.n
+MAN7=\
+  groff_char.n \
+  groff.n \
+  roff.n
diff --git a/contrib/groff/man/groff.man b/contrib/groff/man/groff.man
new file mode 100644
index 0000000..73c9188
--- /dev/null
+++ b/contrib/groff/man/groff.man
@@ -0,0 +1,2785 @@
+.\" st                        -*- nroff -*-
+.ig
+groff.7
+
+This file is part of groff, the GNU roff type-setting system.
+
+Copyright (C) 2000 Free Software Foundation, Inc.
+written by Bernd Warken <bwarken@mayn.de>
+
+Last update: 17 May 2000
+
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.1 or
+any later version published by the Free Software Foundation; with the
+Invariant Sections being this .ig-section and AUTHOR, with no
+Front-Cover Texts, and with no Back-Cover Texts.
+
+A copy of the Free Documentation License is included as a file called
+FDL in the main directory of the groff source package.
+..
+.
+.\" --------------------------------------------------------------------
+.\" Setup
+.\" --------------------------------------------------------------------
+.
+.if n \{\
+.  mso tmac.tty-char
+.  ftr CR R
+.  ftr CI I
+.  ftr CB B
+.\}
+.
+.if '\*[.T]'dvi' \{\
+.  ftr CB CW
+.\}
+.
+.\" a comment macro which does nothing
+.de c
+..
+.
+.\" a tab string
+.ds t "\t
+.
+.eo
+.
+.c text lines in macro definitions or bracketed sections \{...\}
+.de text
+.  if 1 \&\$*\&
+..
+.
+.de option
+.  ds @tmp@ \f(CB\$1\fP
+.  shift 1
+.  text \*[@tmp@]\$*
+.  rm @tmp@
+..
+.
+.als shellcommand option
+.
+.c --------- characters ---------
+.
+.de character
+.  ds @tmp@ \f(CB\$1\fP
+.  shift
+.  text \*[@tmp@]\$*
+.  rm @tmp@
+..
+.
+.de 'char
+.  ds @tmp@ \(oq\f(CB\$1\fP\(cq
+.  shift
+.  text \*[@tmp@]\$*
+.  rm @tmp@
+..
+.
+.de ''char
+.  ds @tmp@ \(lq\f(CB\$1\fP\(rq
+.  shift
+.  text \*[@tmp@]\$*
+.  rm @tmp@
+..
+.
+.c --------- requests ---------
+.
+.c request synopsis
+.de REQ
+.  ds @tmp@ \&\$1
+.  shift 1
+.  IP "\f(CB\&\*[@tmp@] \fP\f(CI\&\$*\fP" 10n
+.  rm @tmp@
+..
+.
+.de request
+.  ds @tmp@ \f(CB\$1\fP
+.  shift 1
+.  text \*[@tmp@]\$*
+.  rm @tmp@
+..
+.
+.c --------- macro or function arguments ---------
+.
+.de argument
+.  ds @tmp@ \f(CI\$1\fP
+.  shift 1
+.  while (\n[.$] >= 2) \{\
+.    as @tmp@ \/\f(CR\$1\fP\f(CI\,\$2\fP
+.    shift 2
+.  \}
+.  if \n[.$] .as @tmp@ \/\f(CR\$1\fP
+.  text \*[@tmp@]
+.  rm @tmp@
+..
+.
+.c argument followed by a numerical expression
+.de argterm
+.  ds @tmp@ \f(CI\$1\fP\|\f(CR\$2\fP
+.  shift 2
+.  text \*[@tmp@]\$*
+.  rm @tmp@
+..
+.
+.c --------- numerical elements ---------
+.
+.de number
+.  ds @tmp@ \f(CR\$1\fP
+.  shift 1
+.  text \*[@tmp@]\$*
+.  rm @tmp@
+..
+.
+.de prefixednumber
+.  ds @tmp@ \&\$1\ \f(CR\$2\fP
+.  shift 2
+.  text \*[@tmp@]\$*
+.  rm @tmp@
+..
+.
+.als scaleindicator request
+.
+.de scalednumber
+.  ds @tmp@ \f(CR\$1\fP\f(CB\$2\fP
+.  shift 2
+.  text \*[@tmp@]\$*
+.  rm @tmp@
+..
+.
+.de operator
+.  ds @tmp@ \(oq\f(CB\$1\fP\(cq
+.  shift
+.  text \*[@tmp@]\$*
+.  rm @tmp@
+..
+.
+.c --------- escape sequences ---------
+.
+.de esc[arg]
+.  ds @tmp@ \f(CB\(rs\$1[\fP\f(CI\$2\fP\f(CB]\fP
+.  shift 2
+.  text \*[@tmp@]\$*
+.  rm @tmp@
+..
+.
+.de esc(arg
+.  ds @tmp@ \f(CB\(rs\$1(\fP\f(CI\$2\fP
+.  shift 2
+.  text \*[@tmp@]\$*
+.  rm @tmp@
+..
+.
+.de escarg
+.  ds @tmp@ \f(CB\(rs\$1\fP\f(CI\$2\fP
+.  shift 2
+.  text \*[@tmp@]\$*
+.  rm @tmp@
+..
+.
+.de esc[]
+.  ds @tmp@ \f(CB\(rs[\fP\f(CI\$1\fP\f(CB]\fP
+.  shift
+.  text \*[@tmp@]\$*
+.  rm @tmp@
+..
+.
+.de esc(
+.  ds @tmp@ \f(CB\(rs(\fP\f(CI\$1\fP
+.  shift
+.  text \*[@tmp@]\$*
+.  rm @tmp@
+..
+.
+.de esc
+.  ds @tmp@ \f(CB\(rs\$1\fP
+.  shift
+.  text \*[@tmp@]\$*
+.  rm @tmp@
+..
+.
+.de (esc
+.  ds @tmp@ \f(CB\(rs(\$1\fP
+.  shift
+.  text \*[@tmp@]\$*
+.  rm @tmp@
+..
+.
+.de [esc]
+.  ds @tmp@ \f(CB\(rs[\$1]\fP
+.  shift
+.  text \*[@tmp@]\$*
+.  rm @tmp@
+..
+.
+.c escape sequence synopsis
+.de ESC
+.  ds @tmp@ \&\$1
+.  shift 1
+.  IP "\f(CB\(rs\&\*[@tmp@]\fP\f(CI\&\$*\fP"
+.  rm @tmp@
+..
+.
+.c synopsis for escape sequences with a long name
+.de ESC[]
+.  ds @arg1@ \&\$1
+.  ds @arg2@ \&\$2
+.  shift 2
+.  IP "\f(CB\(rs\&\*[@arg1@][\fP\f(CI\&\*[@arg2@]\fP\f(CB]\&\$*\fP"
+.  rm @arg1@
+.  rm @arg2@
+..
+.
+.c synopsis escape sequence with quoted argument
+.  de ESCq
+.  ds @tmp@ \&\$1
+.  shift 1
+.  IP "\f(CB\(rs\&\*[@tmp@]\(cq\fP\f(CI\h'-0.2m'\$*\/\fP\f(CB\(cq\fP"
+.  rm @tmp@
+..
+.
+.c synopsis for 2-escapes (special characters)
+.de ESc
+.  ds @tmp@ \$1
+.  TP 14n
+.  text \f(CB\(rs(\&\*[@tmp@]\ \ \ \fP\fR\(\*[@tmp@]\fP
+.  shift 1
+.  text \$*.
+.  rm @tmp@
+..
+.
+.c --------- registers ---------
+.
+.c synopsis for registers
+.de REG
+.  TP 10n
+.  text \&\f(CR\(rsn[\fP\f(CB\$1\fP\f(CR]\fP
+.  shift 1
+.if \n[.$] \&\$*
+..
+.
+.als register request
+.
+.c --------- warnings ---------
+.
+.als warning request
+.
+.c description of warnings
+.de Warning
+.  ne (2v + 1)
+.  TP 12n
+.  text \f(CB\$1\fP
+.  text \f(CI\$2\fP
+.  br
+..
+.
+.ec
+.
+.\" --------------------------------------------------------------------
+.\" Title
+.\" --------------------------------------------------------------------
+.
+.TH GROFF @MAN7EXT@ "@MDATE@" "Groff Version @VERSION@"
+.SH NAME
+groff \- a short reference for the GNU roff language
+.
+.\" --------------------------------------------------------------------
+.SH DESCRIPTION
+.\" --------------------------------------------------------------------
+.I groff
+stands for
+.I GNU roff
+and is the free implementation of the roff type-setting system.
+See
+.BR roff (@MAN7EXT@)
+for a survey and the background of the groff system.
+.LP
+This document gives only short descriptions of the predefined roff
+language elements as used in groff.
+Both the classical features and the groff extensions are provided.
+.LP
+Historically, the
+.I roff language
+was called
+.IR troff .
+.I groff
+is compatible with the classical system and provides proper extensions.
+So in GNU, the terms
+.IR roff ,
+.IR troff ,
+and
+.I groff language
+could be used as synonyms.
+However
+.I troff
+slightly tends to refer more to the classical aspects, whereas
+.I groff
+emphasizes the GNU extensions, and
+.I roff
+is the general term for the language.
+.LP
+This file is only a short version of the complete documentation that is
+found in the
+.I groff
+.BR info (1)
+file, which contains more detailed, actual, and concise information.
+.LP
+The general syntax for writing groff documents is relatively easy, but
+writing extensions to the roff language can be a bit harder.
+.LP
+The roff language is line-oriented.
+There are only two kinds of lines, control lines and text lines.
+The control lines start with a control character, by default a period
+.''char .
+or a single quote
+.''char ' ;
+all other lines are text lines.
+.LP
+.B Control lines
+represent commands, optionally with arguments.
+They have the following syntax.
+The leading control character can be followed by a command name;
+arguments, if any, are separated by blanks from the command name and
+among themselves, for example,
+.RS
+.LP
+\&\.command_name arg1 arg2
+.RE
+.LP
+For indentation, any number of space or tab characters can be inserted
+between the leading control character and the command name, but the control
+character must be on the first position of the line.
+.LP
+.B Text lines
+represent the parts that will be printed.
+They can be modified by escape sequences, which are recognized by a
+leading backslash
+.'char \(rs .
+These are in-line or even in-word formatting elements or functions.
+Some of these take arguments separated by single quotes
+.''char ' ,
+others are regulated by a length encoding introduced by an open
+parenthesis
+.'char (
+or enclosed in brackets
+.'char [
+and
+.'char ] .
+.LP
+The roff language provides flexible instruments for writing language
+extension, such as macros.
+When interpreting macro definitions, the roff system enters a special
+operating mode, called the
+.BR "copy mode" .
+.LP
+The copy mode behavior can be quite tricky, but there are some rules
+that ensure a safe usage.
+.IP 1.
+Printable backslashes must be denoted as
+.esc e .
+To be more precise,
+.esc e
+represents the current escape character.
+To get a backslash glyph, use
+.esc (rs .
+.IP 2.
+Double all backslashes.
+.IP 3.
+Begin all text lines with the special non-spacing character
+.esc & .
+.LP
+This does not produce the most efficient code, but it should work as a
+first measure.
+For better strategies, see the groff info file and
+.BR groff_tmac (@MAN5EXT@).
+.LP
+Reading roff source files is easier, just reduce all double backslashes
+to a single one in all macro definitions.
+.
+.\" --------------------------------------------------------------------
+.SH "GROFF ELEMENTS"
+.\" --------------------------------------------------------------------
+The roff language elements add formatting information to a text file.
+The fundamental elements are predefined commands and variables that make
+roff a full-blown programming language.
+.LP
+There are two kinds of roff commands, possibly with arguments.
+.B Requests
+are written on a line of their own starting with a dot
+.'char .
+or a
+.''char ' ,
+whereas
+.B Escape sequences
+are in-line functions and in-word formatting elements starting with a
+backslash
+.'char \(rs .
+.LP
+The user can define her own formatting commands using the
+.request .de
+request.  These commands are called
+.BR macros ,
+but they are used exactly like requests.  Macro packages are pre-defined 
+sets of macros written in the groff language.
+A user's possibilities to create escape sequences herself is very
+limited, only special characters can be mapped.
+.LP
+The groff language provides several kinds of variables with
+different interfaces.
+There are pre-defined variables, but the user can define her own
+variables as well.
+.LP
+.B String
+variables store character sequences.
+They are set with the
+.request .ds
+request and retrieved by the
+.esc *
+escape sequences.
+.LP
+.B Register
+variables can store numerical values, numbers with a scale unit, and
+occasionally string-like objects.
+They are set with the
+.request .nr
+request and retrieved by the
+.esc n
+escape sequences.
+.LP
+.B Environments
+allow the user to temporarily store global formatting parameters like
+line length, font size, etc. for later reuse.
+This is done by the
+.request .ev
+request.
+.LP
+.B Fonts
+are identified either by a name or by an internal number.
+The current font is chosen by the
+.request .ft
+request or by the
+.esc f
+escape sequences.
+Each device has special fonts, but the following fonts are available for 
+all devices.
+.B R
+is the standard font Roman.
+.B B
+is its
+.B bold
+counterpart.
+The
+.I italic
+font is called
+.B I
+is everywhere available, but on text devices, it is displayed as an
+underlined Roman font.
+For the graphical output devices, there exist constant-width pendants of
+these font,
+.BR CR ,
+.BR CI ,
+and
+.BR CB .
+On text devices, all characters have a constant width anyway.
+.LP
+Moreover, there are some advanced roff elements.
+A
+.B diversion
+stores information into a macro for later usage.
+A
+.B trap
+is a positional condition like a certain number of lines from page top
+or in a diversion or in the input.
+Some action can be prescribed to be run automatically when the condition
+is met.
+.LP
+More detailed information can be found in the groff info file.
+.
+.\" --------------------------------------------------------------------
+.SH "CONTROL CHARACTERS"
+.\" --------------------------------------------------------------------
+There is a small set of characters that have a special controlling task
+in certain conditions.
+.TP
+.character .
+A dot is only special at the beginning of a line or after the
+condition in the requests
+.request .if ,
+.request .ie ,
+.request .el ,
+and
+.request .while .
+There it is the control character that introduces a request (or macro).
+The special behavior can be delayed by using the
+.esc .
+escape.
+By using the 
+.request .cc
+request, the control character can be set to a different character,
+making the dot
+.'char .
+a non-special character.
+.IP ""
+In all other positions, it just means a dot character.
+In text paragraphs, it is advantageous to start each sentence at a line
+of its own.
+.TP
+.character '
+The single quote has two controlling tasks.  At the beginning of a line
+and in the conditional requests it is the non-breaking control
+character.
+That means that it introduces a request like the dot, but with the
+additional property that this request doesn't cause a linebreak.
+By using the 
+.request .c2
+request, the non-break control character can be set to a different
+character.
+.IP ""
+As a second task, it is the most commonly used argument separator in
+some functional escape sequences (but any pair of characters not part
+of the argument will work).
+In all other positions, it denotes the single quote or apostrophe
+character.
+Groff provides a printable representation with the
+.esc (cq
+escape sequence.
+.TP
+.character \(dq
+The double quote is used to enclose arguments in requests and macros.
+The escaped double quote
+.esc \(dq
+introduces a comment.
+Otherwise, it is not special.
+Groff provides a printable representation with the
+.esc (dq
+escape sequence.
+.TP
+.character \(rs
+The backslash usually introduces an escape sequence (this can be
+changed with the
+.request ec
+request).
+A printed version of the escape character is the
+.esc e
+escape; a backslash glyph can be obtained by
+.esc (rs .
+.TP
+.character (
+The open parenthesis is only special in escape sequences when
+introducing an escape name or argument consisting of exactly two
+characters.
+In groff, this behavior can be replaced by the \f(CB[]\fP construct.
+.TP
+.character [
+The opening bracket is only special in groff escape sequences; there it
+is used to introduce a long escape name or long escape argument.
+Otherwise, it is non-special, e.g. in macro calls.
+.TP
+.character ]
+The closing bracket is only special in groff escape sequences; there it
+terminates a long escape name or long escape argument.
+Otherwise, it is non-special.
+.TP
+\f(CIspace\fP
+Space characters are only functional characters.  They separate the
+arguments in requests or macros, and the words in text lines.
+They are subject to groff's horizontal spacing calculations.
+To get a defined space width, escape sequences like
+.'char "\(rs\ "
+(this is the escape character followed by a space),
+.esc | ,
+.esc ^ ,
+or
+.esc h
+should be used.
+.IP \f(CInewline\fP
+In text paragraphs, newlines mostly behave like space characters.
+Continuation lines can be specified by an escaped newline, i.e., by
+specifying a backslash
+.'char \(rs
+as the last character of a line.
+.IP \f(CItab\fP
+If a tab character occurs during text the interpreter makes a horizontal 
+jump to the next pre-defined tab position.
+There is a sophisticated interface for handling tab positions.
+.
+.\" --------------------------------------------------------------------
+.SH "NUMERICAL EXPRESSIONS"
+.\" --------------------------------------------------------------------
+A
+.B numerical value
+is a signed or unsigned integer or float with or without an appended
+scale indicator.
+A
+.B scale indicator
+is a one-character abbreviation for a unit of measurement.
+A number followed by a scale indicator signifies a size value.
+By default, numerical values do not have a scale indicator, i.e., they are
+normal numbers.
+.LP
+The roff language defines the following scale indicators.
+.LP
+.na
+.nh
+.TS
+center, tab(@);
+LfCB Lw(4i).
+c@Centimeter
+i@Inch
+P@Pica\ \(eq\ 1/6\ inch
+p@Point\ \(eq\ 1/72\ inch
+m@T{
+Em\ \(eq\ \fRthe font size in points (width of letter `\f(CRm\fR')
+T}
+M@100th \fRof an \f(CREm
+n@En\ \(eq\ Em/2
+u@\fRBasic unit for actual output device
+v@\fRVertical line space in basic units
+z@T{
+scaled point\ \(eq\ 1/\f(CIsizescale\fR of a point (defined in
+font \fIDESC\fP file)
+T}
+.TE
+.LP
+.ad
+.hy
+.B Numerical expressions
+are combinations of the numerical values defined above with
+the arithmetical operators
+.operator + ,
+.operator \- ,
+.operator * ,
+.operator / ,
+.operator %
+.RI ( modulo ),
+the comparative operators
+.operator ==
+(this is the same as
+.operator = ),
+.operator <= ,
+.operator >= ,
+.operator < ,
+.operator > ,
+the logical operators
+.operator &
+.RI ( and ),
+.operator :
+.RI ( or ),
+.operator !
+.RI ( not ),
+and the parentheses
+.operator (
+and
+.operator ) .
+.LP
+Moreover,
+.I groff
+added the following operators for numerical expressions:
+.LP
+.na
+.nh
+.TS
+center, tab(@);
+LfCB Lw(4i).
+e1\f(CB>?\fPe2@The maximum of \f(CIe1\fP and \f(CIe2\fP.
+e1\f(CB<?\fPe2@The minimum of \f(CIe1\fP and \f(CIe2\fP.
+\f(CB(\fPc\f(CB;\fPe\f(CB)@T{
+Evaluate \f(CIe\fP using \f(CIc\fP as the default scaling
+indicator.
+T}
+.TE
+.LP
+.ad
+.hy
+For details see the groff info file.
+.
+.\" --------------------------------------------------------------------
+.SH CONDITIONS
+.\" --------------------------------------------------------------------
+.B Conditions
+occur in tests raised by the
+.request .if ,
+.request .ie ,
+and the
+.request .while
+requests.
+The following table characterizes the different types of conditions.
+.LP
+.na
+.nh
+.TS
+center, tab(@);
+LfCB Lw(4i).
+\f(CIN\fP@T{
+A numerical expression \f(CIN\fP yields true if its value
+is\ \f(CR>0\fP.
+T}
+!\f(CIN\fP@T{
+True if the value of \f(CIN\fP is\ \f(CR\(<=0\fP.
+T}
+\&'\f(CIs1\fP'\f(CIs2\fP'@T{
+True if string\ \f(CIs1\fP is identical to string\ \f(CIs2\fP.
+T}
+!'\f(CIs1\fP'\f(CIs2\fP'@T{
+True if string\ \f(CIs1\fP is not identical to string\ \f(CIs2\fP.
+T}
+c\f(CIch@T{
+True if there is a character\ \f(CIch\fP available.
+T}
+d\f(CIname@T{
+True if there is a string, macro, diversion, or request
+called \f(CIname\fP.
+T}
+e@Current page number is even.
+o@Current page number is odd.
+n@Formatter is \fBnroff\fP.
+r\f(CIreg@T{
+True if there is a register named \f(CIreg\fP.
+T}
+t@Formatter is \fBtroff\fR.
+.TE
+.LP
+.ad
+.hy
+.
+.\" --------------------------------------------------------------------
+.SH REQUESTS
+.\" --------------------------------------------------------------------
+This section provides a short reference for the predefined requests.
+In groff, request and macro names can be arbitrarily long.
+No bracketing or marking of long names is needed.
+.LP
+Most requests take one or more arguments.
+The arguments are separated by space characters (no tabs!); there is no
+inherent limit for their length or number.
+An argument can be enclosed by a pair of double quotes: This is very handy
+if an argument contains space characters, e.g.,
+.argument "\(dqarg\ with\ space\(dq"
+denotes a single argument.
+.LP
+Some requests have optional arguments with a different behaviour.
+Not all of these details are outlined here.
+Refer to the groff info file for all details.
+.LP
+In the following request specifications, most argument names were chosen
+to be descriptive.
+Only the following denotations need clarification.
+.LP
+.na
+.nh
+.TS
+center, tab(@);
+LfCI Lw(4i).
+c@denotes a single character.
+font@T{
+a font either specified as a font name or a font number.
+T}
+anything@T{
+all characters up to the end of the line or within \f(CB\(rs{\fP
+and \f(CB\(rs}\fP.
+T}
+n@T{
+is a numerical expression that evaluates to an integer value.
+T}
+N@T{
+is an arbitrary numerical expression, signed or unsigned.
+T}
+\(+-N@T{
+has three meanings depending on its sign, described below.
+T}
+.TE
+.LP
+.ad
+.hy
+If an expression defined as
+.argument \(+-N
+starts with a
+.operator +
+sign the resulting value of the expression will be added to an already
+existing value inherent to the related request, e.g. adding to a number
+register.
+If the expression starts with a
+.operator -
+the value of the expression will be subtracted from the request value.
+.LP
+Without a sign,
+.argument N
+replaces the existing value directly.
+To assign a negative number either prepend\ \c
+.number 0
+or enclose the negative number in parentheses.
+.
+.\" --------------------------------------------------------------------
+.SS "REQUEST SHORT REFERENCE"
+.\" --------------------------------------------------------------------
+.PD 0
+.
+.REQ .
+Empty line, ignored.  Useful for structuring documents.
+.
+.REQ .\(rs\(dq anything
+Complete line is a comment.
+.
+.REQ .ab string
+Print
+.argument string
+on standard error, exit program.
+.
+.REQ .ad
+Begin line adjustment for output lines in current adjust mode.
+.
+.REQ .ad c
+Start line adjustment in mode
+.argument c
+(\f(CIc\fP\f(CR\|\^\(eq\|l,r,b,n\fP).
+.
+.REQ .af register c
+Assign format
+.argument c
+to
+.argument register
+(\f(CIc\fP\f(CR\|\^\(eq\|l,i,I,a,A\fP).
+.
+.REQ .aln alias register
+Create alias name for
+.argument register .
+.
+.REQ .als alias object
+Create alias name for request, string, macro, or diversion
+.argument object .
+.
+.REQ .am macro
+Append to
+.argument macro
+until
+.request ..
+is called.
+.
+.REQ .am macro end
+Append to
+.argument macro
+until
+.request .end
+is called.
+.
+.REQ .as stringvar anything
+Append
+.argument anything
+to
+.argument stringvar .
+.
+.REQ .asciify diversion
+Unformat special ASCII characters in
+.argument diversion .
+.
+.REQ .backtrace
+Print a backtrace of the input on stderr.
+.
+.REQ .bd font N
+Embolden
+.argument font
+by
+.argterm N -1
+units.
+.
+.REQ .bd S font N
+Embolden Special Font
+.argument S
+when current font is
+.argument font .
+.
+.REQ .bp
+Eject current page and begin new page.
+.
+.REQ .bp \(+-N
+Eject current page; next page number
+.argument \(+-N .
+.
+.REQ .blm macro
+Set the blank line macro to
+.argument macro .
+.
+.REQ .br
+Line break.
+.
+.REQ .break
+Break out of a while loop.
+.
+.REQ .c2
+Reset no-break control character to
+.''char ' .
+.
+.REQ .c2 c
+Set no-break control character to
+.argument c .
+.
+.REQ .cc
+Reset control character to
+.'char . .
+.
+.REQ .cc c
+Set control character to
+.argument c .
+.
+.REQ .ce
+Center the next input line.
+.
+.REQ .ce N
+Center following
+.argument N
+input lines.
+.
+.REQ .cf filename
+Copy contents of file
+.argument filename
+unprocessed to stdout or to the diversion.
+.
+.REQ .cflags mode c1 c2 ...
+Treat characters
+.argument c1 ,
+.argument c2 ,
+.argument ...
+according to
+.argument mode
+number.
+.
+.REQ .ch trap N
+Change
+.argument trap
+location
+to
+.argument N .
+.
+.REQ .char c anything
+Define character
+.argument c
+to string
+.argument anything .
+.
+.REQ .chop object
+Chop the last character off macro, string, or diversion
+.argument object .
+.
+.REQ .close stream
+Close the
+.argument stream .
+.
+.REQ .continue
+Finish the current iteration of a while loop.
+.
+.REQ .cp
+Enable compatibility mode.
+.
+.REQ .cp N
+If
+.I N
+is zero disable compatibility mode, otherwise enable it.
+.
+.REQ .cs font N M
+Set constant character width mode for
+.argument font
+to
+.argterm N /36
+ems with em
+.argument M .
+.
+.REQ .cu N
+Continuous underline in nroff, like
+.request .ul
+in troff.
+.
+.REQ .da macro
+Divert and append to
+.argument macro .
+.
+.REQ .de macro
+Define or redefine
+.argument macro
+until
+.request ..
+is called.
+.
+.REQ .de macro end
+Define or redefine
+.argument macro
+until
+.request .end
+is called.
+.
+.REQ .di
+End current diversion.
+.
+.REQ .di macro
+Divert to
+.argument macro .
+.
+.REQ .do name
+Interpret
+.request .name
+with compatibility mode enabled.
+.
+.REQ .ds stringvar anything
+Set
+.argument stringvar
+to
+.argument anything .
+.
+.REQ .dt N trap
+Set diversion trap to position
+.argument N
+(default scale indicator\ \c
+.scaleindicator v ).
+.
+.REQ .ec
+Reset escape character to
+.'char \(rs .
+.
+.REQ .ec c
+Set escape character to
+.argument c .
+.
+.REQ .el anything
+Else part for if-else (\c
+.argument .ie )
+request.
+.
+.REQ .em macro
+The
+.argument macro
+will be run after the end of input.
+.
+.REQ .eo
+Turn off escape character mechanism.
+.
+.REQ .ev
+Switch to previous environment.
+.
+.REQ .ev env
+Push down environment number or name
+.argument env
+and switch to it.
+.
+.REQ .evc env
+Copy the contents of environment
+.argument env
+to the current environment.
+No pushing or popping.
+.
+.REQ .ex
+Exit from roff processing.
+.
+.REQ .fam name
+Set the current font family to
+.argument name .
+.
+.REQ .fc
+Disable field mechanism.
+.
+.REQ .fc a
+Set field delimiter to
+.argument a
+and pad character to space.
+.REQ .fc a b
+Set field delimiter to
+.argument a
+and pad character to
+.argument b .
+.
+.REQ .fi
+Fill output lines.
+.
+.REQ .fl
+Flush output buffer.
+.
+.REQ .fp n font
+Mount
+.argument font
+on position
+.argument n .
+.
+.REQ .fp n internal external
+Mount font with long
+.argument external
+name to short
+.argument internal
+name on position
+.argument n .
+.
+.REQ .fspecial font s1 s2...
+When the current font is
+.argument font ,
+then the fonts
+.argument s1 ,
+.argument s2 ,
+.argument ...
+will be special.
+.
+.REQ .ft
+Return to previous font.
+Same as
+.request \(rsfP .
+.REQ .ft font
+Change to font name or number
+.argument font ;
+same as
+.esc[arg] f font
+escape sequence.
+.
+.REQ .ftr font1 font2
+Translate
+.argument font1
+to
+.argument font2 .
+.
+.REQ .hc
+Remove additional hyphenation indicator character.
+.
+.REQ .hc c
+Set up additional hyphenation indicator character\ \c
+.argument c .
+.
+.REQ .hcode c1 code1 c2 code2 ...
+Set the hyphenation code of character
+.argument c1
+to
+.argument code1 ,
+that of
+.argument c2
+to
+.argument code2 ,
+etc.
+.
+.REQ .hla lang
+Set the current hyphenation language to
+.argument lang .
+.
+.REQ .hlm n
+Set the maximum number of consecutive hyphenated lines to
+.argument n .
+.
+.REQ .hpf file
+Read hyphenation patterns from
+.argument file .
+.
+.REQ .hw words
+List of
+.argument words
+with exceptional hyphenation.
+.
+.REQ .hy N
+Switch to hyphenation mode
+.argument N .
+.
+.REQ .hym n
+Set the hyphenation margin to
+.argument n
+(default scale indicator\ \c
+.scaleindicator m ).
+.
+.REQ .hys n
+Set the hyphenation space to
+.argument n .
+.
+.REQ .ie cond anything
+If
+.argument cond
+then
+.argument anything
+else goto
+.request .el .
+.
+.REQ .if cond anything
+If
+.argument cond
+then
+.argument anything ;
+otherwise do nothing.
+.
+.REQ .ig
+Ignore text until
+.request ..
+is called.
+.
+.REQ .ig end
+Ignore text until
+.request .end .
+.
+.REQ .in
+Change to previous indent value.
+.
+.REQ .in \(+-N
+Change indent according to
+.argument \(+-N
+(default scale indicator\ \c
+.scaleindicator m ).
+.
+.REQ .it N trap
+Set an input-line count trap at position
+.argument N .
+.
+.REQ .kern
+Enable pairwise kerning.
+.
+.REQ .kern n
+If
+.argument n
+is zero, disable pairwise kerning, otherwise enable it.
+.
+.REQ .lc
+Remove leader repetition character.
+.
+.REQ .lc c
+Set leader repetition character to\ \c
+.argument c .
+.
+.REQ .length register anything
+Write the length of the string
+.argument anything
+in
+.argument register .
+.
+.REQ .lf N file
+Set input line number to
+.argument N
+and filename to
+.argument file .
+.
+.REQ .lg N
+Ligature mode on if
+.argterm N >0 .
+.
+.REQ .ll
+Change to previous line length.
+.
+.REQ .ll \(+-N
+Set line length according to
+.argument \(+-N
+(default size
+.scalednumber 6.5 i ,
+default scale indicator\ \c
+.scaleindicator m ).
+.
+.REQ .ls
+Change to the previous value of additional intra-line skip.
+.
+.REQ .ls N
+Set additional intra-line skip value to
+.argument N ,
+i.e.,
+.argterm N -1
+blank lines are inserted after each text output line.
+.
+.REQ .lt \(+-N
+Length of title (default scale indicator\ \c
+.scaleindicator m ).
+.
+.REQ .mc
+Margin character off.
+.
+.REQ .mc c
+Print character
+.argument c
+after each text line at actual distance from right margin.
+.
+.REQ .mc c N
+Set margin character to
+.argument c
+and distance to
+.argument N
+from right margin (default scale indicator\ \c
+.scaleindicator m ).
+.
+.REQ .mk register
+Mark current vertical position in
+.argument register .
+.
+.REQ .mso file
+The same as the .so request except that
+.I file
+is also searched in the tmac directories.
+.
+.REQ .na
+No output-line adjusting.
+.
+.REQ .ne
+Need a one-line vertical space.
+.
+.REQ .ne N
+Need
+.argument N
+vertical space (default scale indicator\ \c
+.scaleindicator v ).
+.
+.REQ .nf
+No filling or adjusting of output-lines.
+.
+.REQ .nh
+No hyphenation.
+.
+.REQ .nm
+Number mode off.
+.
+.REQ .nm \(+-N M S I
+In line number mode, set number, multiple, spacing, and indent.
+.
+.REQ .nn
+Do not number next line.
+.
+.REQ .nn N
+Do not number next
+.argument N
+lines.
+.
+.REQ .nr register \(+-N M
+Define or modify
+.argument register
+using
+.argument \(+-N
+with auto-increment
+.argument M .
+.
+.REQ .nroff
+Make the built-in condition
+.B n
+true and
+.B t
+false.
+.
+.REQ .ns
+Turn no-space mode on.
+.
+.REQ .nx filename
+Next file.
+.
+.REQ .open stream filename
+Open
+.register filename
+for writing and associate the stream named
+.register stream
+with it.
+.
+.REQ .opena stream filename
+Like
+.request .open
+but append to it.
+.
+.REQ .os
+Output vertical distance that was saved by the
+.request .sv
+request.
+.
+.REQ .pc
+Reset page number character to\ \c
+.'char % .
+.
+.REQ .pc c
+Page number character.
+.
+.REQ .pi program
+Pipe output to
+.argument program
+(nroff only).
+.
+.REQ .pl
+Set page length to default
+.scalednumber 11 i .
+The current page length is stored in
+.register .p .
+.
+.REQ .pl \(+-N
+Change page length to
+.argument \(+-N
+(default scale indicator\ \c
+.scaleindicator v ).
+.
+.REQ .pm
+Print macro names and sizes (number of blocks of 128 bytes).
+.
+.REQ ".pm t"
+Print only total of sizes of macros (number of 128 bytes blocks).
+.
+.REQ .pn \(+-N
+Next page number
+.argument N .
+.
+.REQ .pnr
+Print the names and contents of all currently defined number registers
+on stderr.
+.
+.REQ .po
+Change to previous page offset.  The current page offset is available in
+.register .o .
+.
+.REQ .po \(+-N
+Page offset
+.argument N .
+.
+.REQ .ps
+Return to previous point-size.
+.REQ .ps \(+-N
+Point size; same as
+.esc[arg] s \(+-N .
+.
+.REQ .psbb filename
+Get the bounding box of a PostScript image
+.argument filename .
+.
+.REQ .pso command
+This behaves like the
+.request .so
+request except that input comes from the standard output of
+.argument command .
+.
+.REQ .ptr
+Print the names and positions of all traps (not including input line
+traps and diversion traps) on stderr.
+.
+.REQ .rchar c1 c2...
+Remove the definitions of characters
+.argument c1 ,
+.argument c2 ,
+.argument ...
+.
+.REQ .rd prompt
+Read insertion.
+.
+.REQ .rj n
+Right justify the next
+.argument n
+input lines.
+.
+.REQ .rm name
+Remove request, macro, or string
+.argument name .
+.
+.REQ .rn old new
+Rename request, macro, or string
+.argument old
+to
+.argument new .
+.
+.REQ .rnn reg1 reg2
+Rename register
+.argument reg1
+to
+.argument reg2 .
+.
+.REQ .rr register
+Remove
+.argument register .
+.
+.REQ .rs
+Restore spacing; turn no-space mode off.
+.
+.REQ .rt \(+-N
+Return
+.I (upward only)
+to marked vertical place (default scale indicator\ \c
+.scaleindicator v ).
+.
+.REQ .shc
+Reset soft hyphen character to
+.esc (hy .
+.
+.REQ .shc c
+Set the soft hyphen character to
+.argument c .
+.
+.REQ .shift n
+In a macro, shift the arguments by
+.argument n \ \c
+positions.
+.
+.REQ .so filename
+Include source file.
+.
+.REQ .sp
+Skip one line vertically.
+.
+.REQ .sp N
+Space vertical distance
+.argument N
+up or down according to sign of
+.argument N
+(default scaling indicator\ \c
+.scaleindicator v ).
+.
+.REQ .special s1 s2 ...
+Fonts
+.argument s1 ,
+.argument s2 ,
+etc. are special and will be searched for characters not in the current font.
+.
+.REQ .ss N
+Space-character size set to
+.argument N /12
+of the spacewidth in the current font.
+.
+.REQ .ss N M
+Space-character size set to
+.argterm N /12
+and sentence space size set to
+.argterm M /12
+of the spacewidth in the current font (\f(CR\(eq1/3 em\fP).
+.
+.REQ .sty n style
+Associate
+.argument style
+with font position
+.argument n .
+.
+.REQ .substring register n1 n2
+Replace the string in
+.argument register
+with the substring defined by the indices
+.argument n1
+and
+.argument n2 .
+.
+.REQ .sv
+Save
+.scalednumber 1 v
+of vertical space.
+.
+.REQ .sv N
+Save the vertical distance
+.argument N
+for later output with
+.request .os
+request.
+.
+.REQ .sy command-line
+Execute program
+.argument command-line .
+.
+.REQ ".ta T" N
+Set tabs after every position that is a multiple of
+.argument N
+(default scaling indicator\ \c
+.scaleindicator m ).
+.REQ .ta n1 n2 ... nn \f(CBT\fP r1 r2 ... rn
+Set tabs at positions
+.argument n1 ,
+.argument n2 ,
+\&...,
+.argument nn ,
+then set tabs at
+.argument nn + r1 ,
+.argument nn + r2 ,
+\&...,
+.argument nn + rn ,
+then at
+.argument nn + rn + r1 ,
+.argument nn + rn + r2 ,
+\&...,
+.argument nn + rn + rn ,
+and so on.
+.
+.\".REQ .tar
+.\"Restore internally saved tab positions.
+.\".
+.\".REQ .tas
+.\"Save tab positions internally.
+.
+.REQ .tc
+Remove tab repition character.
+.REQ .tc c
+Set tab repetition character to\ \c
+.argument c .
+.
+.REQ .ti \(+-N
+Temporary indent next line (default scaling indicator\ \c
+.scaleindicator m ).
+.
+.REQ .tkf font s1 n1 s2 n2
+Enable track kerning for
+.argument font .
+.
+.REQ .tl \f(CB\(cq\fPleft\f(CB\(cq\fPcenter\f(CB\(cq\fPright\f(CB\(cq\fP
+Three-part title.
+.
+.REQ .trf filename
+Transparently output the contents of file
+.argument filename .
+.
+.REQ .tm anything
+Print
+.argument anything
+on terminal (UNIX standard message output).
+.
+.REQ .tr abcd....
+Translate
+.argument a
+to
+.argument b ,
+.argument c
+to
+.argument d ,
+etc. on output.
+.
+.REQ .trnt abcd....
+This is the same as the
+.request .tr
+request except that the translations do not apply to text that is
+transparently throughput into a diversion with
+.esc ! .
+.
+.REQ .troff
+Make the built-in condition
+.B t
+true and
+.B n
+false.
+.
+.REQ .uf font
+Underline font set to
+.argument font
+(to be switched to by
+.request .ul ).
+.
+.REQ .ul N
+Underline (italicize in troff)
+.argument N
+input lines.
+.
+.REQ .vpt n
+Enable vertical position traps if
+.argument n
+is non-zero, disable them otherwise.
+.
+.REQ .vs
+Change to previous vertical base line spacing.
+.
+.REQ .vs N
+Set vertical base line spacing to
+.argument N .
+Default value is
+.scalednumber 12 p .
+.
+.REQ .warn n
+Set warnings code to
+.argument n .
+.
+.REQ .wh N trap
+Set location trap; negative means from page bottom.
+.
+.REQ .while cond anything
+While condition
+.argument cond
+is true, accept
+.argument anything
+as input.
+.
+.REQ .write stream anything
+Write
+.argument anything
+to the stream named
+.argument stream .
+.
+.PD
+.LP
+Besides these standard groff requests, there might be further macro
+calls.
+They can originate from a macro package (see
+.BR roff (@MAN7EXT@)
+for an overview) or from a preprocessor.
+.LP
+Preprocessor macros are easy to be recognized.  They enclose their code
+into a pair of characteristic macros.
+.LP
+.TS
+box, center, tab (@);
+c | c | c
+CfCB | CfCB | CfCB.
+preprocessor@start macro@ end macro
+=
+eqn@.PS@.PE
+grap@.G1@.G2
+grn@.GS@.GE
+pic@.PS@.PE
+refer@.R1@.R2
+soelim@\fInone@\fInone
+tbl@.TS@.TE
+.TE
+.LP
+.
+.\" --------------------------------------------------------------------
+.SH "ESCAPE SEQUENCES"
+.\" --------------------------------------------------------------------
+.
+Escape sequences are in-line language elements usually introduced by
+a backslash
+.'char \(rs
+and followed by an escape name and sometimes by a required argument.
+Input processing is continued directly after the escaped character or
+the argument resp. without an intervening separation character.
+So there must be a way to determine the end of the escape name and the end
+of the argument.
+.LP
+This is done by enclosing names (escape name and arguments consisting of
+a variable name) by a pair of brackets
+.esc[] name
+and constant arguments (number expressions and characters) by apostrophes
+(ASCII 0x27) like
+.IR \(cqconstant\(cq .
+.LP
+There are abbreviations for short names.
+Two character escape names can be specified by an opening parenthesis like
+.esc( xy
+without a closing counterpart.
+And all one-character names different from the special characters
+.'char [
+and
+.'char (
+can even be specified without a marker in the form
+.esc \fP\f(CIc .
+.LP
+Constant arguments of length
+.number 1
+can omit the marker apostrophes, too, but there is no two-character
+analogue.
+.LP
+While 1-character escape sequences are mainly used for in-line functions
+and system related tasks, the 2-letter names following the
+.esc( ""
+construct are used for special characters predefined by the roff system.
+Names with more than two characters
+.esc[] name
+mostly denote user defined named characters (see the
+.request .char
+request).
+.
+.\" --------------------------------------------------------------------
+.SS "SINGLE CHARACTER ESCAPES"
+.\" --------------------------------------------------------------------
+.
+.PD 0
+.
+.\" --------- comments ---------
+.
+.ESC \(dq
+Beginning of a comment.
+Everything up to the end of the line is ignored.
+.
+.ESC #
+Everything up to and including the next newline is ignored.
+This is interpreted in copy mode.
+This is like
+.esc \(dq
+except the ignoring of the terminating newline.
+.
+.\" --------- strings ---------
+.
+.ESC * s
+The string stored in the string variable with 1-character name
+.argument s .
+.
+.ESC *( st
+The string stored in the string variable with 2-character name
+.argument st .
+.
+.ESC[] * stringvar
+The string stored in the string variable with arbitrary length name
+.argument stringvar .
+.
+.\" --------- macro arguments ---------
+.
+.ESC $0
+The name by which the current macro was invoked.  The
+.request .als
+request can make a macro have more than one name.
+.
+.ESC $ x
+Macro argument with 1-place number
+.argument x ,
+where
+.argument x
+is a digit between 1 and 9.
+.
+.ESC $( xy
+Macro argument with 2-digit number
+.argument xy .
+.
+.ESC[] $ nexp
+Macro argument with number
+.argument nexp ,
+where
+.argument nexp
+is a numerical expression evaluating to an integer \(>=1.
+.
+.ESC $*
+In a macro, the concatenation of all the arguments separated by spaces.
+.
+.ESC $@
+In a macro, the concatenation of all the arguments with each surrounded
+by double quotes, and separated by spaces.
+.
+.\" --------- escaped characters ---------
+.
+.ESC \(rs
+reduces to a single backslash; useful to delay its interpretation as
+escape character in copy mode.
+For a printable backslash, use
+.esc e .
+.
+.ESC \(cq
+The acute accent \(aa; same as
+.esc( aa .
+Unescaped: apostrophe, right quotation mark, single quote (ASCII 0x27).
+.
+.ESC `
+The grave accent \(ga; same as
+.esc( ga .
+Unescaped: left quote, backquote (ASCII 0x60).
+.
+.ESC \-
+The \- sign in the current font.
+.
+.ESC .
+An uninterpreted dot (period), even at start of line.
+.
+.ESC %
+Default optional hyphenation character.
+.
+.ESC !
+Transparent line indicator.
+.
+.ESC ? anything\fB?\fP
+In a diversion, this will transparently embed
+.argument anything
+in the diversion.
+.argument anything
+is read in copy mode.
+See also the escape sequences
+.esc !
+and
+.esc ? .
+.
+.
+.\" --------- spacing ---------
+.
+.ESC \& space
+Unpaddable space-size space character (no line break).
+.
+.ESC 0
+Digit width.
+.
+.ESC |
+1/6\ em narrow space character; zero width in nroff.
+.
+.ESC ^
+1/12\ em half-narrow space character; zero width in nroff.
+.
+.ESC &
+Non-printable, zero width character.
+.
+.ESC )
+Like
+.esc &
+except that it behaves like a character declared with the cflags
+request to be transparent for the purposes of end of sentence
+recognition.
+.
+.ESC /
+Increases the width of the preceding character so that the spacing
+between that character and the following character will be correct if
+the following character is a roman character.
+.
+.ESC ,
+Modifies the spacing of the following character so that the spacing
+between that character and the preceding character will correct if the
+preceding character is a roman character.
+.
+.ESC ~
+Unbreakable space that stretches like a normal inter-word space when a
+line is adjusted.
+.
+.ESC \& newline
+Ignored newline, for continuation lines.
+.
+.\" --------- structuring ---------
+.
+.ESC {
+Begin conditional input.
+.
+.ESC }
+End conditional input.
+.
+.\" --------- longer escape names ---------
+.
+.ESC ( st
+The special character with 2-character name
+.argument st ,
+see section
+.BR "SPECIAL CHARACTERS" .
+.
+.ESC[] \& name
+The named character with arbitrary length name
+.argument name .
+.
+.\" --------- alphabetical escapes ---------
+.
+.ESC a
+Non-interpreted leader character.
+.
+.ESCq A anything
+If
+.argument anything
+acceptable as name of a string, macro, diversion, register,
+environment or font it is
+.number 1
+otherwise
+.number 0 .
+.
+.ESCq b abc...
+Bracket building function.
+.
+.ESC c
+Interrupt text processing.
+.
+.ESCq C char
+The character called
+.argument char ;
+same as
+.esc[] char ,
+but compatible to other roff versions.
+.
+.ESC d
+Forward (down) 1/2 em vertical unit (1/2 line in nroff).
+.
+.ESCq D charseq
+Draw a graphical element defined by the characters in
+.argument charseq ;
+see groff info file for details.
+.
+.ESC e
+Printable version of the current escape character.
+.
+.ESC E
+Equivalent to an escape character, but is not interpreted in copy-mode.
+.
+.ESC f F
+Change to font with 1-character name or 1-digit number
+.argument F .
+.
+.ESC f( fo
+Change to font with 2-characer name or 2-digit number
+.argument fo .
+.
+.ESC[] f font
+Change to font with arbitrary length name or number expression
+.argument font .
+.
+.ESC[] g reg
+Return format of register with name
+.argument reg
+suitable for
+.request .af .
+Alternative forms
+.esc(arg g xy
+and
+.escarg g x .
+.
+.ESCq h N
+Local horizontal motion; move right
+.argument N
+(left if negative).
+.
+.ESCq H N
+Set height of current font to
+.argument N .
+.
+.ESC[] k reg
+Mark horizontal input place in register with arbitrary length name
+.argument reg .
+Alternative forms
+.esc(arg k xy
+and
+.escarg k x .
+.
+.ESCq l Nc
+Horizontal line drawing function (optionally using character
+.argument c ).
+.
+.ESCq L Nc
+Vertical line drawing function (optionally using character
+.argument c ).
+.
+.ESC n r
+The numerical value stored in the register variable with the 1-character
+name
+.argument r .
+.
+.ESC n( re
+The numerical value stored in the register variable with the 2-character
+name
+.argument re .
+.
+.ESC[] n reg
+The numerical value stored in the register variable with arbitrary
+lenght name
+.argument reg .
+.
+.ESCq N n
+Typeset the character with code
+.argument n
+in the current font, no special fonts are searched.  Useful for adding
+characters to a font using the
+.request .char
+request.
+.
+.ESCq o abc...
+Overstrike characters
+.argument a ,
+.argument b ,
+.argument c ,
+etc.
+.
+.ESC p
+Break and spread output line.
+.
+.ESC r
+Reverse 1\ em vertical motion (reverse line in nroff).
+.
+.ESCq R name \(+-n
+The same as
+.request .nr
+.argument name
+.argument \(+-n .
+.
+.ESC[] s \(+-N
+Set the point size to
+.I N
+scaled points.  Note the alternative forms
+.BI \(rss \(+- [ N ]\c
+,
+.BI \(rss' \(+-N '\c
+,
+.BI \(rss \(+- ' N '\c
+,
+.esc(arg s \(+-xy ,
+.BI \(rss \(+- ( xy\c
+,
+.escarg s \(+-x .
+Same as
+.request .ps
+request.
+.
+.ESCq S N
+Slant output
+.argument N
+degrees.
+.
+.ESC t
+Non-interpreted horizontal tab.
+.
+.ESC u
+Reverse (up) 1/2 em vertical motion (1/2 line in nroff).
+.
+.ESCq v N
+Local vertical motion; move down
+.argument N
+(up if negative).
+.
+.ESC[] V env
+The contents of the environment variable
+.argument env .
+Alternative forms
+.esc(arg V xy
+and
+.escarg V x .
+.
+.ESCq w string
+The width of the character sequence
+.argument string .
+.
+.ESCq x N
+Extra line-space function (negative before, positive after).
+.
+.ESCq X string
+Output
+.argument string
+as device control function.
+.
+.ESC[] Y name
+Output string variable or macro
+.argument name
+uninterpreted as device control function.
+Alternative forms
+.esc(arg Y xy
+and
+.escarg Y x .
+.
+.ESC z c
+Print
+.argument c
+with zero width (without spacing).
+.
+.ESCq Z anything
+Print
+.argument anything
+and then restore the horizontal and vertical position;
+.argument anything
+may not contain tabs or leaders.
+.PD
+.LP
+The escape sequences
+.esc e ,
+.esc . ,
+.esc \(dq ,
+.esc $ ,
+.esc * ,
+.esc a ,
+.esc n ,
+.esc t ,
+.esc g ,
+and
+.escarg \& newline
+are interpreted in copy mode.
+.LP
+Escape sequences starting with
+.esc (
+or
+.esc [
+do not represent single character escape sequences, but introduce escape
+names with two or more characters.
+.LP
+If a backslash is followed by a character that does not constitute a
+defined escape sequence the backslash is silently ignored and the
+character maps to itself.
+.
+.\" --------------------------------------------------------------------
+.SS "SPECIAL CHARACTERS"
+.\" --------------------------------------------------------------------
+Common special characters are predefined by escape sequences of the form
+.(esc \fP\f(CIxy
+with characters
+.argument x
+and
+.argument y .
+Some of these exist in the usual font while most of them are only
+available in the special font.  Below you'll find a selection of the most
+important glyphs; a complete list can be found in
+.BR groff_char (@MAN7EXT@).
+.RS
+.LP
+.PD 0
+.
+.ESc bu Bullet sign
+.ESc co Copyright
+.ESc ct Cent
+.ESc dd Double dagger
+.ESc de Degree
+.ESc dg Dagger
+.ESc em Em-dash
+.ESc hy Hyphen
+.ESc rg Registered sign
+.ESc sc Section sign
+.ESc ul Underline character
+.ESc == Identical
+.ESc >= Larger or equal
+.ESc <= Less or equal
+.ESc != Not equal
+.ESc -> Right arrow
+.ESc <- Left arrow
+.ESc +- Plus-minus sign
+.PD
+.RE
+.
+.\" --------------------------------------------------------------------
+.SH REGISTERS
+.\" --------------------------------------------------------------------
+Registers are variables that store a value.
+In groff, most registers store numerical values (see section
+.B NUMERICAL EXPRESSIONS
+above), but some can also hold a string value.
+.LP
+Each register is given a name.
+Arbitrary registers can be defined and set with the request
+.request .nr
+.argument register .
+.LP
+The value stored in a register can be retrieved by the escape sequences
+introduced by
+.esc n .
+.LP
+Most useful are predefined registers.
+In the following the notation
+.argument name
+is used to refer to a register called
+.register name
+to make clear that we speak about registers.
+Please keep in mind that the
+.esc en[]
+decoration is not part of the register name.
+.
+.\" --------------------------------------------------------------------
+.SS "READ-ONLY REGISTERS"
+.\" --------------------------------------------------------------------
+The following registers have predefined values that should not be
+modified by the user (usually, registers starting with a dot a read-only).
+Mostly, they provide information on the current settings or store results
+from request calls.
+.LP
+.PD 0
+.REG .$ Number of arguments in the current macro.
+.REG .A
+Set to
+.number 1
+in
+.B troff
+if option
+.B \-A
+is used; always
+.number 1
+in
+.BR nroff .
+.REG .H Available horizontal resolution in basic units.
+.REG .T
+Set to
+.number 1
+if option
+.B \-T
+is used.
+.REG .V Available vertical resolution in basic units.
+.REG .a
+Post-line extra line-space most recently utilized using
+.escarg x 'N' .
+.REG .C 1 if compatibility mode is in effect, 0 otherwise.
+.REG .c Current input line number.
+.REG .cdp
+The depth of the last character added to the current environment.
+It is positive if the character extends below the baseline.
+.REG .ce
+The number of lines remaining to be centered, as set by the
+.request .ce
+request.
+.REG .cht
+The height of the last character added to the current environment.
+It is positive if the character extends above the baseline.
+.REG .csk
+The skew of the last character added to the current environment.
+The skew of a character is how far to the right of the center of a character
+the center of an accent over that character should be placed.
+.REG .d
+Current vertical place in current diversion; equal to register
+.register nl .
+.REG .ev The name or number of the current environment (string-valued).
+.REG .f Current font number.
+.REG .fam  The current font family (string-valued).
+.REG .fp The number of the next free font position.
+.REG .g
+Always 1 in GNU troff.
+Macros should use it to test if running under groff.
+.REG .h Text base-line high-water mark on current page or diversion.
+.REG .hla
+The current hyphenation language as set by the
+.B .hla
+request.
+.REG .hlc
+The number of immediately preceding consecutive hyphenated lines.
+.REG .hlm
+The maximum allowed number of consecutive hyphenated lines, as set by
+the
+.request .hlm
+request.
+.REG .hy
+The current hyphenation flags (as set by the
+.request .hy
+request).
+.REG .hym
+The current hyphenation margin (as set by the
+.request .hym
+request).
+.REG .hys
+The current hyphenation space (as set by the
+.request .hys
+request).
+.REG .i Current ident.
+.REG .in The indent that applies to the current output line.
+.REG .kern
+.number 1
+if pairwise kerning is enabled,
+.number 0
+otherwise.
+.REG .l Current line length.
+.REG .lg
+The current ligature mode (as set by the
+.request .lg
+request).
+.REG .ll The line length that applies to the current output line.
+.REG .lt
+The title length (as set by the
+.request .lt
+request).
+.REG .n Length of text portion on previous output line.
+.REG .ne
+The amount of space that was needed in the last
+.request .ne
+request that caused a trap to be sprung.
+Useful in conjunction with
+.register .trunc .
+.REG .o Current page offset.
+.REG .p Current page length.
+.REG .pn
+The number of the next page: either the value set by a
+.request .pn
+request, or the number of the current page plus\ 1.
+.REG .ps The current pointsize in scaled points.
+.REG .psr The last-requested pointsize in scaled points.
+.REG .rj
+The number of lines to be right-justified as set by the rj request.
+.REG .s Current point size as a decimal fraction.
+.REG .sr
+The last requested pointsize in points as a decimal fraction
+(string-valued).
+.REG .t Distance to the next trap.
+.REG .tabs
+A string representation of the current tab settings suitable for use as
+an argument to the
+.request .ta
+request.
+.REG .trunc
+The amount of vertical space truncated by the most recently sprung
+vertical position trap, or, if the trap was sprung by a
+.request .ne
+request, minus the amount of vertical motion produced by
+.request .ne .
+request.
+In other words, at the point a trap is sprung, it represents the difference
+of what the vertical position would have been but for the trap, and what the
+vertical position actually is.
+Useful in conjunction with the
+.register .ne
+register.
+.REG .ss
+The value of the parameters set by the first argument of the
+.request .ss
+request.
+.REG .sss
+The value of the parameters set by the second argument of the
+.request .ss
+request.
+.REG .u Equal to 1 bin fill mode and 0 in nofill mode.
+.REG .v Current vertical line spacing.
+.REG .vpt
+.number 1
+if vertical position traps are enabled,
+.number 0
+otherwise.
+.REG .w Width of previous character.
+.REG .warn
+The sum of the number codes of the currently enabled warnings.
+.REG .x The major version number.
+.REG .y The minor version number.
+.REG .Y The revision number of groff.
+.REG .z Name of current diversion.
+.REG llx
+Lower left x-coordinate (in PostScript units) of a given PostScript
+image (set by
+.request .psbb ).
+.REG lly
+Lower left y-coordinate (in PostScript units) of a given PostScript
+image (set by
+.request .psbb ).
+.REG rsb Like
+.register sb ,
+but takes account of the heights and depths of characters.
+.REG rst
+Like
+.register st ,
+but takes account of the heights and depths of characters.
+.REG sb
+Depth of string below base line (generated by width function
+.esc w ).
+.REG skw
+Right skip width from the center of the last character in the
+.esc w
+argument.
+.REG ssc
+The amount of horizontal space (possibly negative) that should be added
+to the last character before a subscript (generated by width function
+.esc w ).
+.REG st
+Height of string above base line (generated by width function
+.esc w ).
+.REG urx
+Upper right x-coordinate (in PostScript units) of a given PostScript
+image (set by
+.request .psbb ).
+.REG ury
+Upper right y-coordinate (in PostScript units) of a given PostScript
+image (set by
+.request .psbb ).
+.PD
+.
+.\" --------------------------------------------------------------------
+.SS "WRITABLE REGISTERS"
+.\" --------------------------------------------------------------------
+The following registers can be read and written by the user.
+They have predefined default values, but these can be modified for
+customizing a document.
+.LP
+.PD 0
+.REG % Current page number.
+.REG c. Current input line number.
+.REG ct Character type (set by width function
+.esc w ).
+.REG dl Maximal width of last completed diversion.
+.REG dw Current day of week (1-7).
+.REG dy Current day of month (1-31).
+.REG hp Current horizontal position at input line.
+.REG ln Output line number.
+.REG mo Current month (1-12).
+.REG nl Vertical position of last printed text base-line.
+.REG slimit
+If greater than 0, the maximum number of objects on the input stack.
+If \(<=0 there is no limit, i.e., recursion can continue until virtual
+memory is exhausted.
+.REG systat
+The return value of the
+.I system()
+function executed by the last
+.request .sy
+request.
+.REG year The current year (year 2000 compliant).
+.REG yr
+Current year minus 1900.  For Y2K compliance use register
+.register year
+instead.
+.PD
+.
+.\" --------------------------------------------------------------------
+.SH WARNINGS
+.\" --------------------------------------------------------------------
+Each warning generated by groff is identified by a name and a code
+number.  The codes are powers of 2 to allow bit-encoding with a single
+integer.  There are also names that can be used to refer to groups of
+warnings.
+.LP
+The name associated with a warning is used by the
+.option \-w
+and
+.option \-W
+options;
+the number code is used by the
+.request .warn
+request and by the
+.esc[arg] n warn
+register.
+.LP
+.PD 0
+.Warning all group
+All warnings except
+.warning di ,
+.warning mac
+and
+.warning reg .
+Intended to cover all warnings with traditional macro packages.
+.Warning break 4
+In fill mode, lines which could not be broken so that their length was
+less than the line length.  This is enabled by default.
+.Warning char 1
+Non-existent characters.  This is enabled by default.
+.Warning delim 8
+Missing or mismatched closing delimiters.
+.Warning di 256
+Use of
+.request .di
+or
+.request .da
+without an argument when there is no current diversion.
+.Warning el 16
+Use of the
+.request .el
+request with no matching
+.request .ie
+request.
+.Warning escape 32768
+Unrecognized escape sequence.  Then the escape character is ignored.
+.Warning font 131072
+Non-existent fonts.  This is enabled by default.
+.Warning ig 262144
+Illegal escapes in text ignored with the
+.request \.ig
+request.  These are conditions that are errors when they occur outside
+of ignored text.
+.Warning mac 512
+Use of undefined strings, macros, and diversions.  Automatically handled
+as empty.  Usually, only one warning per name.
+.Warning missing 8192
+Request that is missing non-optional arguments.
+.Warning input 16384
+Illegal input character.
+.Warning number 2
+Invalid numeric expressions.  This is enabled by default.
+.Warning range 64
+Out of range arguments.
+.Warning reg 1024
+Use of undefined number register.  Automatically defined as having
+value 0.  Usually, only one warning per name.
+.Warning right-brace 4096
+Use of
+.esc }
+where a number was expected.
+.Warning scale 32
+Meaningless scaling indicators.
+.Warning space 65536
+Missing space between a request or macro and its argument.  Then no
+macro is automatically defined.  This is enabled by default.  This
+warning will never occur in compatibility mode.
+.Warning syntax 128
+Dubious syntax in numeric expressions.
+.Warning tab 2048
+Inappropriate use of a tab character (either in an unquoted macro
+argument or where a number was expected).
+.Warning w group
+All warnings.
+.PD
+.LP
+.TS
+tab(@), box, expand;
+c c c | c  c  c | c  c  c
+R RI CB | R RI CB | R RI CB.
+Bit@Code@Warning@Bit@Code@Warning@Bit@Code@Warning
+_
+0@1@char@8@256@di@16@65536@space
+1@2@number@9@512@mac@17@131072@font
+2@4@break@10@1024@reg@18@262144@ig
+3@8@delim@11@2048@tab
+4@16@el@12@4096@right-brace
+5@32@scale@13@8192@missing
+6@64@range@14@16384@input
+7@128@syntax@15@32768@escape
+.TE
+.LP
+.
+.\" --------------------------------------------------------------------
+.SH COMPATIBILITY
+.\" --------------------------------------------------------------------
+.I groff
+provides a
+.B compatibility mode
+that allows to process roff code written for classical
+.troff
+or for other implementations of roff in a consistent way.
+.LP
+Compatibility mode can be turned on with the
+.option \-C
+command line option, and turned on or off with the
+.request .cp
+request.  The number register
+.esc(arg n .C
+is
+.number 1
+if compatibility mode is on,
+.number 0
+otherwise.
+.LP
+This became necessary because the GNU concept for long names causes some
+incompatibilities.
+.I Classical troff
+will interpret
+.IP
+.B
+\&.dsabcd
+.LP
+as defining a string
+.B ab
+with contents
+.BR cd .
+Normally,
+.I groff
+will interpret this as a call of a macro named
+.request dsabcd .
+.LP
+Also
+.I classical troff
+will interpret
+.esc *[
+or
+.esc n[
+as references to a string or number register called
+.register [ .
+In
+.I GNU native
+.IR mode ,
+however, this will normally be interpreted as the start of a long name.
+.LP
+In
+.I compatibility
+.IR mode ,
+groff will interpret these things in the traditional way, but long names
+are not recognized.
+.LP
+On the other hand, groff in
+.I GNU native mode
+does not allow to use the escape sequences
+.esc e ,
+.esc | ,
+.esc ^ ,
+.esc & ,
+.esc } ,
+.esc { ,
+.esc "\ " (space),
+.esc ' ,
+.esc ` ,
+.esc - ,
+.esc _ ,
+.esc ! ,
+.esc % ,
+and
+.esc c
+in names of strings, macros, diversions, number registers, fonts or
+environments, whereas
+.I classical troff
+does.  The
+.esc A
+escape sequence can be helpful in avoiding these escape sequences in
+names.
+.LP
+Fractional pointsizes cause one noteworthy incompatibility.
+In
+.I classical
+.IR troff ,
+the
+.request .ps
+request ignores scale indicators and so
+.RS
+.LP
+.B .ps\ 10u
+.RE
+.LP
+will set the pointsize to 10 points, whereas in groff native mode the
+pointsize will be set to 10 scaled points.
+.LP
+In
+.I groff
+mode, there is a fundamental difference between unformatted input
+characters, and formatted output characters.
+Everything that affects how an output character will be output is stored
+with the character; once an output character has been constructed it is
+unaffected by any subsequent requests that are executed, including the
+.request .bd ,
+.request .cs ,
+.request .tkf ,
+.request .tr ,
+or
+.request .fp
+requests.
+.LP
+Normally output characters are constructed from input characters at the
+moment immediately before the character is added to the current output
+line.
+Macros, diversions and strings are all, in fact, the same type of object;
+they contain lists of input characters and output characters in any
+combination.
+.LP
+An output character does not behave like an input character for the
+purposes of macro processing; it does not inherit any of the special
+properties that the input character from which it was constructed might
+have had.
+The following example will make things clearer.
+.LP
+.RS
+.nf
+.ft B
+\&.di x
+\(rs\(rs\(rs\(rs
+\&.br
+\&.di
+\&.x
+.ft
+.fi
+.RE
+.LP
+In
+.I GNU mode
+this will be printed as
+.esc \(rs .
+So each pair of input backslashes
+.'char \(rs\(rs
+is turned into a single output backslash
+.'char \(rs
+and the resulting output backslashes are not interpreted as escape
+characters when they are reread.
+.LP
+.I Classical troff
+would interpret them as escape characters when they were reread and
+would end up printing a single backslash
+.'char \(rs .
+.LP
+The correct way to get a printable
+.'char \(rs
+is to use the
+.esc e
+escape sequence.  This will always print a single instance of the
+current escape character, regardless of whether or not it is used in a
+diversion.  It will also work in both GNU mode and compatibility mode.
+.LP
+To store an escape sequence in a diversion that will be interpreted when
+the diversion is reread, either the traditional
+.esc !
+transparent output facility or the
+new
+.esc ?
+escape sequence can be used.
+.
+.\" --------------------------------------------------------------------
+.SH BUGS
+.\" --------------------------------------------------------------------
+At the moment, the documentation of the groff system is in a state of
+change and evolution.  It is possible that there are small
+inconsistencies between different documents temporarily.
+.LP
+The
+.B WARNINGS
+section belongs to
+.BR troff (@MAN1EXT@).
+.
+.\" --------------------------------------------------------------------
+.SH AUTHOR
+.\" --------------------------------------------------------------------
+This document is part of groff, the GNU roff distribution.  It was
+written by Bernd Warken <bwarken@mayn.de>.
+.LP
+It 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 under
+.RS
+.LP
+.IR http://www.gnu.org/copyleft/fdl.html .
+.RE
+.LP
+Formerly, the extensions of the groff language were kept in the manual
+page
+.BR troff (@MAN1EXT@).
+This document contains the essential parts of that documentation, but
+the gory details are found in the groff info file.
+.
+.\" --------------------------------------------------------------------
+.SH "SEE ALSO"
+.\" --------------------------------------------------------------------
+The main source of information for the groff language is the
+.B groff
+.BR info (1)
+file.
+.LP
+For a survey of roff and the groff system and further documentation
+pointers see
+.BR roff (@MAN7EXT@).
+.LP
+The formatter programs are described in
+.BR groff (@MAN1EXT@)
+and
+.BR troff (@MAN1EXT@);
+a complete of all predefined glyph names can be found in
+.BR groff_char (@MAN7EXT@).
+.LP
+The classical
+.I troff
+documentation is available on-line at
+.RS
+.LP
+.I http://cm.bell-labs.com/cm/cs/cstr.html
+.RE
+and
+.RS
+.IR http://www.kohala.com/start/troff/ .
diff --git a/contrib/groff/man/groff_char.man b/contrib/groff/man/groff_char.man
index 18085dc..fd9f4ce 100644
--- a/contrib/groff/man/groff_char.man
+++ b/contrib/groff/man/groff_char.man
@@ -1,5 +1,5 @@
 .ig \"-*- nroff -*-
-Copyright (C) 1989-1995 Free Software Foundation, Inc.
+Copyright (C) 1989-2000 Free Software Foundation, Inc.
 
 Permission is granted to make and distribute verbatim copies of
 this manual provided the copyright notice and this permission notice
@@ -45,7 +45,9 @@ This manual page lists the standard
 .B groff
 input characters.
 Only the characters that are available for the device that
-is being used to print this manual page will be displayed.
+is being used to print or view this manual page will be
+.ie \n(.g displayed (the device currently used is `\*(.T').
+.el displayed.
 The
 .I "Input code"
 column applies to characters which can be
@@ -379,6 +381,7 @@ Output	Input	Input	PostScript	Notes
 .C2 OK \& "check mark, tick"
 .C2 Of ordfeminine
 .C2 Om ordmasculine
+.C2 pc periodcentered
 .C2 S1 onesuperior
 .C2 S2 twosuperior
 .C2 S3 threesuperior
@@ -399,7 +402,7 @@ Output	Input	Input	PostScript	Notes
 .C2 br br "box rule with traditional troff metrics"
 .C2 ru ru "baseline rule"
 .C2 ul ul "underline with traditional troff metrics"
-.C2 bv bv "bold vertical"
+.C2 bv bv "bar vertical"
 .C2 bs bell
 .C2 ci circle
 .C2 bu bullet
@@ -436,7 +439,9 @@ Output	Input	Input	PostScript	Notes
 .C2 lq quotedblleft
 .C2 rq quotedblright
 .C2 oq quoteleft "single open quote"
+.C2 cq quoteright "single closing quote (ASCII 39)"
 .C2 aq quotesingle "apostrophe quote"
+.C2 dq quotedbl "double quote (ASCII 34)"
 .C2 or bar
 .C2 at at
 .C1 - minus "minus sign from current font"
@@ -533,6 +538,9 @@ Output	Input	Input	PostScript	Notes
 .C2 ib reflexsubset
 .C2 ip reflexsuperset
 .C2 ap similar
+.C2 is integral
+.C2 sr radical "square root"
+.C2 rn \& overline
 .C2 pd partialdiff "partial differentiation sign"
 .C2 c* circlemultiply "multiply sign in a circle"
 .C2 c+ circleplus "plus sign in a circle"
@@ -549,8 +557,8 @@ Output	Input	Input	PostScript	Notes
 .C2 CR carriagereturn "carriage return symbol"
 .C2 st suchthat
 .C2 /_ angle
-.C2 << "" "much less"
-.C2 >> "" "much greater"
+.C2 << \& "much less"
+.C2 >> \& "much greater"
 .C2 wp weierstrass "Weierstrass p"
 .C2 lz lozenge
 .C2 an arrowhorizex "horizontal arrow extension"
diff --git a/contrib/groff/man/groff_font.man b/contrib/groff/man/groff_font.man
index 97b6480..8b9e3b4 100644
--- a/contrib/groff/man/groff_font.man
+++ b/contrib/groff/man/groff_font.man
@@ -130,6 +130,16 @@ will cause no font to be mounted on the corresponding font position.
 The default font family is
 .IR fam .
 .TP
+.B use_charnames_in_special
+This command indicates that troff should encode named characters inside
+special commands.
+.TP
+.B pass_filenames
+requests that troff tells the driver the source file name being processed.
+This is achieved by another tcommand:
+.B F
+.IR filename .
+.TP
 .B charset
 This line and everything following in the file are ignored.
 It is allowed for the sake of backwards compatibility.
@@ -139,6 +149,13 @@ Other commands are ignored by
 .B troff
 but may be used by postprocessors to store arbitrary information
 about the device in the DESC file.
+.LP
+Here a list of obsolete keywords which are recognized by
+.B groff
+but completely ignored:
+.BR spare1 ,
+.BR spare2 ,
+.BR biggestfont .
 .SS Font file format
 A font file has two sections. The first section is a sequence
 of lines each containing a sequence of blank delimited
@@ -165,7 +182,8 @@ Characters
 are ligatures; possible ligatures are
 .BR ff ,
 .BR fi ,
-.BR fl 
+.BR fl ,
+.B ffi
 and
 .BR ffl .
 For backwards compatibility, the list of ligatures may be terminated
@@ -209,8 +227,10 @@ Each line gives information for one character.
 A line comprises a number of fields separated
 by blanks or tabs. The format is
 .IP
-.I
-name metrics type code comment
+.I name metrics type code 
+.RI [ entity_name ]
+.RB [ --
+.IR comment ]
 .LP
 .I name
 identifies the character:
@@ -279,7 +299,16 @@ or
 .B 0X
 it will be intepreted as hexadecimal.
 .LP
-Anything on the line after the code field will be ignored.
+The
+.I entity_name
+field gives an ascii string identifying the glyph which the postprocessor
+uses to print the character.
+This field is optional and has been introduced so that the html device driver
+can encode its character set.
+For example, the character `\e[Po]' is represented as `&pound;' in html 4.0.
+.LP
+Anything on the line after the encoding field resp. after `-\&-' will
+be ignored.
 .LP
 The
 .I metrics
diff --git a/contrib/groff/man/roff.man b/contrib/groff/man/roff.man
new file mode 100644
index 0000000..793ce61
--- /dev/null
+++ b/contrib/groff/man/roff.man
@@ -0,0 +1,520 @@
+.\"                        -*- nroff -*- 
+.ig
+roff.7
+
+This file is part of groff, the GNU roff type-setting system.
+
+Copyright (C) 2000 Free Software Foundation, Inc.
+written by Bernd Warken <bwarken@mayn.de>
+
+Last update: 17 May 2000
+
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.1 or
+any later version published by the Free Software Foundation; with the
+Invariant Sections being this .ig-section and AUTHOR, with no
+Front-Cover Texts, and with no Back-Cover Texts.
+
+A copy of the Free Documentation License is included as a file called
+FDL in the main directory of the groff source package.
+..
+.
+.\" --------------------------------------------------------------------
+.\" Setup
+.\" --------------------------------------------------------------------
+.
+.if n \{\
+.  mso tmac.tty-char
+.  ftr CR R
+.  ftr CI I
+.  ftr CB B
+.\}
+.
+.\" text lines in macro definitions or bracketed sections \{...\}
+.de text
+.  if 1 \&\\$*\&
+..
+.
+.de option
+.  ds @tmp@ \f(CB\\$1\fP
+.  shift 1
+.  text \\*[@tmp@]\\$*
+.  rm @tmp@
+..
+.
+.de 'char
+.  ds @tmp@ `\f(CB\\$1\fP'
+.  shift
+.  text \\*[@tmp@]\\$*
+.  rm @tmp@
+..
+.
+.de esc
+.  ds @tmp@ \f(CB\e\\$1\fP
+.  shift
+.  text \\*[@tmp@]\\$*
+.  rm @tmp@
+..
+.
+.de argname
+.  ds @tmp@ \f(CI\\$1\fP
+.  shift 1
+.  text \\*[@tmp@]\\$*
+.  rm @tmp@
+..
+.
+.de prefixednumber
+.  ds @tmp@ \&\\$1\ \f(CR\\$2\fP
+.  shift 2
+.  text \\*[@tmp@]\\$*
+.  rm @tmp@
+..
+.
+.\" --------------------------------------------------------------------
+.\" Title
+.\" --------------------------------------------------------------------
+.TH ROFF @MAN7EXT@ "@MDATE@" "Groff Version @VERSION@"
+.SH NAME
+roff \- a survey of the roff typesetting system
+.\" --------------------------------------------------------------------
+.SH DESCRIPTION
+.\" --------------------------------------------------------------------
+.I roff
+is the general name for a set of type-setting programs, known under
+names like
+.IR troff ,
+.IR nroff ,
+.IR groff ,
+etc.
+.LP
+The roff type-setting system consists of a formatting language, macro
+packages, preprocessors, postprocessors for output devices, user
+front-end programs, and conversion tools.
+.LP
+The most common roff system today is the free software implementation
+.I groff
+(from `GNU\ roff').
+The pre-groff implementations are referred to as `classical' (dating
+back as long as 1973).
+.LP
+.I groff
+is backward-compatible to its classical ancestors, but has many
+extensions, and is still evolving.
+As it is available for almost every computer system it is the de-facto
+roff standard today.
+.LP
+In spite of its age, roff is in wide use today, e.g., the manual pages
+on UNIX systems
+.RI ( man-pages )
+are written in roff.
+The roff output for text devices is still unmatched, and its graphical
+output has the same quality as the other free type-setting programs and
+is better than some of the commercial systems.
+.LP
+This document gives only an overview and provides pointers to further
+documentation.
+
+This document is not maintained and might be out of date.  For the real
+documentation refer to the groff info file that contains the detailed,
+actual and concise reference information.
+.\" --------------------------------------------------------------------
+.SH "FORMATTING LANGUAGE"
+.\" --------------------------------------------------------------------
+There are three terms that refer to the language of the
+.I roff
+system.
+The term
+.I troff language
+is used when the classical aspects of
+.I roff
+are stressed, the term
+.I groff language
+includes the GNU extensions, whereas
+.I roff language
+is the general term.
+.LP
+The main source of documentation for all aspects of the
+.I groff language
+is the groff info file.  The manual page
+.BR groff (@MAN7EXT@)
+gives a short description of all predefined language elements.
+.LP
+Documents using roff are normal text files decorated by formatting
+elements.
+It is very easy to write high-quality documents by using one of the
+macro packages.
+These are like high-level programming languages, while the bare roff
+language compares to a low-level language like C or assembler.
+.LP
+The roff language is a full programming language providing low-level
+requests, definition of macros, escape sequences, string variables,
+number or size registers, and C-like flow controls.
+.ig /
+In the 1980s, it was even possible to write the common utilities for
+system administration by only using troff.
+There were contests on writing the most unreadable program fake by
+exclusively using troff.
+Because of security impacts, these dangerous features were removed in
+.IR groff .
+./
+.LP
+Some clarification on the language elements seems to be wanted.
+Requests are basic formatting commands defined by programming languages
+like C, C++, etc., whereas macros are formatting commands that are
+written in the roff language.
+A document writer will not note any difference in usage for requests or
+macros, both are written on a line on their own starting with a dot
+.'char . .
+But the user may define her own macros if desired.
+.LP
+Escape sequences are in-line elements starting with a backslash
+.'char \e .
+They are used to implement various features, including the insertion of
+non-ASCII characters with
+.esc ( ,
+the content of strings with
+.esc *
+and register variables with
+.esc n ,
+font changes with
+.esc f ,
+in-line comments with
+.esc \(dq ,
+the escaping of special control characters like
+.esc \e ,
+and many other features.
+.\" --------------------------------------------------------------------
+.SH FORMATTERS
+.\" --------------------------------------------------------------------
+Formatters are the front-end programs that analyze a groff document and
+translate it into a form that is suitable for a special device.
+The traditional
+.I roff
+had two formatters,
+.B nroff
+for text devices and
+.B troff
+for graphical devices.
+.LP
+These programs still exist in the
+.I groff
+implementation, but usually they are accessed through a program called
+.BR groff .
+This combined and extended the old functionality into a single program.
+It has many command-line options, most of them herited from
+.BR troff .
+To ease the option jungle, the user-friendly utility
+.B grog
+(from `groff guess') was created.
+It tries to guess from the document which arguments should be used and
+displays a suitable command line.
+Though not being perfect, it is a good starting point.
+.\" --------------------------------------------------------------------
+.SH PREPROCESSORS
+.\" --------------------------------------------------------------------
+The classical preprocessors that are still available in groff.
+.RS
+.LP
+.PD 0
+.TP
+.I eqn
+for including mathematical equations.
+.TP
+.I grap
+for constructing graphical elements (this preprocessor doesn't come with
+groff; it is an extra package).
+.TP
+.I grn
+for including gremlin pictures.
+.TP
+.I pic
+for creating diagrams.
+.TP
+.I refer
+for bibliographic references.
+.TP
+.I soelim
+for including other roff files.
+.TP
+.I tbl
+for rectangular tables.
+.PD
+.RE
+.LP
+Each of these preprocessors defines its own language that is translated
+into roff code when run through the preprocessor program.
+So parts written in these languages may be included within a roff
+document.
+Such an enhanced document is run through one or more corresponding
+preprocessors before it is fed into the actual formatter.
+.LP
+The preprocessor programs extract and transform the document parts
+determined for them.
+They can be called either in a UNIX pipeline with their program name or
+automatically with a groff option.
+.LP
+.TS
+center, box, tab (@);
+C | C
+CfCB | CfCB.
+preprocessor@groff option
+=
+eqn@\-e
+grap@\-G
+grn@\-g
+pic@\-p
+refer@\-R
+tbl@\-r
+soelim@\-s
+.TE
+.LP
+.
+.\" --------------------------------------------------------------------
+.SH "MACRO PACKAGES"
+.\" --------------------------------------------------------------------
+Macro packages are collections of macros that are suitable to format a
+special kind of documents in a convenient way.
+This greatly eases the usage of roff.
+The macro definitions of a package are kept in a file called
+.BI tmac. name
+where
+.I name
+is the internal roff name for this package.
+All tmac files are stored in a single or few directories at standard
+positions.
+.LP
+A macro package that is used in a document is specified by the command line
+option
+.option \-m
+for the formatter like
+.option "troff\ \-m"
+.argname name
+or
+.option "groff\ \-m"
+.argname name .
+General details on the naming of macro packages and their placement is
+found in
+.BR tmac (@MAN5EXT@).
+.LP
+Famous classical macro packages are
+.IR man ,
+.IR mandoc ,
+and
+.I mdoc
+for manual pages and
+.IR me ,
+.IR ms ,
+and
+.I mm
+for books, articles, and letters.
+Besides these collections, groff provides an increasing number of new
+macro packages for various applications, for example integration of or
+conversion into other file formats.
+.\" --------------------------------------------------------------------
+.SH "FILE NAME EXTENSIONS"
+.\" --------------------------------------------------------------------
+Manual pages (man-pages) take the section number as a file name
+extension, e.g., the filename for this document is
+.IR roff.7 ,
+i.e., it is kept in
+.prefixednumber section 7
+of the man-pages.
+.LP
+The classical macro packages take the package name as an extension, e.g.
+.IB file. me
+for a document using the
+.I me
+macro package,
+.IB file. mm
+for
+.IR mm ,
+.IB file. ms
+for
+.IR ms ,
+.IB file. pic
+for
+.I pic
+files,
+etc.
+.ig
+.LP
+But there is no general naming scheme for roff documents, though
+.IB file. roff
+or
+.IB file. rof
+seems to be a good choice.
+.LP
+File name extensions can be very handy in conjunction with the
+.BR less (1)
+pager.
+It provides the possibility to feed all input into a command-line pipe that
+is specified in the shell environment variable
+.B LESSOPEN
+This process is not well documented, so here an example
+.B LESSOPEN='|lesspipe %s'
+where
+.B lesspipe
+is either a system supplied command or a shell script of your own.
+..
+.\" --------------------------------------------------------------------
+.SH EDITING
+.\" --------------------------------------------------------------------
+Most text editors provide support for editing documents using roff.
+Especially useful is the
+.B nroff-mode
+in all flavors of the Emacs editor.
+.\" --------------------------------------------------------------------
+.SH ENVIRONMENT
+.\" --------------------------------------------------------------------
+.TP
+.SM
+.B GROFF_TMAC_PATH
+A colon separated list of directories in which to search for
+macro files, see
+.BR tmac (@MAN5EXT@).
+.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.
+.B troff
+will search in directories given in the
+.option \-F
+option before these, and in standard directories
+.RB ( .:/usr/local/share/groff/font:/usr/lib/font )
+after these.
+.\" --------------------------------------------------------------------
+.SH FILES
+.\" --------------------------------------------------------------------
+By default,
+.I groff
+installs all of its library files in a directory tree under
+.IR /usr/local/share/groff .
+This location might vary for different systems.
+In the following, this directory is referred to as
+.IR <groff_dir> .
+.LP
+.TP
+.IB <groff_dir> /tmac/troffrc
+Initialization file for troff.
+.TP
+.IB <groff_dir> /tmac/tmac. name
+Macro files.
+.TP
+.IB <groff_dir> /font/dev name /DESC
+Device description file for device
+.IR name .
+.TP
+.IB <groff_dir> /font/dev name / F
+Font file for font
+.I F
+of device
+.IR name .
+.\" --------------------------------------------------------------------
+.SH BUGS
+.\" --------------------------------------------------------------------
+The groff documentation is in evolution at the moment.
+It is possible that small inconsistencies between different documents exist
+temporarily.
+.\" --------------------------------------------------------------------
+.SH AUTHOR
+.\" --------------------------------------------------------------------
+This document is part of groff, the GNU roff distribution.  It was
+written by Bernd Warken <bwarken@mayn.de>.
+.LP
+It 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 under
+.RS
+.LP
+.IR <http://www.gnu.org/copyleft/fdl.html> .
+.RE
+.\" --------------------------------------------------------------------
+.SH "SEE ALSO"
+.\" --------------------------------------------------------------------
+The main source of information is the
+.I groff
+.BR info (1)
+file.
+.LP
+The predefined elements of the
+.I groff
+language are also documented in the manual page
+.BR groff (@MAN7EXT@).
+.LP
+Formatters and their wrappers:
+.BR groff (@MAN1EXT@),
+.BR grog (@MAN1EXT@),
+.BR nroff (@MAN1EXT@),
+and
+.BR troff (@MAN1EXT@).
+.LP
+Postprocessors for the output devices:
+.BR grodvi (@MAN1EXT@),
+.BR grohtml (@MAN1EXT@),
+.BR grolbp (@MAN1EXT@),
+.BR grolj4 (@MAN1EXT@),
+.BR grops (@MAN1EXT@),
+and
+.BR grotty (@MAN1EXT@).
+.LP
+Standard preprocessors:
+.BR eqn (@MAN1EXT@),
+.BR grn (@MAN1EXT@),
+.BR grap (1),
+.BR pic (@MAN1EXT@),
+.BR refer (@MAN1EXT@),
+.BR soelim (@MAN1EXT@),
+and
+.BR tbl (@MAN1EXT@).
+.LP
+The man pages for macro packages include
+.BR groff_tmac (@MAN5EXT@),
+.BR groff_man (@MAN7EXT@),
+.BR groff_markup (@MAN7EXT@),
+.BR groff_mdoc (@MAN7EXT@),
+.BR groff_mdoc.samples (@MAN7EXT@),
+.BR groff_me (@MAN7EXT@),
+.BR groff_mm (@MAN7EXT@),
+.BR groff_mmroff (@MAN7EXT@),
+.BR groff_ms (@MAN7EXT@),
+and
+.BR groff_msafer (@MAN7EXT@).
+.LP
+The following utilities are available:
+.BR addftinfo (@MAN1EXT@),
+.BR afmtodif (@MAN1EXT@),
+.BR hpftodit (@MAN1EXT@),
+.BR indxbib (@MAN1EXT@),
+.BR lookbib (@MAN1EXT@),
+.BR pfbtops (@MAN1EXT@),
+.BR tfmtodit (@MAN1EXT@),
+and
+.BR gxditview (@MAN1EXT@).
+.LP
+For details on the GNU implementation of the
+.I roff
+system see
+.BR groff_char (@MAN7EXT@),
+.BR groff_font (@MAN7EXT@),
+.BR groff_out (@MAN7EXT@),
+and the file
+.I README
+in the main directory of the groff source distribution.
+These also give details on how to contact or join the
+.I groff
+developer group.
+.LP
+Many classical
+.troff
+documents are still available on-line.
+Especially informative are the original Bell Labs proceedings for the old,
+free UNIX 7 found at
+.I http://cm.bell-labs.com/cm/cs/cstr.html
+and the collection of the late Richard S. Stevens at 
+.IR http://www.kohala.com/start/troff/ .