===================================================================
RCS file: /cvs/mandoc/roff.7,v
retrieving revision 1.17
retrieving revision 1.30
diff -u -p -r1.17 -r1.30
--- mandoc/roff.7	2010/12/18 19:32:08	1.17
+++ mandoc/roff.7	2011/07/28 14:17:11	1.30
@@ -1,4 +1,4 @@
-.\"	$Id: roff.7,v 1.17 2010/12/18 19:32:08 schwarze Exp $
+.\"	$Id: roff.7,v 1.30 2011/07/28 14:17:11 kristaps Exp $
 .\"
 .\" Copyright (c) 2010 Kristaps Dzonsons <kristaps@bsd.lv>
 .\" Copyright (c) 2010 Ingo Schwarze <schwarze@openbsd.org>
@@ -15,7 +15,7 @@
 .\" 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 18 2010 $
+.Dd $Mdocdate: July 28 2011 $
 .Dt ROFF 7
 .Os
 .Sh NAME
@@ -57,10 +57,6 @@ To produce other characters in the output, use the esc
 documented in the
 .Xr mandoc_char 7
 manual.
-.Pp
-All manuals must have
-.Ux
-line terminators.
 .Sh REQUEST SYNTAX
 A request or macro line consists of:
 .Pp
@@ -86,6 +82,38 @@ Thus, the following request lines are all equivalent:
 \&.ig    end
 \&.   ig end
 .Ed
+.Sh MACRO SYNTAX
+Macros can be defined by the
+.Sx \&de
+request.
+When called, they follow the same syntax as requests, except that
+macro arguments may optionally be quoted by enclosing them
+in double quote characters
+.Pq Sq \(dq .
+To be recognized as the beginning of a quoted argument, the opening
+quote character must be preceded by a space character.
+.Pp
+A quoted argument may contain whitespace, and pairs of double quote
+characters
+.Pq Sq Qq
+resolve to single double quote characters.
+A quoted argument extends to the next double quote character that is not
+part of a pair, or to the end of the input line, whichever comes earlier.
+Leaving out the terminating double quote character at the end of the line
+is discouraged.
+For clarity, if more arguments follow on the same input line,
+it is recommended to follow the terminating double quote character
+by a space character; in case the next character after the terminating
+double quote character is anything else, it is regarded as the beginning
+of the next, unquoted argument.
+.Pp
+Both in quoted and unquoted arguments, pairs of backslashes
+.Pq Sq \e\e
+resolve to single backslashes.
+In unquoted arguments, space characters can alternatively be included
+by preceding them with a backslash
+.Pq Sq \e\~ ,
+but quoting is usually better for clarity.
 .Sh REQUEST REFERENCE
 The
 .Xr mandoc 1
@@ -174,12 +202,9 @@ The macro can be invoked later using the syntax
 .Pp
 .D1 Pf . Ar name Op Ar argument Op Ar argument ...
 .Pp
-Arguments are separated by blank characters and can be quoted
-using double-quotes
-.Pq Sq \(dq
-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.
+Regarding argument parsing, see
+.Sx MACRO SYNTAX
+above.
 .Pp
 The line invoking the macro will be replaced
 in the input stream by the
@@ -319,6 +344,15 @@ then false is assumed.
 The syntax of this request is similar to
 .Sx \&if
 except that the conditional is missing.
+.Ss \&EN
+End an equation block.
+See
+.Sx \&EQ .
+.Ss \&EQ
+Begin an equation block.
+See
+.Xr eqn 7
+for a description of the equation language.
 .Ss \&hy
 Set automatic hyphenation mode.
 This line-scoped request is currently ignored.
@@ -414,15 +448,20 @@ than having the request or macro follow as
 The scope of a conditional is always parsed, but only executed if the
 conditional evaluates to true.
 .Pp
-Note that text following an
-.Sq \&.\e}
-escape sequence is discarded.
-Furthermore, if an explicit closing sequence
+Note that the
 .Sq \e}
-is specified in a free-form line, the entire line is accepted within the
-scope of the prior request, not only the text preceding the close, with the
+is converted into a zero-width escape sequence if not passed as a
+standalone macro
+.Sq \&.\e} .
+For example,
+.Pp
+.D1 \&.Fl a \e} b
+.Pp
+will result in
 .Sq \e}
-collapsing into a zero-width space.
+being considered an argument of the
+.Sq \&Fl
+macro.
 .Ss \&ig
 Ignore input.
 Its syntax can be either
@@ -512,6 +551,16 @@ section with the
 .Cm \&Sh
 macro will reset this register.
 .El
+.Ss \&ns
+Turn on no-space mode.
+This line-scoped request is intended to take no arguments.
+Currently, it is ignored including its arguments,
+and the number of arguments is not checked.
+.Ss \&ps
+Change point size.
+This line-scoped request is intended to take one numerical argument.
+Currently, it is ignored including its arguments,
+and the number of arguments is not checked.
 .Ss \&so
 Include a source file.
 Its syntax is as follows:
@@ -523,18 +572,47 @@ The
 will be read and its contents processed as input in place of the
 .Sq \&.so
 request line.
-To avoid inadvertant inclusion of unrelated files,
+To avoid inadvertent inclusion of unrelated files,
 .Xr mandoc 1
 only accepts relative paths not containing the strings
 .Qq ../
 and
 .Qq /.. .
+.Ss \&ta
+Set tab stops.
+This line-scoped request can take an arbitrary number of arguments.
+Currently, it is ignored including its arguments.
 .Ss \&tr
 Output character translation.
-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.
+Its syntax is as follows:
+.Pp
+.D1 Pf \. Cm \&tr Ar [ab]+
+.Pp
+Pairs of
+.Ar ab
+characters are replaced
+.Ar ( a
+for
+.Ar b ) .
+Replacement (or origin) characters may also be character escapes; thus,
+.Pp
+.Dl tr \e(xx\e(yy
+.Pp
+replaces all invocations of \e(xx with \e(yy.
+.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.
+See
+.Xr tbl 7
+for a description of the tbl language.
 .Sh COMPATIBILITY
 This section documents compatibility between mandoc and other other
 .Nm
@@ -546,6 +624,19 @@ refers to groff version 1.15.
 .Pp
 .Bl -dash -compact
 .It
+In mandoc, the
+.Sx \&EQ ,
+.Sx \&TE ,
+.Sx \&TS ,
+and
+.Sx \&T& ,
+macros are considered regular macros.
+In all other
+.Nm
+implementations, these are special macros that must be specified without
+spacing between the control character (which must be a period) and the
+macro name.
+.It
 The
 .Cm nS
 register is only compatible with OpenBSD's groff-1.15.
@@ -563,9 +654,11 @@ using the next-line syntax.
 .El
 .Sh SEE ALSO
 .Xr mandoc 1 ,
+.Xr eqn 7 ,
 .Xr man 7 ,
 .Xr mandoc_char 7 ,
-.Xr mdoc 7
+.Xr mdoc 7 ,
+.Xr tbl 7
 .Rs
 .%A Joseph F. Ossanna
 .%A Brian W. Kernighan