===================================================================
RCS file: /cvs/mandoc/mdoc.7,v
retrieving revision 1.109
retrieving revision 1.139
diff -u -p -r1.109 -r1.139
--- mandoc/mdoc.7	2010/05/26 09:35:35	1.109
+++ mandoc/mdoc.7	2010/07/19 15:43:10	1.139
@@ -1,6 +1,7 @@
-.\"	$Id: mdoc.7,v 1.109 2010/05/26 09:35:35 kristaps Exp $
+.\"	$Id: mdoc.7,v 1.139 2010/07/19 15:43:10 kristaps Exp $
 .\"
-.\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@bsd.lv>
+.\" Copyright (c) 2009, 2010 Kristaps Dzonsons <kristaps@bsd.lv>
+.\" Copyright (c) 2010 Ingo Schwarze <schwarze@openbsd.org>
 .\"
 .\" Permission to use, copy, modify, and distribute this software for any
 .\" purpose with or without fee is hereby granted, provided that the above
@@ -14,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 26 2010 $
+.Dd $Mdocdate: July 19 2010 $
 .Dt MDOC 7
 .Os
 .Sh NAME
@@ -26,17 +27,20 @@ The
 language is used to format
 .Bx
 .Ux
-manuals.  In this reference document, we describe its syntax, structure,
-and usage.  Our reference implementation is mandoc; the
+manuals.
+In this reference document, we describe its syntax, structure, and
+usage.
+Our reference implementation is mandoc; the
 .Sx COMPATIBILITY
 section describes compatibility with other troff \-mdoc implementations.
 .Pp
 An
 .Nm
-document follows simple rules:  lines beginning with the control
+document follows simple rules: lines beginning with the control
 character
 .Sq \.
-are parsed for macros.  Other lines are interpreted within the scope of
+are parsed for macros.
+Other lines are interpreted within the scope of
 prior macros:
 .Bd -literal -offset indent
 \&.Sh Macro lines change control state.
@@ -45,18 +49,20 @@ Other lines are interpreted within the current state.
 .Sh LANGUAGE SYNTAX
 .Nm
 documents may contain only graphable 7-bit ASCII characters, the space
-character, and, in certain circumstances, the tab character.  All
-manuals must have
+character, and, in certain circumstances, the tab character.
+All manuals must have
 .Ux
 line terminators.
 .Ss Comments
 Text following a
-.Sq \e" ,
+.Sq \e\*q ,
 whether in a macro or free-form text line, is ignored to the end of
-line.  A macro line with only a control character and comment escape,
-.Sq \&.\e" ,
-is also ignored.  Macro lines with only a control charater and optionally
-whitespace are stripped from input.
+line.
+A macro line with only a control character and comment escape,
+.Sq \&.\e\*q ,
+is also ignored.
+Macro lines with only a control character and optionally whitespace are
+stripped from input.
 .Ss Reserved Characters
 Within a macro line, the following characters are reserved:
 .Pp
@@ -122,7 +128,7 @@ escape followed by an indicator: B (bold), I, (italic)
 A numerical representation 3, 2, or 1 (bold, italic, and Roman,
 respectively) may be used instead.
 A text decoration is valid within
-the current font scope only:  if a macro opens a font scope alongside
+the current font scope only: if a macro opens a font scope alongside
 its own scope, such as
 .Sx \&Bf
 .Cm \&Sy ,
@@ -134,28 +140,7 @@ If
 is specified outside of any font scope, such as in unenclosed, free-form
 text, it will affect the remainder of the document.
 .Pp
