===================================================================
RCS file: /cvs/mandoc/roff.7,v
retrieving revision 1.15
retrieving revision 1.21
diff -u -p -r1.15 -r1.21
--- mandoc/roff.7	2010/12/06 16:37:32	1.15
+++ mandoc/roff.7	2011/01/04 12:06:21	1.21
@@ -1,4 +1,4 @@
-.\"	$Id: roff.7,v 1.15 2010/12/06 16:37:32 kristaps Exp $
+.\"	$Id: roff.7,v 1.21 2011/01/04 12:06:21 kristaps Exp $
 .\"
 .\" Copyright (c) 2010 Kristaps Dzonsons <kristaps@bsd.lv>
 .\" Copyright (c) 2010 Ingo Schwarze <schwarze@openbsd.org>
@@ -15,64 +15,85 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.Dd $Mdocdate: December 6 2010 $
+.Dd $Mdocdate: January 4 2011 $
 .Dt ROFF 7
 .Os
 .Sh NAME
 .Nm roff
-.Nd roff language reference
+.Nd roff language reference for mandoc
 .Sh DESCRIPTION
 The
 .Nm roff
-language is a general-purpose text-formatting language.  The purpose of
-this document is to consistently describe those language constructs
-accepted by the
+language is a general purpose text formatting language.
+In particular, it serves as the basis for the
+.Xr mdoc 7
+and
+.Xr man 7
+manual formatting macro languages.
+This manual describes the subset of the
+.Nm
+language accepted by the
 .Xr mandoc 1
-utility.  It is a work in progress.
+utility.
 .Pp
