===================================================================
RCS file: /cvs/mandoc/mdoc.7,v
retrieving revision 1.109
retrieving revision 1.117
diff -u -p -r1.109 -r1.117
--- mandoc/mdoc.7	2010/05/26 09:35:35	1.109
+++ mandoc/mdoc.7	2010/06/04 20:57:26	1.117
@@ -1,4 +1,4 @@
-.\"	$Id: mdoc.7,v 1.109 2010/05/26 09:35:35 kristaps Exp $
+.\"	$Id: mdoc.7,v 1.117 2010/06/04 20:57:26 kristaps Exp $
 .\"
 .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@bsd.lv>
 .\"
@@ -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: May 26 2010 $
+.Dd $Mdocdate: June 4 2010 $
 .Dt MDOC 7
 .Os
 .Sh NAME
@@ -343,18 +343,15 @@ file:
 \&.Dd $\&Mdocdate$
 \&.Dt mdoc 7
 \&.Os
-\&.
 \&.Sh NAME
 \&.Nm foo
 \&.Nd a description goes here
 \&.\e\*q The next is for sections 2, 3, & 9 only.
 \&.\e\*q .Sh LIBRARY
-\&.
 \&.Sh SYNOPSIS
 \&.Nm foo
 \&.Op Fl options
 \&.Ar
-\&.
 \&.Sh DESCRIPTION
 The
 \&.Nm
@@ -1139,22 +1136,18 @@ macro.
 These dictate the width of columns either as
 .Sx Scaling Widths
 or literal text.
