===================================================================
RCS file: /cvs/mandoc/mdoc.7,v
retrieving revision 1.187
retrieving revision 1.195
diff -u -p -r1.187 -r1.195
--- mandoc/mdoc.7	2011/05/21 15:55:42	1.187
+++ mandoc/mdoc.7	2011/08/02 01:07:26	1.195
@@ -1,4 +1,4 @@
-.\"	$Id: mdoc.7,v 1.187 2011/05/21 15:55:42 schwarze Exp $
+.\"	$Id: mdoc.7,v 1.195 2011/08/02 01:07:26 schwarze Exp $
 .\"
 .\" Copyright (c) 2009, 2010, 2011 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: May 21 2011 $
+.Dd $Mdocdate: August 2 2011 $
 .Dt MDOC 7
 .Os
 .Sh NAME
@@ -65,42 +65,6 @@ A macro line with only a control character and comment
 is also ignored.
 Macro lines with only a control character and optional whitespace are
 stripped from input.
-.Ss Reserved Terms
-Within a macro line, the following terms are reserved:
-.Pp
-.Bl -tag -width Ds -offset indent -compact
-.It \&.
-.Pq period
-.It \e.
-.Pq escaped period
-.It \&,
-.Pq comma
-.It \&:
-.Pq colon
-.It \&;
-.Pq semicolon
-.It \&(
-.Pq left-parenthesis
-.It \&)
-.Pq right-parenthesis
-.It \&[
-.Pq left-bracket
-.It \&]
-.Pq right-bracket
-.It \&?
-.Pq question
-.It \&!
-.Pq exclamation
-.It \&|
-.Pq vertical bar
-.It \e*(Ba
-.Pq reserved-word vertical bar
-.El
-.Pp
-For general use in macro lines, these can be escaped with a non-breaking
-space
-.Pq Sq \e& .
-In text lines, these may be used as normal punctuation.
 .Ss Special Characters
 Special characters may occur in both macro and text lines.
 Sequences begin with the escape character
@@ -178,15 +142,38 @@ trailing spaces are stripped from input (unless in a l
 Blank text lines, which may include whitespace, are only permitted
 within literal contexts.
 .Pp
+In general, trailing whitespace on input lines is discouraged
+for reasons of clarity and portability.
+In the rare case that a blank character is needed at the end of an
+input line, it may be forced by
+.Sq \e\ \e& .
+.Pp
 In macro lines, whitespace delimits arguments and is discarded.
-If arguments are quoted, whitespace within the quotes is retained.
 .Ss Quotation
-Macro arguments may be quoted with double-quotes to group
-space-delimited terms or to retain blocks of whitespace.
+Macro arguments may be quoted with double-quotes; in this case,
+whitespace within the quotes is retained as part of the argument.
+For example,
+.Pp
+.D1 Pf \. \&Fn strlen "\(dqconst char *s\(dq"
+.Pp
+renders as
+.Sq Fn strlen "const char *s" ,
+while
+.Pp
+.D1 Pf \. \&Fn strlen "const char *s"
+.Pp
+would produce
+.Sq Fn strlen const char *s .
+.Pp
 A quoted argument begins with a double-quote preceded by whitespace.
 The next double-quote not pairwise adjacent to another double-quote
 terminates the literal, regardless of surrounding whitespace.
 .Pp
+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.
+.Pp
 Note that any quoted text, even if it would cause a macro invocation
 when unquoted, is considered literal text.
 Thus, the following produces
@@ -296,19 +283,20 @@ sections, although this varies between manual sections
 .Pp
 The following is a well-formed skeleton
 .Nm
-file:
+file for a utility
+.Qq progname :
 .Bd -literal -offset indent
 \&.Dd $\&Mdocdate$
-\&.Dt mdoc 7
+\&.Dt PROGNAME section
 \&.Os
 \&.Sh NAME
-\&.Nm foo
-\&.Nd a description goes here
+\&.Nm progname
+\&.Nd one line about what it does
 \&.\e\*q .Sh LIBRARY
 \&.\e\*q For sections 2, 3, & 9 only.
 \&.\e\*q Not used in OpenBSD.
 \&.Sh SYNOPSIS
-\&.Nm foo
+\&.Nm progname
 \&.Op Fl options
 \&.Ar
 \&.Sh DESCRIPTION
@@ -599,6 +587,17 @@ The
 .Em Callable
 column indicates that the macro may also be called by passing its name
 as an argument to another macro.
+For example,
+.Sq \&.Op \&Fl O \&Ar file
+produces
+.Sq Op Fl O Ar file .
+To prevent a macro call and render the macro name literally,
+escape it by prepending a zero-width space,
+.Sq \e& .
+For example,
+.Sq \&Op \e&Fl O
+produces
+.Sq Op \&Fl O .
 If a macro is not callable but its name appears as an argument
 to another macro, it is interpreted as opaque text.
 For example,
@@ -727,9 +726,8 @@ and/or tail
 .It Sx \&Xo  Ta    Yes      Ta    Yes      Ta    closed by Sx \&Xc
 .El
 .Ss Block partial-implicit
-Like block full-implicit, but with single-line scope closed by
-.Sx Reserved Terms
-or end of line.
+Like block full-implicit, but with single-line scope closed by the
+end of the line.
 .Bd -literal -offset indent
 \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB \(lBres...\(rB
 .Ed
@@ -759,10 +757,24 @@ in a
 .Em SYNOPSIS
 section line, else it is
 .Sx In-line .
+.Ss Special block macro
+The
+.Sx \&Ta
+macro can only be used below
+.Sx \&It
+in
+.Sx \&Bl Fl column
+lists.
+It delimits blocks representing table cells;
+these blocks have bodies, but no heads.
+.Pp
+.Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXXX" -compact -offset indent
+.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope
+.It Sx \&Ta  Ta    Yes      Ta    Yes    Ta closed by Sx \&Ta , Sx \&It
+.El
 .Ss In-line
-Closed by
-.Sx Reserved Terms ,
-end of line, fixed argument lengths, and/or subsequent macros.
+Closed by the end of the line, fixed argument lengths,
+and/or subsequent macros.
 In-line macros have only text children.
 If a number (or inequality) of arguments is
 .Pq n ,
@@ -852,6 +864,90 @@ then the macro accepts an arbitrary number of argument
 .It Sx \&br  Ta    \&No     Ta    \&No     Ta    0
 .It Sx \&sp  Ta    \&No     Ta    \&No     Ta    1
 .El
+.Ss Delimiters
+When a macro argument consists of one single input character
+considered as a delimiter, the argument gets special handling.
+This does not apply when delimiters appear in arguments containing
+more than one character.
+Consequently, to prevent special handling and just handle it
+like any other argument, a delimiter can be escaped by prepending
+a zero-width space
+.Pq Sq \e& .
+In text lines, delimiters never need escaping, but may be used
+as normal punctuation.
+.Pp
+For many macros, when the leading arguments are opening delimiters,
+these delimiters are put before the macro scope,
+and when the trailing arguments are closing delimiters,
+these delimiters are put after the macro scope.
+For example,
+.Pp
+.D1 Pf \. \&Aq "( [ word ] ) ."
+.Pp
+renders as:
+.Pp
+.D1 Aq ( [ word ] ) .
+.Pp
+Opening delimiters are:
+.Pp
+.Bl -tag -width Ds -offset indent -compact
+.It \&(
+left parenthesis
+.It \&[
+left bracket
+.El
+.Pp
+Closing delimiters are:
+.Pp
+.Bl -tag -width Ds -offset indent -compact
+.It \&.
+period
+.It \&,
+comma
+.It \&:
+colon
+.It \&;
+semicolon
+.It \&)
+right parenthesis
+.It \&]
+right bracket
+.It \&?
+question mark
+.It \&!
+exclamation mark
+.El
+.Pp
+Note that even a period preceded by a backslash
+.Pq Sq \e.\&
+gets this special handling; use
+.Sq \e&.
+to prevent that.
+.Pp
+Many in-line macros interrupt their scope when they encounter
+delimiters, and resume their scope when more arguments follow that
+are not delimiters.
+For example,
+.Pp
+.D1 Pf \. \&Fl "a ( b | c \e*(Ba d ) e"
+.Pp
+renders as:
+.Pp
+.D1 Fl a ( b | c \*(Ba d ) e
+.Pp
+This applies to both opening and closing delimiters,
+and also to the middle delimiter:
+.Pp
+.Bl -tag -width Ds -offset indent -compact
+.It \&|
+vertical bar
+.El
+.Pp
+As a special case, the predefined string \e*(Ba is handled and rendered
+in the same way as a plain
+.Sq \&|
+character.
+Using this predefined string is not recommended in new manuals.
 .Sh REFERENCE
 This section is a canonical reference of all macros, arranged
 alphabetically.
@@ -1022,6 +1118,8 @@ Accepts one optional argument:
 .It Cm v[1-7] | 32v
 A version of
 .At .
+.It Cm III
+.At III .
 .It Cm V[.[1-4]]?
 A version of
 .At V .
@@ -1031,6 +1129,7 @@ Note that these arguments do not begin with a hyphen.
 .Pp
 Examples:
 .Dl \&.At
+.Dl \&.At III
 .Dl \&.At V.1
 .Pp
 See also
@@ -1690,14 +1789,21 @@ See also
 and
 .Sx \&Os .
 .Ss \&Dv
-Defined variables such as preprocessor constants.
+Defined variables such as preprocessor constants, constant symbols,
+enumeration values, and so on.
 .Pp
 Examples:
+.Dl \&.Dv NULL
 .Dl \&.Dv BUFSIZ
 .Dl \&.Dv STDOUT_FILENO
 .Pp
 See also
-.Sx \&Er .
+.Sx \&Er
+and
+.Sx \&Ev
+for special-purpose constants and
+.Sx \&Va
+for variable symbols.
 .Ss \&Dx
 Format the DragonFly BSD version provided as an argument, or a default
 value if no argument is provided.
@@ -1773,14 +1879,17 @@ argument is used as the enclosure head, for example, s
 will emulate
 .Sx \&Do .
 .Ss \&Er
-Display error constants.
+Error constants for definitions of the
+.Va errno
+libc global variable.
 .Pp
 Examples:
 .Dl \&.Er EPERM
 .Dl \&.Er ENOENT
 .Pp
 See also
-.Sx \&Dv .
+.Sx \&Dv
+for general constants.
 .Ss \&Es
 This macro is obsolete and not implemented.
 .Ss \&Ev
@@ -1790,17 +1899,25 @@ Environmental variables such as those specified in
 Examples:
 .Dl \&.Ev DISPLAY
 .Dl \&.Ev PATH
+.Pp
+See also
+.Sx \&Dv
+for general constants.
 .Ss \&Ex
-Insert a standard sentence regarding exit values.
+Insert a standard sentence regarding command exit values of 0 on success
+and >0 on failure.
 Its syntax is as follows:
 .Pp
-.D1 Pf \. Sx \&Ex Fl std Op Ar utility
+.D1 Pf \. Sx \&Ex Fl std Op Ar utility ...
 .Pp
-When
+If
 .Ar utility
 is not specified, the document's name set by
 .Sx \&Nm
 is used.
+Multiple
+.Ar utility
+arguments are treated as separate utilities.
 .Pp
 See also
 .Sx \&Rv .
@@ -1927,6 +2044,8 @@ See also
 .Sx \&Fc ,
 and
 .Sx \&Ft .
+.Ss \&Fr
+This macro is obsolete and not implemented.
 .Ss \&Ft
 A function type.
 Its syntax is as follows:
@@ -2049,31 +2168,27 @@ The
 list is the most complicated.
 Its syntax is as follows:
 .Pp
-.D1 Pf \. Sx \&It Op Cm args
+.D1 Pf \. Sx \&It Ar cell Op <TAB> Ar cell ...
+.D1 Pf \. Sx \&It Ar cell Op Sx \&Ta Ar cell ...
 .Pp
-The
-.Cm args
-are phrases, a mix of macros and text corresponding to a line column,
-delimited by tabs or the special
-.Sq \&Ta
-pseudo-macro.
-Lines subsequent the
+The arguments consist of one or more lines of text and macros
+representing a complete table line.
+Cells within the line are delimited by tabs or by the special
+.Sx \&Ta
+block macro.
+The tab cell delimiter may only be used within the
 .Sx \&It
-are interpreted within the scope of the last phrase.
-Calling the pseudo-macro
-.Sq \&Ta
-will open a new phrase scope (this must occur on a macro line to be
-interpreted as a macro).
-Note that the tab phrase delimiter may only be used within the
+line itself; on following lines, only the
+.Sx \&Ta
+macro can be used to delimit cells, and
+.Sx \&Ta
+is only recognized as a macro when called by other macros,
+not as the first macro on a line.
+.Pp
+Note that quoted strings may span tab-delimited cells on an
 .Sx \&It
-line itself.
-Subsequent this, only the
-.Sq \&Ta
-pseudo-macro may be used to delimit phrases.
-Furthermore, note that quoted sections propagate over tab-delimited
-phrases on an
-.Sx \&It ,
-for example,
+line.
+For example,
 .Pp
 .Dl .It \(dqcol1 ; <TAB> col2 ;\(dq \&;
 .Pp
@@ -2090,9 +2205,9 @@ The syntax is as follows:
 The
 .Ar library
 parameter may be a system library, such as
-.Ar libz
+.Cm libz
 or
-.Ar libpam ,
+.Cm libpam ,
 in which case a small library description is printed next to the linker
 invocation; or a custom library, in which case the library name is
 printed in quotes.
@@ -2434,16 +2549,22 @@ block is used within a SEE ALSO section, a vertical sp
 before the rendered output, else the block continues on the current
 line.
 .Ss \&Rv
-Inserts text regarding a function call's return value.
-This macro must consist of the
-.Fl std
-argument followed by an optional
-.Ar function .
+Insert a standard sentence regarding a function call's return value of 0
+on success and \-1 on error, with the
+.Va errno
+libc global variable set on error.
+Its syntax is as follows:
+.Pp
+.D1 Pf \. Sx \&Rv Fl std Op Ar function ...
+.Pp
 If
 .Ar function
-is not provided, the document's name as stipulated by the first
+is not specified, the document's name set by
 .Sx \&Nm
-is provided.
+is used.
+Multiple
+.Ar function
+arguments are treated as separate functions.
 .Pp
 See also
 .Sx \&Ex .
@@ -2472,9 +2593,9 @@ Its syntax is as follows:
 .D1 Pf \. Sx \&Sm Cm on | off
 .Pp
 By default, spacing is
-.Ar on .
+.Cm on .
 When switched
-.Ar off ,
+.Cm off ,
 no white space is inserted between macro arguments and between the
 output generated from adjacent macros, but text lines
 still get normal spacing between words and sentences.
@@ -2628,6 +2749,11 @@ See also
 .Sx \&Li ,
 and
 .Sx \&Em .
+.Ss \&Ta
+Table cell separator in
+.Sx \&Bl Fl column
+lists; can only be used below
+.Sx \&It .
 .Ss \&Tn
 Format a tradename.
 .Pp
@@ -2777,7 +2903,7 @@ Newer groff and mandoc print
 .Qq AT&T UNIX
 and the arguments.
 .It
-.Sx \&Bd Fl column
+.Sx \&Bl Fl column
 does not recognize trailing punctuation characters when they immediately
 precede tabulator characters, but treats them as normal text and
 outputs a space before them.
@@ -2837,7 +2963,7 @@ In new groff and mandoc, any list may be nested by def
 lists will restart the sequence only for the sub-list.
 .It
 .Sx \&Li
-followed by a reserved character is incorrectly used in some manuals
+followed by a delimiter is incorrectly used in some manuals
 instead of properly quoting that character, which sometimes works with
 historic groff.
 .It