-An
-.Nm
-document follows simple rules:  lines beginning with the control
-characters
-.Sq \.
+Input lines beginning with the control characters
+.Sq \&.
 or
 .Sq \(aq
 are parsed for requests and macros.
-Other lines are interpreted within the scope of
-prior macros:
-.Bd -literal -offset indent
-\&.xx Macro lines change control state.
-Other lines are interpreted within the current state.
-.Ed
+These define the document structure, change the processing state
+and manipulate the formatting.
+Some requests and macros also produce formatted output,
+while others do not.
+.Pp
+All other input lines provide free-form text to be printed;
+the formatting of free-form text depends on the respective
+processing context.
 .Sh LANGUAGE SYNTAX
 .Nm
 documents may contain only graphable 7-bit ASCII characters, the space
-character, and, in certain circumstances, the tab character.  All
-manuals must have
+character, and, in certain circumstances, the tab character.
+To produce other characters in the output, use the escape sequences
+documented in the
+.Xr mandoc_char 7
+manual.
+.Pp
+All manuals must have
 .Ux
 line terminators.
-.Sh MACRO SYNTAX
-Requests and macros are arbitrary in length and begin with a control
-character,
-.Sq \.
+.Sh REQUEST SYNTAX
+A request or macro line consists of:
+.Pp
+.Bl -enum -compact
+.It
+the control character
+.Sq \&.
 or
-.Sq \(aq ,
-at the beginning of the line.
-An arbitrary amount of whitespace may sit between the control character
-and the request or macro name.
-Thus, the following are equivalent:
+.Sq \(aq
+at the beginning of the line,
+.It
+optionally an arbitrary amount of whitespace,
+.It
+the name of the request or the macro, which is one word of arbitrary
+length, terminated by whitespace,
+.It
+and zero or more arguments delimited by whitespace.
+.El
+.Pp
+Thus, the following request lines are all equivalent:
 .Bd -literal -offset indent
-\&.if
-\&.\ \ \ \&if
+\&.ig end
+\&.ig    end
+\&.   ig end
 .Ed
 .Sh REQUEST REFERENCE
-This section is a canonical reference of all requests recognized by the
+The
 .Xr mandoc 1
 .Nm
-parser.
-The
+parser recognizes the following requests.
+Note that the
 .Nm
-language defines many more requests and macros not implemented in
+language defines many more requests not implemented in
 .Xr mandoc 1 .
 .Ss \&ad
 Set line adjustment mode.
@@ -103,7 +124,7 @@ It is currently ignored by
 .Xr mandoc 1 ,
 as are its children.
 .Ss \&de
-Define a user-defined
+Define a
 .Nm
 macro.
 Its syntax can be either
@@ -149,7 +170,7 @@ request or
 .Nm
 macro, but not as a high-level macro.
 .Pp
-A user-defined macro can be invoked later using the syntax
+The macro can be invoked later using the syntax
 .Pp
 .D1 Pf . Ar name Op Ar argument Op Ar argument ...
 .Pp
@@ -160,12 +181,12 @@ to allow inclusion of blank characters into arguments.
 To include the double-quote character into a quoted argument,
 escape it from ending the argument by doubling it.
 .Pp
-The line invoking the user-defined macro will be replaced
+The line invoking the macro will be replaced
 in the input stream by the
 .Ar macro definition ,
 replacing all occurrences of
 .No \e\e$ Ns Ar N ,
-where 
+where
 .Ar N
 is a digit, by the
 .Ar N Ns th Ar argument .
@@ -183,7 +204,7 @@ produces
 .Pp
 in the input stream, and thus in the output: \fI\^XtFree\^\fP.
 .Pp
-Since user-defined macros and strings share a common string table,
+Since macros and user-defined strings share a common string table,
 defining a macro
 .Ar name
 clobbers the user-defined string
@@ -196,17 +217,23 @@ string interpolation syntax described below
 .Sx ds ,
 but this is rarely useful because every macro definition contains at least
 one explicit newline character.
+.Pp
+In order to prevent endless recursion, both groff and
+.Xr mandoc 1
+limit the stack depth for expanding macros and strings
+to a large, but finite number.
+Do not rely on the exact value of this limit.
 .Ss \&dei
-Define a user-defined
+Define a
 .Nm
 macro, specifying the macro name indirectly.
-The syntax of this macro is the same as that of
+The syntax of this request is the same as that of
 .Sx \&de .
 It is currently ignored by
 .Xr mandoc 1 ,
 as are its children.
 .Ss \&de1
-Define a user-defined
+Define a
 .Nm
 macro that will be executed with
 .Nm
@@ -218,7 +245,7 @@ Since
 .Xr mandoc 1
 does not implement
 .Nm
-compatibility mode at all, it handles this macro as an alias for
+compatibility mode at all, it handles this request as an alias for
 .Sx \&de .
 .Ss \&ds
 Define a user-defined string.
@@ -248,11 +275,14 @@ for a
 of arbitrary length, or \e*(NN or \e*N if the length of
 .Ar name
 is two or one characters, respectively.
+Interpolation can be prevented by escaping the leading backslash;
+that is, an asterisk preceded by an even number of backslashes
+does not trigger string interpolation.
 .Pp
 Since user-defined strings and macros share a common string table,
 defining a string
 .Ar name
-clobbers the user-defined macro
+clobbers the macro
 .Ar name ,
 and the
 .Ar name
@@ -286,7 +316,7 @@ If no stack entries are present (e.g., due to no prior
 .Sx \&ie
 calls)
 then false is assumed.
-The syntax of this macro is similar to
+The syntax of this request is similar to
 .Sx \&if
 except that the conditional is missing.
 .Ss \&hy
@@ -307,45 +337,40 @@ Begins a conditional.
 Right now, the conditional evaluates to true
 if and only if it starts with the letter
 .Sy n ,
-indicating processing in
-.Xr nroff 1
-style as opposed to
-.Xr troff 1
-style.
+indicating processing in nroff style as opposed to troff style.
 If a conditional is false, its children are not processed, but are
 syntactically interpreted to preserve the integrity of the input
 document.
 Thus,
 .Pp
-.D1 \&.if t \e .ig
+.D1 \&.if t .ig
 .Pp
 will discard the
 .Sq \&.ig ,
 which may lead to interesting results, but
 .Pp
-.D1 \&.if t \e .if t \e{\e
+.D1 \&.if t .if t \e{\e
 .Pp
 will continue to syntactically interpret to the block close of the final
 conditional.
 Sub-conditionals, in this case, obviously inherit the truth value of
 the parent.
-This macro has the following syntax:
-.Pp
-.Bd -literal -offset indent -compact
+This request has the following syntax:
+.Bd -literal -offset indent
 \&.if COND \e{\e
 BODY...
 \&.\e}
 .Ed
-.Bd -literal -offset indent -compact
+.Bd -literal -offset indent
 \&.if COND \e{ BODY
 BODY... \e}
 .Ed
-.Bd -literal -offset indent -compact
+.Bd -literal -offset indent
 \&.if COND \e{ BODY
 BODY...
 \&.\e}
 .Ed
-.Bd -literal -offset indent -compact
+.Bd -literal -offset indent
 \&.if COND \e
 BODY
 .Ed
@@ -366,12 +391,12 @@ evaluate as false.
 .Pp
 If the BODY section is begun by an escaped brace
 .Sq \e{ ,
-scope continues until a closing-brace macro
+scope continues until a closing-brace escape sequence
 .Sq \.\e} .
-If the BODY is not enclosed in braces, scope continues until the next
-macro or word.
+If the BODY is not enclosed in braces, scope continues until
+the end of the line.
 If the COND is followed by a BODY on the same line, whether after a
-brace or not, then macros
+brace or not, then requests and macros
 .Em must
 begin with a control character.
 It is generally more intuitive, in this case, to write
@@ -382,20 +407,20 @@ bar
 \&.\e}
 .Ed
 .Pp
-than having the macro follow as
+than having the request or macro follow as
 .Pp
 .D1 \&.if COND \e{ .foo
 .Pp
 The scope of a conditional is always parsed, but only executed if the
 conditional evaluates to true.
 .Pp
-Note that text subsequent a
+Note that text following an
 .Sq \&.\e}
-macro is discarded.
+escape sequence is discarded.
 Furthermore, if an explicit closing sequence
 .Sq \e}
 is specified in a free-form line, the entire line is accepted within the
-scope of the prior macro, not only the text preceding the close, with the
+scope of the prior request, not only the text preceding the close, with the
 .Sq \e}
 collapsing into a zero-width space.
 .Ss \&ig
@@ -416,7 +441,7 @@ or
 .Pp
 In the first case, input is ignored until a
 .Sq \&..
-macro is encountered on its own line.
+request is encountered on its own line.
 In the second case, input is ignored until the specified
 .Sq Pf . Ar end
 macro is encountered.
@@ -441,7 +466,7 @@ Otherwise, it only terminates the
 .Ar ignored text ,
 and arguments following it or the
 .Sq \&..
-macro are discarded.
+request are discarded.
 .Ss \&ne
 Declare the need for the specified minimum vertical space
 before the next trap or the bottom of the page.
@@ -466,9 +491,6 @@ Its syntax is as follows:
 The
 .Ar value
 may, at the moment, only be an integer.
-The
-.Ar name
-is defined up to the next whitespace.
 So far, only the following register
 .Ar name
 is recognised:
@@ -476,15 +498,19 @@ is recognised:
 .It Cm nS
 If set to a positive integer value, certain
 .Xr mdoc 7
-macros will behave as if they were defined in the
+macros will behave in the same way as in the
 .Em SYNOPSIS
 section.
-Otherwise, this behaviour is unset (even if called within the
+If set to 0, these macros will behave in the same way as outside the
 .Em SYNOPSIS
-section itself).
-Note that invoking a new
+section, even when called within the
+.Em SYNOPSIS
+section itself.
+Note that starting a new
 .Xr mdoc 7
-section will unset this value.
+section with the
+.Cm \&Sh
+macro will reset this register.
 .El
 .Ss \&so
 Include a source file.
@@ -505,39 +531,276 @@ and
 .Qq /.. .
 .Ss \&tr
 Output character translation.
-This macro is intended to have one argument,
+This request is intended to have one argument,
 consisting of an even number of characters.
 Currently, it is ignored including its arguments,
 and the number of arguments is not checked.
+.Ss \&T&
+Re-start a table layout, retaining the options of the prior table
+invocation.
+See
+.Sx \&TS .
+.Ss \&TE
+End a table context.
+See
+.Sx \&TS .
+.Ss \&TS
+Begin a table, which formats input in aligned rows and columns.
+A table consists of an optional single line of table options terminated
+by a semicolon, followed by one or more lines of layout specification
+terminated by a period, then table data.
+A table block may also include
+.Nm ,
+.Xr mdoc 7 ,
+or
+.Xr man 7
+macros.
+Example:
+.Bd -literal -offset indent
+\&.TS
+box tab(:);   \e" Table-wide options.
+c | c         \e" Layout for first line.
+| c | c.      \e" Layout for all subsequent lines.
+1:2           \e" Data...
+3:4
+\&.TE
+.Ed
+.Pp
+Table data is
+.Em pre-processed ,
+that is, data rows are parsed then inserted into the underlying stream
+of input data.
+This allows data rows to be interspersed by arbitrary macros, such as
+.Bd -literal -offset indent
+\&.TS
+tab(:);
+c c c.
+1:2:3
+\&.Ao
+3:2:1
+\&.Ac
+\&.TE
+.Ed
+.Pp
+in the case of
+.Xr mdoc 7
+or
+.Bd -literal -offset indent
+\&.TS
+tab(:);
+c c c.
+\&.ds ab 2
+1:\e*(ab:3
+\&.I
+3:2:1
+\&.TE
+.Ed
+.Pp
+in the case of
+.Xr man 7 .
+.Pp
+The first line of a table consists of its options, which consists of
+space-separated keys and modifiers terminated by a semicolon.
+If the first line does not have a terminating semicolon, it is assumed
+that no options are specified and instead a layout is processed.
+Some options accept arguments enclosed by paranthesis.
+The following case-insensitive options are available:
+.Bl -tag -width Ds
+.It Cm center
+This option is not supported by
+.Xr mandoc 1 .
+This may also be invoked with
+.Cm centre .
+.It Cm delim
+Accepts a two-character argument.
+This option is not supported by
+.Xr mandoc 1 .
+.It Cm expand
+This option is not supported by
+.Xr mandoc 1 .
+.It Cm box
+Draw a single-line box around the table.
+This may also be invoked with
+.Cm frame .
+.It Cm doublebox
+Draw a double-line box around the table.
+This may also be invoked with
+.Cm doubleframe .
+.It Cm allbox
+This option is not supported by
+.Xr mandoc 1 .
+.It Cm tab
+Accepts a single-character argument.
+This character is used a delimiter between data cells, which otherwise
+defaults to the tab character.
+.It Cm linesize
+Accepts a natural number (all digits).
+This option is not supported by
+.Xr mandoc 1 .
+.It Cm nokeep
+This option is not supported by
+.Xr mandoc 1 .
+.It Cm decimalpoint
+Accepts a single-character argument.
+This character will be used as the decimal point with the
+.Cm n
+layout key.
+This option is not supported by
+.Xr mandoc 1 .
+.It Cm nospaces
+This option is not supported by
+.Xr mandoc 1 .
+.El
+.Pp
+The table layout follows table options, except in the case of
+.Sx \&T& ,
+where it immediately procedes invocation.
+Layout specifies how data rows are displayed on output.
+Each layout line corresponds to a line of data; the last layout line
+applies to all remaining data lines.
+Layout lines may also be separated by a comma.
+Each layout cell consists of one of the following case-insensitive keys:
+.Bl -tag -width Ds
+.It Cm c
+Centre a literal string within its column.
+.It Cm r
+Right-justify a literal string within its column.
+.It Cm l
+Left-justify a literal string within its column.
+.It Cm n
+Justify a number around its decimal point.
+If the decimal point is not found on the number, it's assumed to trail
+the number.
+.It Cm s
+This option is not supported by
+.Xr mandoc 1 .
+.It Cm a
+This option is not supported by
+.Xr mandoc 1 .
+.It Cm ^
+This option is not supported by
+.Xr mandoc 1 .
+.It Cm \-
+Replace the data cell (its contents will be lost) with a single
+horizontal line.
+This may also be invoked with
+.Cm _ .
+.It Cm =
+Replace the data cell (its contents will be lost) with a double
+horizontal line.
+.It Cm \(ba
+Emit a vertical bar instead of data.
+.It Cm \(ba\(ba
+Emit a double-vertical bar instead of data.
+.El
+.Pp
+For example, following layout specifies a centre-justified column of
+minimum width 10, followed by vertical bar, followed by a left-justified
+column of minimum width 10, another vertical bar, then a column
+justified about the decimal point in numbers:
+.Pp
+.Dl c10 | l10 | n
+.Pp
+Keys may be followed by a set of modifiers.
+A modifier is either a modifier key or a natural number for specifying
+spacing.
+The following case-insensitive modifier keys are available:
+.Cm z ,
+.Cm u ,
+.Cm e ,
+.Cm t ,
+.Cm d ,
+.Cm f ,
+.Cm b ,
+.Cm i ,
+.Cm b ,
+and
+.Cm i .
+All of these are ignored by
+.Xr mandoc 1 .
+.Pp
+The data section follows the last layout row.
+By default, cells in a data section are delimited by a tab.
+This behaviour may be changed with the
+.Cm tab
+option.
+If
+.Cm _
+or
+.Cm =
+is specified, a single or double line, respectively, is drawn across the
+data field.
+If
+.Cm \e-
+or
+.Cm \e=
+is specified, a line is drawn within the data field (i.e., terminating
+within the cell and not draw to the border).
 .Sh COMPATIBILITY
 This section documents compatibility between mandoc and other other
-troff implementations, at this time limited to GNU troff
+.Nm
+implementations, at this time limited to GNU troff
 .Pq Qq groff .
 The term
 .Qq historic groff
-refers to groff versions before the
-.Pa doc.tmac
-file re-write
-.Pq somewhere between 1.15 and 1.19 .
+refers to groff version 1.15.
 .Pp
 .Bl -dash -compact
 .It
 The
 .Cm nS
-request to
-.Sx \&nr
-is only compatible with OpenBSD's groff.
+register is only compatible with OpenBSD's groff-1.15.
 .It
-Historic groff did not accept white-space buffering the custom END tag
-for the
+Historic groff did not accept white-space before a custom
+.Ar end
+macro for the
 .Sx \&ig
-macro.
+request.
 .It
 The
 .Sx \&if
 and family would print funny white-spaces with historic groff when
-depending on next-line syntax.
+using the next-line syntax.
 .El
+.Sh SEE ALSO
+.Xr mandoc 1 ,
+.Xr man 7 ,
+.Xr mandoc_char 7 ,
+.Xr mdoc 7
+.Rs
+.%A M. E. Lesk
+.%T Tbl\(emA Program to Format Tables
+.%D June 11, 1976
+.%U http://www.kohala.com/start/troff/v7/man/tbl/tbl.ps
+.Re
+.Rs
+.%A Joseph F. Ossanna
+.%A Brian W. Kernighan
+.%I AT&T Bell Laboratories
+.%T Troff User's Manual
+.%R Computing Science Technical Report
+.%N 54
+.%C Murray Hill, New Jersey
+.%D 1976 and 1992
+.%U http://www.kohala.com/start/troff/cstr54.ps
+.Re
+.Rs
+.%A Joseph F. Ossanna
+.%A Brian W. Kernighan
+.%A Gunnar Ritter
+.%T Heirloom Documentation Tools Nroff/Troff User's Manual
+.%D September 17, 2007
+.%U http://heirloom.sourceforge.net/doctools/troff.pdf
+.Re
+.Sh HISTORY
+The RUNOFF typesetting system was written in PL/1 for the CTSS
+operating system by Jerome ("Jerry") E. Saltzer in 1961.
+It was first used as the main documentation tool by Multics since 1963.
+Robert ("Bob") H. Morris ported it to the GE-635 and called it
+.Nm ,
+Doug McIlroy rewrote it in BCPL in 1969,
+Joseph F. Ossanna rewrote it in PDP-11 assembly in 1973,
+and Brian W. Kernighan rewrote it in C in 1975.
 .Sh AUTHORS
 .An -nosplit
 This partial