===================================================================
RCS file: /cvs/mandoc/mdoc.7,v
retrieving revision 1.157
retrieving revision 1.167
diff -u -p -r1.157 -r1.167
--- mandoc/mdoc.7	2010/08/29 11:28:09	1.157
+++ mandoc/mdoc.7	2010/11/30 21:44:59	1.167
@@ -1,4 +1,4 @@
-.\"	$Id: mdoc.7,v 1.157 2010/08/29 11:28:09 kristaps Exp $
+.\"	$Id: mdoc.7,v 1.167 2010/11/30 21:44:59 schwarze Exp $
 .\"
 .\" Copyright (c) 2009, 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: August 29 2010 $
+.Dd $Mdocdate: November 30 2010 $
 .Dt MDOC 7
 .Os
 .Sh NAME
@@ -343,13 +343,14 @@ The
 \&.Nm
 utility processes files ...
 \&.\e\*q .Sh IMPLEMENTATION NOTES
+\&.\e\*q Not used in OpenBSD.
 \&.\e\*q .Sh RETURN VALUES
 \&.\e\*q For sections 2, 3, & 9 only.
 \&.\e\*q .Sh ENVIRONMENT
 \&.\e\*q For sections 1, 6, 7, & 8 only.
 \&.\e\*q .Sh FILES
 \&.\e\*q .Sh EXIT STATUS
-\&.\e\*q For sections 1 & 8 only.
+\&.\e\*q For sections 1, 6, & 8 only.
 \&.\e\*q .Sh EXAMPLES
 \&.\e\*q .Sh DIAGNOSTICS
 \&.\e\*q For sections 1, 4, 6, 7, & 8 only.
@@ -603,20 +604,21 @@ closes it out.
 .Pp
 The
 .Em Callable
-column indicates that the macro may be called subsequent to the initial
-line-macro.
-If a macro is not callable, then its invocation after the initial line
-macro is interpreted as opaque text, such that
+column indicates that the macro may also be called by passing its name
+as an argument to another macro.
+If a macro is not callable but its name appears as an argument
+to another macro, it is interpreted as opaque text.
+For example,
 .Sq \&.Fl \&Sh
 produces
 .Sq Fl \&Sh .
 .Pp
 The
 .Em Parsed
-column indicates whether the macro may be followed by further
-(ostensibly callable) macros.
-If a macro is not parsed, subsequent macro invocations on the line
-will be interpreted as opaque text.
+column indicates whether the macro may call other macros by receiving
+their names as arguments.
+If a macro is not parsed but the name of another macro appears
+as an argument, it is interpreted as opaque text.
 .Pp
 The
 .Em Scope
@@ -1075,7 +1077,8 @@ implementations render it poorly.
 Left- and right-justify the block.
 .It Fl literal
 Do not justify the block at all.
-Preserve white space as it appears in the input.
+Preserve white space and newlines as they appear in the input, including
+if it follows a macro.
 .It Fl ragged
 Only left-justify the block.
 .It Fl unfilled
@@ -1645,6 +1648,7 @@ It must be one of
 .Ar luna88k ,
 .Ar mac68k ,
 .Ar macppc ,
+.Ar mips64 ,
 .Ar mvme68k ,
 .Ar mvme88k ,
 .Ar mvmeppc ,
@@ -1868,6 +1872,9 @@ Examples:
 \&.Fn funcname
 .Ed
 .Pp
+When referring to a function documented in another manual page, use
+.Sx \&Xr
+instead.
 See also
 .Sx MANUAL STRUCTURE
 and
@@ -2118,6 +2125,9 @@ Examples:
 Format a
 .Dq mailto:
 hyperlink.
+If an argument is not provided, the string
+.Dq \(ti
+is used as a default.
 Its syntax is as follows:
 .Pp
 .D1 Pf \. Sx \&Mt Cm address
@@ -2299,6 +2309,9 @@ and
 .Sx \&Ux .
 .Ss \&Pa
 A file-system path.
+If an argument is not provided, the string
+.Dq \(ti
+is used as a default.
 .Pp
 Examples:
 .D1 \&.Pa /usr/bin/mandoc
@@ -2653,9 +2666,13 @@ and
 Close a scope opened by
 .Sx \&Xo .
 .Ss \&Xo
-Open an extension scope.
-This macro originally existed to extend the 9-argument limit of troff;
-since this limit has been lifted, the macro has been deprecated.
+Extend the header of an
+.Sx \&It
+macro or the body of a partial-implicit block macro
+beyond the end of the input line.
+This macro originally existed to work around the 9-argument limit
+of historic
+.Xr roff 7 .
 .Ss \&Xr
 Link to another manual
 .Pq Qq cross-reference .
@@ -2709,10 +2726,10 @@ troff implementations, at this time limited to GNU tro
 .Pq Qq groff .
 The term
 .Qq historic groff
-refers to groff versions before the
+refers to groff versions before 1.17,
+which featured a significant update of the
 .Pa doc.tmac
-file re-write
-.Pq somewhere between 1.15 and 1.19 .
+file.
 .Pp
 Heirloom troff, the other significant troff implementation accepting
 \-mdoc, is similar to historic groff.
@@ -2803,6 +2820,11 @@ can only be called by other macros, but not at the beg
 .Sx \&%C
 is not implemented.
 .It
+Historic groff only allows up to eight or nine arguments per macro input
+line, depending on the exact situation.
+Providing more arguments causes garbled output.
+The number of arguments on one input line is not limited with mandoc.
+.It
 Historic groff has many un-callable macros.
 Most of these (excluding some block-level macros) are callable
 in new groff and mandoc.
@@ -2868,6 +2890,7 @@ standalone double-quote in formatted output.
 This is not supported by mandoc.
 .El
 .Sh SEE ALSO
+.Xr man 1 ,
 .Xr mandoc 1 ,
 .Xr mandoc_char 7
 .Sh HISTORY