-Text may also be sized with the
-.Sq \es
-escape, whose syntax is one of
-.Sq \es+-n
-for one-digit numerals;
-.Sq \es(+-nn
-or
-.Sq \es+-(nn
-for two-digit numerals; and
-.Sq \es[+-N] ,
-.Sq \es+-[N] ,
-.Sq \es'+-N' ,
-or
-.Sq \es+-'N'
-for arbitrary-digit numerals:
-.Pp
-.D1 \es+1bigger\es-1
-.D1 \es[+10]much bigger\es[-10]
-.D1 \es+(10much bigger\es-(10
-.D1 \es+'100'much much bigger\es-'100'
-.Pp
-Note these forms are
+Note this form is
 .Em not
 recommended for
 .Nm ,
@@ -167,7 +152,7 @@ also defined a set of package-specific
 .Dq predefined strings ,
 which, like
 .Sx Special Characters ,
-demark special output characters and strings by way of input codes.
+mark special output characters and strings by way of input codes.
 Predefined strings are escaped with the slash-asterisk,
 .Sq \e* :
 single-character
@@ -333,8 +318,11 @@ must be the NAME section, consisting of at least one
 followed by
 .Sx \&Nd .
 .Pp
-Following that, convention dictates specifying at least the SYNOPSIS and
-DESCRIPTION sections, although this varies between manual sections.
+Following that, convention dictates specifying at least the
+.Em SYNOPSIS
+and
+.Em DESCRIPTION
+sections, although this varies between manual sections.
 .Pp
 The following is a well-formed skeleton
 .Nm
@@ -343,18 +331,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
@@ -453,13 +438,44 @@ And for the third, configurations (section 4):
 Manuals not in these sections generally don't need a
 .Em SYNOPSIS .
 .Pp
-See
-.Sx \&Op ,
+Some macros are displayed differently in the
+.Em SYNOPSIS
+section, particularly
+.Sx \&Nm ,
 .Sx \&Cd ,
+.Sx \&Fd ,
 .Sx \&Fn ,
-.Sx \&Ft ,
+.Sx \&Fo ,
+.Sx \&In ,
+.Sx \&Vt ,
 and
-.Sx \&Vt .
+.Sx \&Ft .
+All of these macros are output on their own line.
+If two such dissimilar macros are pair-wise invoked (except for
+.Sx \&Ft
+before
+.Sx \&Fo
+or
+.Sx \&Fn ) ,
+they are separated by a vertical space, unless in the case of
+.Sx \&Fo ,
+.Sx \&Fn ,
+and
+.Sx \&Ft ,
+which are always separated by vertical space.
+.Pp
+When text and macros following an
+.Sx \&Nm
+macro starting an input line span multiple output lines,
+all output lines but the first will be indented to align
+with the text immediately following the
+.Sx \&Nm
+macro, up to the next
+.Sx \&Nm ,
+.Sx \&Sx ,
+or
+.Sx \&Ss
+macro or the end of an enclosing block, whichever comes first.
 .It Em DESCRIPTION
 This expands upon the brief, one-line description in
 .Em NAME .
@@ -654,9 +670,20 @@ has multiple heads.
 .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope
 .It Sx \&It  Ta    \&No     Ta    Yes      Ta    closed by Sx \&It , Sx \&El
 .It Sx \&Nd  Ta    \&No     Ta    \&No     Ta    closed by Sx \&Sh
+.It Sx \&Nm  Ta    \&No     Ta  Yes Ta closed by Sx \&Nm , Sx \&Sh , Sx \&Ss
 .It Sx \&Sh  Ta    \&No     Ta    \&No     Ta    closed by Sx \&Sh
 .It Sx \&Ss  Ta    \&No     Ta    \&No     Ta    closed by Sx \&Sh , Sx \&Ss
 .El
+.Pp
+Note that the
+.Sx \&Nm
+macro is a
+.Sx Block full-implicit
+macro only when invoked as the first macro
+in a
+.Em SYNOPSIS
+section line, else it is
+.Sx In-line .
 .Ss Block partial-explicit
 Like block full-explicit, but also with single-line scope.
 Each has at least a body and, in limited circumstances, a head
@@ -836,14 +863,17 @@ For the scoping of individual macros, see
 .Ss \&%A
 Author name of an
 .Sx \&Rs
-block.  Multiple authors should each be accorded their own
+block.
+Multiple authors should each be accorded their own
 .Sx \%%A
-line.  Author names should be ordered with full or abbreviated
-forename(s) first, then full surname.
+line.
+Author names should be ordered with full or abbreviated forename(s)
+first, then full surname.
 .Ss \&%B
 Book title of an
 .Sx \&Rs
-block.  This macro may also be used in a non-bibliographic context when
+block.
+This macro may also be used in a non-bibliographic context when
 referring to book titles.
 .Ss \&%C
 Publication city or location of an
@@ -856,8 +886,8 @@ this macro is not implemented in
 .Ss \&%D
 Publication date of an
 .Sx \&Rs
-block.  This should follow the reduced or canonical form syntax
-described in
+block.
+This should follow the reduced or canonical form syntax described in
 .Sx Dates .
 .Ss \&%I
 Publisher or issuer name of an
@@ -882,7 +912,8 @@ block.
 .Ss \&%Q
 Institutional author (school, government, etc.) of an
 .Sx \&Rs
-block.  Multiple institutional authors should each be accorded their own
+block.
+Multiple institutional authors should each be accorded their own
 .Sx \&%Q
 line.
 .Ss \&%R
@@ -892,8 +923,9 @@ block.
 .Ss \&%T
 Article title of an
 .Sx \&Rs
-block.  This macro may also be used in a non-bibliographical context
-when referring to article titles.
+block.
+This macro may also be used in a non-bibliographical context when
+referring to article titles.
 .Ss \&%U
 URI of reference document.
 .Ss \&%V
@@ -903,7 +935,8 @@ block.
 .Ss \&Ac
 Closes an
 .Sx \&Ao
-block.  Does not have any tail arguments.
+block.
+Does not have any tail arguments.
 .Ss \&Ad
 Address construct: usually in the context of an computational address in
 memory, not a physical (post) address.
@@ -954,8 +987,8 @@ Examples:
 See also
 .Sx \&Aq .
 .Ss \&Ap
-Inserts an apostrophe without any surrounding white-space.
-This is generally used as a grammatic device when referring to the verb
+Inserts an apostrophe without any surrounding whitespace.
+This is generally used as a grammatical device when referring to the verb
 form of a function:
 .Bd -literal -offset indent
 \&.Fn execve Ap d
@@ -1018,9 +1051,18 @@ and
 .Ss \&Bc
 Closes a
 .Sx \&Bo
-block.  Does not have any tail arguments.
+block.
+Does not have any tail arguments.
 .Ss \&Bd
 Begins a display block.
+Its syntax is as follows:
+.Bd -ragged -offset indent
+.Pf \. Sx \&Bd
+.Fl type
+.Op Fl offset Ar width
+.Op Fl compact
+.Ed
+.Pp
 A display is collection of macros or text which may be collectively
 offset or justified in a manner different from that
 of the enclosing context.
@@ -1045,9 +1087,9 @@ Centre-justify each line.
 The type must be provided first.
 Secondary arguments are as follows:
 .Bl -tag -width 12n -offset indent
-.It Fl offset Ar width
+.It Fl offset Ar val
 Offset by the value of
-.Ar width ,
+.Ar val ,
 which is interpreted as one of the following, specified in order:
 .Bl -item
 .It
@@ -1058,7 +1100,7 @@ the width of standard indentation;
 twice
 .Ar indent ;
 .Ar left ,
-which has no effect ;
+which has no effect;
 .Ar right ,
 which justifies to the right margin; and
 .Ar center ,
@@ -1076,16 +1118,9 @@ As a scaling unit following the syntax described in
 As the calculated string length of the opaque string.
 .El
 .Pp
-If unset, it will revert to the value of
-.Ar 8n
-as described in
-.Sx Scaling Widths .
+If not provided an argument, it will be ignored.
 .It Fl compact
 Do not assert a vertical space before the block.
-.It Fl file Ar file
-Prepend the file
-.Ar file
-before any text or macros within the block.
 .El
 .Pp
 Examples:
@@ -1100,9 +1135,75 @@ See also
 and
 .Sx \&Dl .
 .Ss \&Bf
+Change the font mode for a scoped block of text.
+Its syntax is as follows:
+.Bd -ragged -offset indent
+.Pf \. Sx \&Bf
+.Oo
+.Fl emphasis | literal | symbolic |
+.Cm \&Em | \&Li | \&Sy
+.Oc
+.Ed
+.Pp
+The
+.Fl emphasis
+and
+.Cm \&Em
+argument are equivalent, as are
+.Fl symbolic
+and
+.Cm \&Sy,
+and
+.Fl literal
+and
+.Cm \&Li .
+Without an argument, this macro does nothing.
+The font mode continues until broken by a new font mode in a nested
+scope or
+.Sx \&Ef
+is encountered.
+.Pp
+See also
+.Sx \&Li ,
+.Sx \&Ef ,
+and
+.Sx \&Sy .
 .Ss \&Bk
+Begins a collection of macros or text not breaking the line.
+Its syntax is as follows:
+.Pp
+.D1 Pf \. Sx \&Bk Fl words
+.Pp
+Subsequent arguments are ignored.
+The
+.Fl words
+argument is required.
+.Pp
+Each line within a keep block is kept intact, so the following example
+will not break within each
+.Sx \&Op
+macro line:
+.Bd -literal -offset indent
+\&.Bk \-words
+\&.Op Fl f Ar flags
+\&.Op Fl o Ar output
+\&.Ek
+.Ed
+.Pp
+Be careful in using over-long lines within a keep block!
+Doing so will clobber the right margin.
 .Ss \&Bl
 Begins a list composed of one or more list entries.
+Its syntax is as follows:
+.Bd -ragged -offset indent
+.Pf \. Sx \&Bl
+.Fl type
+.Op Fl width Ar val
+.Op Fl offset Ar val
+.Op Fl compact
+.Op HEAD ...
+.Ed
+.Pp
 A list is associated with a type, which is a required argument.
 Other arguments are
 .Fl width ,
@@ -1139,22 +1240,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.
@@ -1204,11 +1301,14 @@ The
 .Fl width
 argument is ignored.
 .It Fl tag
-A list offset by list entry heads.  List entry bodies are positioned
-after the head as specified by the
+A list offset by list entry heads.
+List entry bodies are positioned 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.
@@ -1240,7 +1340,8 @@ See also
 .Ss \&Brc
 Closes a
 .Sx \&Bro
-block.  Does not have any tail arguments.
+block.
+Does not have any tail arguments.
 .Ss \&Bro
 Begins a block enclosed by curly braces.
 Does not have any head arguments.
@@ -1308,7 +1409,7 @@ Examples:
 .Pp
 .Em Remarks :
 this macro is commonly abused by using quoted literals to retain
-white-space and align consecutive
+whitespace and align consecutive
 .Sx \&Cd
 declarations.
 This practise is discouraged.
@@ -1336,18 +1437,24 @@ See also
 and
 .Sx \&Dl .
 .Ss \&Db
+Start a debugging context.
+This macro is parsed, but generally ignored.
+Its syntax is as follows:
+.Pp
+.D1 Pf \. Sx \&Db Cm on | off
 .Ss \&Dc
 Closes a
 .Sx \&Do
-block.  Does not have any tail arguments.
+block.
+Does not have any tail arguments.
 .Ss \&Dd
 Document date.
 This is the mandatory first macro of any
 .Nm
 manual.
-Its calling syntax is as follows:
+Its syntax is as follows:
 .Pp
-.D1 \. Ns Sx \&Dd Cm date
+.D1 Pf \. Sx \&Dd Cm date
 .Pp
 The
 .Cm date
@@ -1382,8 +1489,8 @@ See also
 and
 .Sx \&D1 .
 .Ss \&Do
-Begins a block enclosed by double quotes.  Does not have any head
-arguments.
+Begins a block enclosed by double quotes.
+Does not have any head arguments.
 .Pp
 Examples:
 .D1 \&.D1 \&Do April is the cruellest month \&Dc \e(em T.S. Eliot
@@ -1391,7 +1498,9 @@ Examples:
 See also
 .Sx \&Dq .
 .Ss \&Dq
-Encloses its arguments in double quotes.
+Encloses its arguments in
+.Dq typographic
+double-quotes.
 .Pp
 Examples:
 .Bd -literal -offset indent -compact
@@ -1400,21 +1509,34 @@ Examples:
 .Ed
 .Pp
 See also
+.Sx \&Qq ,
+.Sx \&Sq ,
+and
 .Sx \&Do .
 .Ss \&Dt
 Document title.
 This is the mandatory second macro of any
 .Nm
 file.
-Its calling syntax is as follows:
+Its syntax is as follows:
+.Bd -ragged -offset indent
+.Pf \. Sx \&Dt
+.Oo
+.Cm title
+.Oo
+.Cm section
+.Op Cm volume | arch
+.Oc
+.Oc
+.Ed
 .Pp
-.D1 \. Ns Sx \&Dt Cm title 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
+.Dq UNKNOWN
+if unspecified.
+It should be capitalised.
 .It Cm section
 The manual section.
 This may be one of
@@ -1451,8 +1573,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
+.Dq 1
+if unspecified.
 .It Cm volume
 This overrides the volume inferred from
 .Ar section .
@@ -1524,7 +1647,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
@@ -1557,10 +1679,34 @@ See also
 and
 .Sx \&Ux .
 .Ss \&Ec
+Close a scope started by
+.Sx \&Eo .
+Its syntax is as follows:
+.Pp
+.D1 Pf \. Sx \&Ec Op Cm TERM
+.Pp
+The
+.Cm TERM
+argument is used as the enclosure tail, for example, specifying \e(rq
+will emulate
+.Sx \&Dc .
 .Ss \&Ed
+End a display context started by
+.Sx \&Bd .
 .Ss \&Ef
+Ends a font mode context started by
+.Sx \&Bf .
 .Ss \&Ek
+Ends a keep context started by
+.Sx \&Bk .
 .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
@@ -1569,8 +1715,25 @@ stylistically decorating technical terms.
 Examples:
 .D1 \&.Em Warnings!
 .D1 \&.Em Remarks :
+.Pp
+See also
+.Sx \&Bf ,
+.Sx \&Sy ,
+and
+.Sx \&Li .
 .Ss \&En
+This macro is obsolete and not implemented.
 .Ss \&Eo
+An arbitrary enclosure.
+Its syntax is as follows:
+.Pp
+.D1 Pf \. Sx \&Eo Op Cm TERM
+.Pp
+The
+.Cm TERM
+argument is used as the enclosure head, for example, specifying \e(lq
+will emulate
+.Sx \&Do .
 .Ss \&Er
 Display error constants.
 .Pp
@@ -1581,6 +1744,7 @@ Examples:
 See also
 .Sx \&Dv .
 .Ss \&Es
+This macro is obsolete and not implemented.
 .Ss \&Ev
 Environmental variables such as those specified in
 .Xr environ 7 .
@@ -1589,19 +1753,63 @@ Examples:
 .D1 \&.Ev DISPLAY
 .D1 \&.Ev PATH
 .Ss \&Ex
-Inserts text regarding a utility's exit values.
-This macro must have first the
+Inserts text regarding a utility's exit value.
+This macro must consist of the
 .Fl std
-argument specified, then an optional
+argument followed by an optional
 .Ar utility .
 If
 .Ar utility
 is not provided, the document's name as stipulated in
 .Sx \&Nm
 is provided.
+.Pp
+See also
+.Sx \&Rv .
 .Ss \&Fa
+Function argument.
+Its syntax is as follows:
+.Bd -ragged -offset indent
+.Pf \. Sx \&Fa
+.Op Cm argtype
+.Cm argname
+.Ed
+.Pp
+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
+within
+.Sx \&Fo
+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
+.Pp
+See also
+.Sx \&Fo .
 .Ss \&Fc
+Ends a function context started by
+.Sx \&Fo .
 .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 MANUAL STRUCTURE
+and
+.Sx \&In .
 .Ss \&Fl
 Command-line flag.
 Used when listing arguments to command-line utilities.
@@ -1621,9 +1829,81 @@ Examples:
 See also
 .Sx \&Cm .
 .Ss \&Fn
+A function name.
+Its syntax is as follows:
+.Bd -ragged -offset indent
+.Pf \. Ns Sx \&Fn
+.Op Cm functype
+.Cm funcname
+.Op Oo Cm argtype Oc Cm argname
+.Ed
+.Pp
+Function arguments are surrounded in parenthesis and
+are delimited by commas.
+If no arguments are specified, blank parenthesis are output.
+.Pp
+Examples:
+.D1 \&.Fn "int funcname" "int arg0" "int arg1"
+.D1 \&.Fn funcname "int arg0"
+.D1 \&.Fn funcname arg0
+.Bd -literal -offset indent -compact
+\&.Ft functype
+\&.Fn funcname
+.Ed
+.Pp
+See also
+.Sx MANUAL STRUCTURE
+and
+.Sx \&Ft .
 .Ss \&Fo
-.Ss \&Fr
+Begin a function block.
+This is a multi-line version of
+.Sx \&Fn .
+Its syntax is as follows:
+.Pp
+.D1 Pf \. Sx \&Fo Cm funcname
+.Pp
+Invocations usually occur in the following context:
+.Bd -ragged -offset indent
+.Pf \. Sx \&Ft Cm functype
+.br
+.Pf \. Sx \&Fo Cm funcname
+.br
+.Pf \. Sx \&Fa Oo Cm argtype Oc Cm argname
+.br
+\.\.\.
+.br
+.Pf \. Sx \&Fc
+.Ed
+.Pp
+A
+.Sx \&Fo
+scope is closed by
+.Pp
+See also
+.Sx MANUAL STRUCTURE ,
+.Sx \&Fa ,
+.Sx \&Fc ,
+and
+.Sx \&Ft .
 .Ss \&Ft
+A function type.
+Its syntax is as follows:
+.Pp
+.D1 Pf \. Sx \&Ft Cm functype
+.Pp
+Examples:
+.D1 \&.Ft int
+.Bd -literal -offset indent -compact
+\&.Ft functype
+\&.Fn funcname
+.Ed
+.Pp
+See also
+.Sx MANUAL STRUCTURE ,
+.Sx \&Fn ,
+and
+.Sx \&Fo .
 .Ss \&Fx
 Format the FreeBSD version provided as an argument, or a default value
 if no argument is provided.
@@ -1642,14 +1922,127 @@ See also
 and
 .Sx \&Ux .
 .Ss \&Hf
+This macro is obsolete and not implemented.
 .Ss \&Ic
+Designate an internal or interactive command.
+This is similar to
+.Sx \&Cm
+but used for instructions rather than values.
+.Pp
+Examples:
+.D1 \&.Ic hash
+.D1 \&.Ic alias
+.Pp
+Note that using
+.Sx \&Bd No Fl literal
+or
+.Sx \&D1
+is preferred for displaying code; the
+.Sx \&Ic
+macro is used when referring to specific instructions.
 .Ss \&In
+An
+.Dq include
+file.
+In the
+.Em SYNOPSIS
+section (only if invoked as the line macro), the first argument is
+preceded by
+.Dq #include ,
+the arguments is enclosed in angled braces.
+.Pp
+Examples:
+.D1 \&.In sys/types
+.Pp
+See also
+.Sx MANUAL STRUCTURE .
 .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 syntax:
+.Pp
+.D1 Pf \. Sx \&It Cm args
+.Pp
+Lists of type
+.Fl bullet ,
+.Fl dash ,
+.Fl enum ,
+.Fl hyphen
+and
+.Fl item
+have the following syntax:
+.Pp
+.D1 Pf \. 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 the following syntax:
+.Pp
+.D1 Pf \. Sx \&It Op Cm args
+.Pp
+Subsequent lines are 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 as follows:
+.Pp
+.D1 Pf \. Sx \&It Op Cm args
+.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
+.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 propagate 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:
+The syntax is as follows:
 .Pp
-.D1 \. Ns Sx \&Lb Cm library
+.D1 Pf \. Sx \&Lb Cm library
 .Pp
 The
 .Cm library
@@ -1669,11 +2062,20 @@ Examples:
 .D1 \&.Lb libz
 .D1 \&.Lb mdoc
 .Ss \&Li
+Denotes text that should be in a literal font mode.
+Note that this is a presentation term and should not be used for
+stylistically decorating technical terms.
+.Pp
+See also
+.Sx \&Bf ,
+.Sx \&Sy ,
+and
+.Sx \&Em .
 .Ss \&Lk
 Format a hyperlink.
-The calling syntax is as follows:
+Its syntax is as follows:
 .Pp
-.D1 \. Ns Sx \&Lk Cm uri Op Cm name
+.D1 Pf \. Sx \&Lk Cm uri Op Cm name
 .Pp
 Examples:
 .D1 \&.Lk http://bsd.lv "The BSD.lv Project"
@@ -1682,12 +2084,104 @@ Examples:
 See also
 .Sx \&Mt .
 .Ss \&Lp
+Synonym for
+.Sx \&Pp .
 .Ss \&Ms
+Display a mathematical symbol.
+.Pp
+Examples:
+.D1 \&.Ms sigma
+.D1 \&.Ms aleph
 .Ss \&Mt
+Format a
+.Dq mailto:
+hyperlink.
+Its syntax is as follows:
+.Pp
+.D1 Pf \. Sx \&Mt Cm address
+.Pp
+Examples:
+.D1 \&.Mt discuss@manpages.bsd.lv
 .Ss \&Nd
+A one-line description of the manual's content.
+This may only be invoked in the
+.Em SYNOPSIS
+section subsequent the
+.Sx \&Nm
+macro.
+.Pp
+Examples:
+.D1 \&.Sx \&Nd mdoc language reference
+.D1 \&.Sx \&Nd format and display UNIX manuals
+.Pp
+The
+.Sx \&Nd
+macro technically accepts child macros and terminates with a subsequent
+.Sx \&Sh
+invocation.
+Do not assume this behaviour: some
+.Xr whatis 1
+database generators are not smart enough to parse more than the line
+arguments and will display macros verbatim.
+.Pp
+See also
+.Sx \&Nm .
 .Ss \&Nm
+The name of the manual page, or \(em in particular in section 1, 6,
+and 8 pages \(em of an additional command or feature documented in
+the manual page.
+When first invoked, the
+.Sx \&Nm
+macro expects a single argument, the name of the manual page.
+Usually, the first invocation happens in the
+.Em NAME
+section of the page.
+The specified name will be remembered and used whenever the macro is
+called again without arguments later in the page.
+The
+.Sx \&Nm
+macro uses
+.Sx Block full-implicit
+semantics when invoked as the first macro on an input line in the
+.Em SYNOPSIS
+section; otherwise, it uses ordinary
+.Sx In-line
+semantics.
+.Pp
+Examples:
+.Bd -literal -offset indent
+\&.Sh SYNOPSIS
+\&.Nm cat
+\&.Op Fl benstuv
+\&.Op Ar
+.Ed
+.Pp
+In the
+.Em SYNOPSIS
+of section 2, 3 and 9 manual pages, use the
+.Sx \&Fn
+macro rather than
+.Sx \&Nm
+to mark up the name of the manual page.
 .Ss \&No
+A
+.Dq noop
+macro used to terminate prior macro contexts.
+.Pp
+Examples:
+.D1 \&.Sx \&Fl ab \&No cd \&Fl ef
 .Ss \&Ns
+Suppress a space.
+Following invocation, text is interpreted as free-form text until a
+macro is encountered.
+.Pp
+Examples:
+.D1 \&.Fl o \&Ns \&Ar output
+.Pp
+See also
+.Sx \&No
+and
+.Sx \&Sm .
 .Ss \&Nx
 Format the NetBSD version provided as an argument, or a default value if
 no argument is provided.
@@ -1706,16 +2200,39 @@ See also
 and
 .Sx \&Ux .
 .Ss \&Oc
+Closes multi-line
+.Sx \&Oo
+context.
 .Ss \&Oo
+Multi-line version of
+.Sx \&Op .
+.Pp
+Examples:
+.Bd -literal -offset indent -compact
+\&.Oo
+\&.Op Fl flag Ns Ar value
+\&.Oc
+.Ed
 .Ss \&Op
+Command-line option.
+Used when listing options to command-line utilities.
+Prints the argument(s) in brackets.
+.Pp
+Examples:
+.D1 \&.Op \&Fl a \&Ar b
+.D1 \&.Op \&Ar a | b
+.Pp
+See also
+.Sx \&Oo .
 .Ss \&Os
 Document operating system version.
 This is the mandatory third macro of
 any
 .Nm
-file.  Its calling syntax is as follows:
+file.
+Its syntax is as follows:
 .Pp
-.D1 \. Ns Sx \&Os Op Cm system
+.D1 Pf \. Sx \&Os Op Cm system
 .Pp
 The optional
 .Cm system
@@ -1755,15 +2272,67 @@ See also
 and
 .Sx \&Ux .
 .Ss \&Pa
+A file-system path.
+.Pp
+Examples:
+.D1 \&.Pa /usr/bin/mandoc
+.D1 \&.Pa /usr/share/man/man7/mdoc.7
+.Pp
+See also
+.Sx \&Lk .
 .Ss \&Pc
+Close parenthesised context opened by
+.Sx \&Po .
 .Ss \&Pf
+Removes the space
+.Pq Dq prefix
+between its arguments.
+Its syntax is as follows:
+.Pp
+.D1 Pf \. \&Pf Cm prefix suffix
+.Pp
+The
+.Cm suffix
+argument may be a macro.
+.Pp
+Examples:
+.D1 \&.Pf \e. \&Sx \&Pf \&Cm prefix suffix
 .Ss \&Po
+Multi-line version of
+.Sx \&Pq .
 .Ss \&Pp
+Break a paragraph.
+This will assert vertical space between prior and subsequent macros
+and/or text.
 .Ss \&Pq
+Parenthesised enclosure.
+.Pp
+See also
+.Sx \&Po .
 .Ss \&Qc
+Close quoted context opened by
+.Sx \&Qo .
 .Ss \&Ql
+Format a single-quoted literal.
+See also
+.Sx \&Qq
+and
+.Sx \&Sq .
 .Ss \&Qo
+Multi-line version of
+.Sx \&Qq .
 .Ss \&Qq
+Encloses its arguments in
+.Dq typewriter
+double-quotes.
+Consider using
+.Sx \&Dq .
+.Pp
+See also
+.Sx \&Dq ,
+.Sx \&Sq ,
+and
+.Sx \&Qo .
 .Ss \&Re
 Closes a
 .Sx \&Rs
@@ -1787,6 +2356,7 @@ The block macro may only contain
 .Sx \&%Q ,
 .Sx \&%R ,
 .Sx \&%T ,
+.Sx \&%U ,
 and
 .Sx \&%V
 child macros (at least one must be specified).
@@ -1809,17 +2379,203 @@ 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 .
+If
+.Ar function
+is not provided, the document's name as stipulated by the first
+.Sx \&Nm
+is provided.
+.Pp
+See also
+.Sx \&Ex .
 .Ss \&Sc
+Close single-quoted context opened by
+.Sx \&So .
 .Ss \&Sh
+Begin a new section.
+For a list of conventional manual sections, see
+.Sx MANUAL STRUCTURE .
+These sections should be used unless it's absolutely necessary that
+custom sections be used.
+.Pp
+Section names should be unique so that they may be keyed by
+.Sx \&Sx .
+.Pp
+See also
+.Sx \&Pp ,
+.Sx \&Ss ,
+and
+.Sx \&Sx .
 .Ss \&Sm
+Switches the spacing mode for output generated from macros.
+Its syntax is as follows:
+.Pp
+.D1 Pf \. Sx \&Sm Cm on | off
+.Pp
+By default, spacing is
+.Cm on .
+When switched
+.Cm off ,
+no white space is inserted between macro arguments and between the
+output generated from adjacent macros, but free-form text lines
+still get normal spacing between words and sentences.
 .Ss \&So
+Multi-line version of
+.Sx \&Sq .
 .Ss \&Sq
+Encloses its arguments in
+.Dq typewriter
+single-quotes.
+.Pp
+See also
+.Sx \&Dq ,
+.Sx \&Qq ,
+and
+.Sx \&So .
 .Ss \&Ss
+Begin a new sub-section.
+Unlike with
+.Sx \&Sh ,
+there's no convention for sub-sections.
+Conventional sections, as described in
+.Sx MANUAL STRUCTURE ,
+rarely have sub-sections.
+.Pp
+Sub-section names should be unique so that they may be keyed by
+.Sx \&Sx .
+.Pp
+See also
+.Sx \&Pp ,
+.Sx \&Sh ,
+and
+.Sx \&Sx .
 .Ss \&St
+Replace an abbreviation for a standard with the full form.
+The following standards are recognised:
+.Pp
+.Bl -tag -width "-p1003.1g-2000X" -compact
+.It \-p1003.1-88
+.St -p1003.1-88
+.It \-p1003.1-90
+.St -p1003.1-90
+.It \-p1003.1-96
+.St -p1003.1-96
+.It \-p1003.1-2001
+.St -p1003.1-2001
+.It \-p1003.1-2004
+.St -p1003.1-2004
+.It \-p1003.1-2008
+.St -p1003.1-2008
+.It \-p1003.1
+.St -p1003.1
+.It \-p1003.1b
+.St -p1003.1b
+.It \-p1003.1b-93
+.St -p1003.1b-93
+.It \-p1003.1c-95
+.St -p1003.1c-95
+.It \-p1003.1g-2000
+.St -p1003.1g-2000
+.It \-p1003.1i-95
+.St -p1003.1i-95
+.It \-p1003.2-92
+.St -p1003.2-92
+.It \-p1003.2a-92
+.St -p1003.2a-92
+.It \-p1387.2-95
+.St -p1387.2-95
+.It \-p1003.2
+.St -p1003.2
+.It \-p1387.2
+.St -p1387.2
+.It \-isoC
+.St -isoC
+.It \-isoC-90
+.St -isoC-90
+.It \-isoC-amd1
+.St -isoC-amd1
+.It \-isoC-tcor1
+.St -isoC-tcor1
+.It \-isoC-tcor2
+.St -isoC-tcor2
+.It \-isoC-99
+.St -isoC-99
+.It \-iso9945-1-90
+.St -iso9945-1-90
+.It \-iso9945-1-96
+.St -iso9945-1-96
+.It \-iso9945-2-93
+.St -iso9945-2-93
+.It \-ansiC
+.St -ansiC
+.It \-ansiC-89
+.St -ansiC-89
+.It \-ansiC-99
+.St -ansiC-99
+.It \-ieee754
+.St -ieee754
+.It \-iso8802-3
+.St -iso8802-3
+.It \-ieee1275-94
+.St -ieee1275-94
+.It \-xpg3
+.St -xpg3
+.It \-xpg4
+.St -xpg4
+.It \-xpg4.2
+.St -xpg4.2
+.St -xpg4.3
+.It \-xbd5
+.St -xbd5
+.It \-xcu5
+.St -xcu5
+.It \-xsh5
+.St -xsh5
+.It \-xns5
+.St -xns5
+.It \-xns5.2
+.St -xns5.2
+.It \-xns5.2d2.0
+.St -xns5.2d2.0
+.It \-xcurses4.2
+.St -xcurses4.2
+.It \-susv2
+.St -susv2
+.It \-susv3
+.St -susv3
+.It \-svid4
+.St -svid4
+.El
 .Ss \&Sx
+Reference a section or sub-section.
+The referenced section or sub-section name must be identical to the
+enclosed argument, including whitespace.
+.Pp
+Examples:
+.D1 \&.Sx MANUAL STRUCTURE
 .Ss \&Sy
+Format enclosed arguments in symbolic
+.Pq Dq boldface .
+Note that this is a presentation term and should not be used for
+stylistically decorating technical terms.
+.Pp
+See also
+.Sx \&Bf ,
+.Sx \&Li ,
+and
+.Sx \&Em .
 .Ss \&Tn
+Format a tradename.
+.Pp
+Examples:
+.D1 \&.Tn IBM
 .Ss \&Ud
+Prints out
+.Dq currently under development.
 .Ss \&Ux
 Format the UNIX name.
 Accepts no argument.
@@ -1837,14 +2593,21 @@ See also
 and
 .Sx \&Ox .
 .Ss \&Va
+A variable name.
+.Pp
+Examples:
+.D1 \&.Va foo
+.D1 \&.Va const char *bar ;
 .Ss \&Vt
 A variable type.
-This is also used for indicating global variables in the SYNOPSIS
+This is also used for indicating global variables in the
+.Em 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
+syntax when invoked as the first macro in the
+.Em SYNOPSIS
+section, else it accepts ordinary
 .Sx In-line
 syntax.
 .Pp
@@ -1854,10 +2617,10 @@ which is used for function return types.
 .Pp
 Examples:
 .D1 \&.Vt unsigned char
-.D1 \&.Vt extern const char * const sys_signame[] ;
+.D1 \&.Vt extern const char * const sys_signame[] \&;
 .Pp
 See also
-.Sx \&Ft
+.Sx MANUAL STRUCTURE
 and
 .Sx \&Va .
 .Ss \&Xc
@@ -1870,9 +2633,9 @@ since this limit has been lifted, the macro has been d
 .Ss \&Xr
 Link to another manual
 .Pq Qq cross-reference .
-Its calling syntax is
+Its syntax is as follows:
 .Pp
-.D1 \. Ns Sx \&Xr Cm name section
+.D1 Pf \. Sx \&Xr Cm name section
 .Pp
 The
 .Cm name
@@ -1889,7 +2652,7 @@ This behaviour is for compatibility with
 .Pp
 Examples:
 .D1 \&.Xr mandoc 1
-.D1 \&.Xr mandoc 1 ;
+.D1 \&.Xr mandoc 1 \&;
 .D1 \&.Xr mandoc 1 \&Ns s behaviour
 .Ss \&br
 .Ss \&sp
@@ -1909,8 +2672,57 @@ Heirloom troff, the other significant troff implementa
 .Pp
 .Bl -dash -compact
 .It
+The \es (font size), \em (font colour), and \eM (font filling colour)
+font decoration escapes are all discarded in mandoc.
+.It
+Old groff fails to assert a newline before
+.Sx \&Bd Fl ragged compact .
+.It
+groff behaves inconsistently when encountering
+.Pf non- Sx \&Fa
+children of
+.Sx \&Fo
+regarding spacing between arguments.
+In mandoc, this is not the case: each argument is consistently followed
+by a single space and the trailing
+.Sq \&)
+suppresses prior spacing.
+.It
+groff behaves inconsistently when encountering
+.Sx \&Ft
+and
+.Sx \&Fn
+in the
+.Em SYNOPSIS :
+at times newline(s) are suppressed depending on whether a prior
+.Sx \&Fn
+has been invoked.
+In mandoc, this is not the case.
+See
+.Sx \&Ft
+and
+.Sx \&Fn
+for the normalised behaviour.
+.It
+Historic groff does not break before an
+.Sx \&Fn
+when not invoked as the line macro in the
+.Em SYNOPSIS
+section.
+.It
+Historic groff formats the
+.Sx \&In
+badly: trailing arguments are trashed and
+.Em SYNOPSIS
+is not specially treated.
+.It
+groff does not accept the
+.Sq \&Ta
+pseudo-macro as a line macro.
+mandoc does.
+.It
 The comment syntax
-.Sq \e."
+.Sq \e\."
 is no longer accepted.
 .It
 In groff, the
@@ -1940,16 +2752,15 @@ In quoted literals, groff allowed pair-wise double-quo
 standalone double-quote in formatted output.
 This idiosyncratic behaviour is not applicable in mandoc.
 .It
-Display types
+Display offsets
 .Sx \&Bd
-.Fl center
+.Fl offset Ar center
 and
-.Fl right
-are aliases for
-.Fl left
-in manodc.  Furthermore, the
+.Fl offset Ar right
+are disregarded in mandoc.
+Furthermore, troff specifies a
 .Fl file Ar file
-argument is ignored.
+argument that is not supported in mandoc.
 Lastly, since text is not right-justified in mandoc (or even groff),
 .Fl ragged
 and
@@ -1981,11 +2792,6 @@ delimiter to render.
 This is not supported in mandoc.
 .It
 In groff, the
-.Sx \&Fo
-macro only produces the first parameter.
-This is not the case in mandoc.
-.It
-In groff, the
 .Sx \&Cd ,
 .Sx \&Er ,
 .Sx \&Ex ,
@@ -2008,71 +2814,3 @@ The
 .Nm
 reference was written by
 .An Kristaps Dzonsons Aq kristaps@bsd.lv .
-.\"
-.\" XXX: this really isn't the place for these caveats.
-.\" .
-.\" .
-.\" .Sh CAVEATS
-.\" There are many ambiguous parts of mdoc.
-.\" .
-.\" .Pp
-.\" .Bl -dash -compact
-.\" .It
-.\" .Sq \&Fa
-.\" should be
-.\" .Sq \&Va
-.\" as function arguments are variables.
-.\" .It
-.\" .Sq \&Ft
-.\" should be
-.\" .Sq \&Vt
-.\" as function return types are still types.  Furthermore, the
-.\" .Sq \&Ft
-.\" should be removed and
-.\" .Sq \&Fo ,
-.\" which ostensibly follows it, should follow the same convention as
-.\" .Sq \&Va .
-.\" .It
-.\" .Sq \&Va
-.\" should formalise that only one or two arguments are acceptable: a
-.\" variable name and optional, preceding type.
-.\" .It
-.\" .Sq \&Fd
-.\" is ambiguous.  It's commonly used to indicate an include file in the
-.\" synopsis section.
-.\" .Sq \&In
-.\" should be used, instead.
-.\" .It
-.\" Only the
-.\" .Sq \-literal
-.\" argument to
-.\" .Sq \&Bd
-.\" makes sense.  The remaining ones should be removed.
-.\" .It
-.\" The
-.\" .Sq \&Xo
-.\" and
-.\" .Sq \&Xc
-.\" macros should be deprecated.
-.\" .It
-.\" The
-.\" .Sq \&Dt
-.\" macro lacks clarity.  It should be absolutely clear which title will
-.\" render when formatting the manual page.
-.\" .It
-.\" A
-.\" .Sq \&Lx
-.\" should be provided for Linux (\(`a la
-.\" .Sq \&Ox ,
-.\" .Sq \&Nx
-.\" etc.).
-.\" .It
-.\" There's no way to refer to references in
-.\" .Sq \&Rs/Re
-.\" blocks.
-.\" .It
-.\" The \-split and \-nosplit dictates via
-.\" .Sq \&An
-.\" are re-set when entering and leaving the AUTHORS section.
-.\" .El
-.\" .