-List entry bodies must be left empty.
-Column bodies have the following syntax:
-.Pp
-.D1 .It col1 <TAB> ... coln
-.D1 .It col1 Ta ... coln
-.D1 .It col1 <TAB> col2 Ta coln
-.Pp
-where columns may be separated by tabs, the literal string
-.Qq Ta ,
-or a mixture of both.
-These are equivalent except that quoted sections propogate over tabs,
-for example,
-.Pp
-.D1 .It \(dqcol1 ; <TAB> col2 ;\(dq ;
-.Pp
-will preserve the semicolon whitespace except for the last.
+If the initial macro of a
+.Fl column
+list is not an
+.Sx \&It ,
+an
+.Sx \&It
+context spanning each line is implied until an
+.Sx \&It
+line macro is encountered, at which point list bodies are interpreted as
+described in the
+.Sx \&It
+documentation.
 .It Fl dash
 A list offset by a dash (hyphen).
 The head of list entries must be empty.
@@ -1209,6 +1202,9 @@ after the head as specified by the
 .Fl width
 argument.
 .El
+.Pp
+See also
+.Sx \&It .
 .Ss \&Bo
 Begins a block enclosed by square brackets.
 Does not have any head arguments.
@@ -1336,6 +1332,11 @@ See also
 and
 .Sx \&Dl .
 .Ss \&Db
+Start a debugging context.
+This macro is parsed, but generally ignored.
+Its calling syntax is as follows:
+.Pp
+.D1 \. Ns Sx \&Db Cm on | off
 .Ss \&Dc
 Closes a
 .Sx \&Do
@@ -1408,13 +1409,15 @@ This is the mandatory second macro of any
 file.
 Its calling syntax is as follows:
 .Pp
-.D1 \. Ns Sx \&Dt Cm title section Op Cm volume | arch
+.D1 \. Ns Sx \&Dt Op Cm title Op Cm section Op Cm volume | arch
 .Pp
 Its arguments are as follows:
 .Bl -tag -width Ds -offset Ds
 .It Cm title
-The document's title (name).
-This should be capitalised and is required.
+The document's title (name), defaulting to
+.Qq UNKNOWN
+if unspecified.
+It should be capitalised.
 .It Cm section
 The manual section.
 This may be one of
@@ -1451,8 +1454,9 @@ This may be one of
 or
 .Ar paper
 .Pq paper .
-It is also required and should correspond to the manual's filename
-suffix.
+It should correspond to the manual's filename suffix and defaults to
+.Qq 1
+if unspecified.
 .It Cm volume
 This overrides the volume inferred from
 .Ar section .
@@ -1524,7 +1528,6 @@ Examples:
 .D1 \&.Dt FOO 1
 .D1 \&.Dt FOO 4 KM
 .D1 \&.Dt FOO 9 i386
-.D1 \&.Dt FOO 9 KM i386
 .Pp
 See also
 .Sx \&Dd
@@ -1561,6 +1564,13 @@ and
 .Ss \&Ef
 .Ss \&Ek
 .Ss \&El
+Ends a list context started by
+.Sx \&Bl .
+.Pp
+See also
+.Sx \&Bl
+and
+.Sx \&It .
 .Ss \&Em
 Denotes text that should be emphasised.
 Note that this is a presentation term and should not be used for
@@ -1600,8 +1610,33 @@ is not provided, the document's name as stipulated in
 .Sx \&Nm
 is provided.
 .Ss \&Fa
+Function argument.
+This may be invoked for names with or without the corresponding type.
+It is also used to specify the field name of a structure.
+Most often, the
+.Sx \&Fa
+macro is used in the
+.Em SYNOPSIS
+section when documenting multi-line function prototypes.
+If invoked with multiple arguments, the arguments are separated by a
+comma.
+Furthermore, if the following macro is another
+.Sx \&Fa ,
+the last argument will also have a trailing comma.
+.Pp
+Examples:
+.D1 \&.Fa \(dqconst char *p\(dq
+.D1 \&.Fa \(dqint a\(dq \(dqint b\(dq \(dqint c\(dq
+.D1 \&.Fa foo
 .Ss \&Fc
 .Ss \&Fd
+Historically used to document include files.
+This usage has been deprecated in favour of
+.Sx \&In .
+Do not use this macro.
+.Pp
+See also
+.Sx \&In .
 .Ss \&Fl
 Command-line flag.
 Used when listing arguments to command-line utilities.
@@ -1645,6 +1680,86 @@ and
 .Ss \&Ic
 .Ss \&In
 .Ss \&It
+A list item.  The syntax of this macro depends on the list type.
+.Pp
+Lists
+of type
+.Fl hang ,
+.Fl ohang ,
+.Fl inset ,
+and
+.Fl diag
+have the following calling syntax:
+.Pp
+.D1 \. Ns Sx \&It Cm args
+.Pp
+Lists of type
+.Fl bullet ,
+.Fl dash ,
+.Fl enum ,
+.Fl hyphen
+and
+.Fl item
+have the following calling syntax:
+.Pp
+.D1 \. Ns Sx \&It
+.Pp
+with subsequent lines interpreted within the scope of the
+.Sx \&It
+until either a closing
+.Sx \&El
+or another
+.Sx \&It .
+.Pp
+The
+.Fl tag
+list has syntax
+.Pp
+.D1 \. Ns Sx \&It Op Cm args
+.Pp
+with subsequent lines interpreted as with
+.Fl bullet
+and family.
+The line arguments correspond to the list's left-hand side; body
+arguments correspond to the list's contents.
+.Pp
+The
+.Fl column
+list is the most complicated.
+Its syntax is
+.Pp
+.D1 \. Ns Sx \&It Op Cm args
+.Pp
+where
+.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
+.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
+.Sx \&It
+line itself.
+Subsequent this, only the
+.Sq \&Ta
+pseudo-macro may be used to delimit phrases.
+Furthermore, note that quoted sections propogate over tab-delimited
+phrases on an
+.Sx \&It ,
+for example,
+.Pp
+.D1 .It \(dqcol1 ; <TAB> col2 ;\(dq ;
+.Pp
+will preserve the semicolon whitespace except for the last.
+.Pp
+See also
+.Sx \&Bl .
 .Ss \&Lb
 Specify a library.
 The calling syntax is as follows:
@@ -1684,6 +1799,15 @@ See also
 .Ss \&Lp
 .Ss \&Ms
 .Ss \&Mt
+Format a
+.Qq mailto:
+hyperlink.
+The calling syntax is as follows:
+.Pp
+.D1 \. Ns Sx \&Mt Cm address
+.Pp
+Examples:
+.D1 \&.Mt discuss@manpages.bsd.lv
 .Ss \&Nd
 .Ss \&Nm
 .Ss \&No
@@ -1820,6 +1944,8 @@ line.
 .Ss \&Sy
 .Ss \&Tn
 .Ss \&Ud
+Prints out
+.Dq currently under development.
 .Ss \&Ux
 Format the UNIX name.
 Accepts no argument.
@@ -1908,6 +2034,11 @@ Heirloom troff, the other significant troff implementa
 \-mdoc, is similar to historic groff.
 .Pp
 .Bl -dash -compact
+.It
+groff does not accept the
+.Sq \&Ta
+pseudo-macro as a line macro.
+mandoc does.
 .It
 The comment syntax
 .Sq \e."