===================================================================
RCS file: /cvs/mandoc/mdoc.7,v
retrieving revision 1.79
retrieving revision 1.85
diff -u -p -r1.79 -r1.85
--- mandoc/mdoc.7	2010/01/01 13:35:30	1.79
+++ mandoc/mdoc.7	2010/03/21 18:16:41	1.85
@@ -1,4 +1,4 @@
-.\"	$Id: mdoc.7,v 1.79 2010/01/01 13:35:30 kristaps Exp $
+.\"	$Id: mdoc.7,v 1.85 2010/03/21 18:16:41 kristaps Exp $
 .\"
 .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@kth.se>
 .\"
@@ -14,7 +14,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: January 1 2010 $
+.Dd $Mdocdate: March 21 2010 $
 .Dt MDOC 7
 .Os
 .
@@ -132,7 +132,7 @@ and
 Terms may be text-decorated using the
 .Sq \ef
 escape followed by an indicator: B (bold), I, (italic), R (Roman), or P
-(revert to previous mode):  
+(revert to previous mode):
 .Pp
 .D1 \efBbold\efR \efIitalic\efP
 .Pp
@@ -170,19 +170,19 @@ for arbitrary-digit numerals:
 .D1 \es+(10much bigger\es-(10
 .D1 \es+'100'much much bigger\es-'100'
 .Pp
-Note these forms are 
+Note these forms are
 .Em not
-recommended for 
+recommended for
 .Nm ,
 which encourages semantic annotation.
 .
 .
 .Ss Predefined Strings
-Historically, 
+Historically,
 .Xr groff 1
-also defined a set of package-specific 
+also defined a set of package-specific
 .Dq predefined strings ,
-which, like 
+which, like
 .Sx Special Characters ,
 demark special output characters and strings by way of input codes.
 Predefined strings are escaped with the slash-asterisk,
@@ -343,7 +343,7 @@ and
 .Sx \&Os
 macros, is required for every document.
 .Pp
-The first section (sections are denoted by 
+The first section (sections are denoted by
 .Sx \&Sh )
 must be the NAME section, consisting of at least one
 .Sx \&Nm
@@ -419,6 +419,11 @@ The
 macro(s) must precede the
 .Sx \&Nd
 macro.
+.Pp
+See
+.Sx \&Nm
+and
+.Sx \&Nd .
 .
 .It Em LIBRARY
 The name of the library containing the documented material, which is
@@ -429,12 +434,11 @@ this is as follows:
 .Ed
 .Pp
 See
-.Sx \&Lb
-for details.
+.Sx \&Lb .
 .
 .It Em SYNOPSIS
 Documents the utility invocation syntax, function call syntax, or device
-configuration. 
+configuration.
 .Pp
 For the first, utilities (sections 1, 6, and 8), this is
 generally structured as follows:
@@ -465,11 +469,19 @@ And for the third, configurations (section 4):
 \&.Cd \*qit* at isa? port 0x4e\*q
 .Ed
 .Pp
-Manuals not in these sections generally don't need a 
+Manuals not in these sections generally don't need a
 .Em SYNOPSIS .
+.Pp
+See
+.Sx \&Op ,
+.Sx \&Cd ,
+.Sx \&Fn ,
+.Sx \&Ft ,
+and
+.Sx \&Vt .
 .
 .It Em DESCRIPTION
-This expands upon the brief, one-line description in 
+This expands upon the brief, one-line description in
 .Em NAME .
 It usually contains a break-down of the options (if documenting a
 command), such as:
@@ -480,6 +492,7 @@ The arguments are as follows:
 Print verbose information.
 \&.El
 .Ed
+.Pp
 Manuals not documenting a command won't include the above fragment.
 .
 .It Em IMPLEMENTATION NOTES
@@ -535,7 +548,8 @@ for manuals in sections 1, 6, and 8; however, this pra
 discouraged.
 .Pp
 See
-.Sx \&Bl No \-diag .
+.Sx \&Bl
+.Fl diag .
 .
 .It Em ERRORS
 Documents error handling in sections 2, 3, and 9.
@@ -669,7 +683,7 @@ All macros have bodies; some
 don't have heads; only one
 .Po
 .Sx \&It Fl column
-.Pc 
+.Pc
 has multiple heads.
 .Bd -literal -offset indent
 \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead... \(lBTa head...\(rB\(rB
@@ -756,7 +770,16 @@ or end of line.
 .It Sx \&Ql  Ta    Yes      Ta    Yes
 .It Sx \&Qq  Ta    Yes      Ta    Yes
 .It Sx \&Sq  Ta    Yes      Ta    Yes
+.It Sx \&Vt  Ta    Yes      Ta    Yes
 .El
+.Pp
+Note that the
+.Sx \&Vt
+macro is a
+.Sx Block partial-implicit
+only when invoked as the first macro
+in a SYNOPSIS section line, else it is
+.Sx In-line .
 .
 .
 .Ss In-line
@@ -849,10 +872,10 @@ then the macro accepts an arbitrary number of argument
 .It Sx \&Ux  Ta    Yes      Ta    Yes      Ta    n
 .It Sx \&Va  Ta    Yes      Ta    Yes      Ta    n
 .It Sx \&Vt  Ta    Yes      Ta    Yes      Ta    >0
-.It Sx \&Xr  Ta    Yes      Ta    Yes      Ta    >0, <3
+.It Sx \&Xr  Ta    Yes      Ta    Yes      Ta    >0
 .It Sx \&br  Ta    \&No     Ta    \&No     Ta    0
 .It Sx \&sp  Ta    \&No     Ta    \&No     Ta    1
-.El   
+.El
 .
 .
 .Sh REFERENCE
@@ -1012,7 +1035,7 @@ a function:
 .Ed
 .
 .Ss \&Aq
-Encloses its arguments in angled brackets.  
+Encloses its arguments in angled brackets.
 .Pp
 Examples:
 .Bd -literal -offset indent
@@ -1059,7 +1082,7 @@ Note that these parameters do not begin with a hyphen.
 .Pp
 Examples:
 .Bd -literal -offset indent
-\&.At 
+\&.At
 \&.At V.1
 .Ed
 .Pp
@@ -1160,7 +1183,60 @@ and
 .Ss \&Bf
 .Ss \&Bk
 .Ss \&Bl
-.
+.\" Begins a list composed of one or more list entries.  A list entry is
+.\" specified by the
+.\" .Sx \&It
+.\" macro, which consists of a head and optional body.  By default, a list
+.\" is preceded by a blank line.  A list must specify one of the following
+.\" list types:
+.\" .Bl -tag -width 12n
+.\" .It Fl bullet
+.\" A list offset by a bullet.  The head of list entries must be empty.
+.\" List entry bodies are justified after the bullet.
+.\" .It Fl column
+.\" A columnated list.  The number of columns is specified as arguments to
+.\" the
+.\" .Sx \&Bl
+.\" macro (the deprecated form of following the invocation of
+.\" .Fl column
+.\" is also accepted).  Arguments dictate the width of columns specified in
+.\" list entries.  List entry bodies must be left empty.  Columns specified
+.\" in the list entry head are justified to their position in the sequence
+.\" of columns.
+.\" .It Fl dash
+.\" A list offset by a dash (hyphen).  The head of list entries must be
+.\" empty.  List entry bodies are justified past the dash.
+.\" .It Fl diag
+.\" Like
+.\" .Fl inset
+.\" lists, but with additional formatting to the head.
+.\" .It Fl enum
+.\" A list offset by a number indicating list entry position.  The head of
+.\" list entries must be empty.  List entry bodies are justified past the
+.\" enumeration.
+.\" .It Fl hang
+.\" Like
+.\" .Fl tag ,
+.\" but instead of list bodies justifying to the head on the first line,
+.\" they trail the head text.
+.\" .It Fl hyphen
+.\" Synonym for
+.\" .Fl dash .
+.\" .It Fl inset
+.\" Like
+.\" .Fl tag ,
+.\" but list entry bodies aren't justified.
+.\" .It Fl item
+.\" An un-justified list.  This produces blocks of text.
+.\" .It Fl ohang
+.\" List bodies are placed on the line following the head.
+.\" .It Fl tag
+.\" A list offset by list entry heads.  List entry bodies are justified
+.\" after the head.
+.\" .El
+.\" .Pp
+.\" More...
+.\" .
 .Ss \&Bo
 Begins a block enclosed by square brackets.  Does not have any head
 arguments.
@@ -1175,7 +1251,7 @@ See also
 .Sx \&Bq .
 .
 .Ss \&Bq
-Encloses its arguments in square brackets.  
+Encloses its arguments in square brackets.
 .Pp
 Examples:
 .Bd -literal -offset indent
@@ -1322,7 +1398,7 @@ manual.  Its calling syntax is as follows:
 .Pp
 .D1 \. Ns Sx \&Dd Cm date
 .Pp
-The 
+The
 .Cm date
 field may be either
 .Ar $\&Mdocdate$ ,
@@ -1371,7 +1447,7 @@ See also
 .Sx \&Dq .
 .
 .Ss \&Dq
-Encloses its arguments in double quotes.  
+Encloses its arguments in double quotes.
 .Pp
 Examples:
 .Bd -literal -offset indent
@@ -1477,6 +1553,7 @@ subsequent that.  It, too, is optional.  It must be on
 .Ar hppa64 ,
 .Ar i386 ,
 .Ar landisk ,
+.Ar longsoon ,
 .Ar luna88k ,
 .Ar mac68k ,
 .Ar macppc ,
@@ -1825,9 +1902,58 @@ and
 .
 .Ss \&Va
 .Ss \&Vt
+A variable type.  This is also used for indicating global variables in the
+SYNOPSIS section, in which case a variable name is also specified.  Note that
+it accepts
+.Sx Block partial-implicit
+syntax when invoked as the first macro in the SYNOPSIS section, else it
+accepts ordinary
+.Sx In-line
+syntax.
+.Pp
+Note that this should not be confused with
+.Sx \&Ft ,
+which is used for function return types.
+.Pp
+Examples:
+.Bd -literal -offset indent
+\&.Vt unsigned char
+\&.Vt extern const char * const sys_signame[] ;
+.Ed
+.Pp
+See also
+.Sx \&Ft
+and
+.Sx \&Va .
+.
 .Ss \&Xc
 .Ss \&Xo
 .Ss \&Xr
+Link to another manual
+.Pq Qq cross-reference .
+Its calling syntax is
+.Pp
+.D1 \. Ns Sx \&Xr Cm name section
+.Pp
+The
+.Cm name
+and
+.Cm section
+are the name and section of the linked manual.  If
+.Cm section
+is followed by non-punctuation, an
+.Sx \&Ns
+is inserted into the token stream.  This behaviour is for compatibility
+with
+.Xr groff 1 .
+.Pp
+Examples:
+.Bd -literal -offset indent
+\&.Xr mandoc 1
+\&.Xr mandoc 1 ;
+\&.Xr mandoc 1 s behaviour
+.Ed
+.
 .Ss \&br
 .Ss \&sp
 .
@@ -1846,9 +1972,20 @@ file re-write
 .Pp
 .Bl -dash -compact
 .It
-Historic 
+The comment syntax
+.Sq \e."
+is no longer accepted.
+.It
+In
+.Xr groff 1 ,
+the
+.Sx \&Pa
+macro does not format its arguments when used in the FILES section under
+certain list types.  This irregular behaviour has been discontinued.
+.It
+Historic
 .Xr groff 1
-does not print a dash for empty 
+does not print a dash for empty
 .Sx \&Fl
 arguments.  This behaviour has been discontinued.
 .It
@@ -1861,7 +1998,7 @@ normalised.
 Negative scaling units are now truncated to zero instead of creating
 interesting conditions, such as with
 .Sx \&sp
-.Cm \-1i .
+.Fl 1i .
 Furthermore, the
 .Sq f
 scaling unit, while accepted, is rendered as the default unit.