===================================================================
RCS file: /cvs/mandoc/mdoc.7,v
retrieving revision 1.71
retrieving revision 1.93
diff -u -p -r1.71 -r1.93
--- mandoc/mdoc.7	2009/10/31 06:50:25	1.71
+++ mandoc/mdoc.7	2010/04/07 19:37:54	1.93
@@ -1,4 +1,4 @@
-.\"	$Id: mdoc.7,v 1.71 2009/10/31 06:50:25 kristaps Exp $
+.\"	$Id: mdoc.7,v 1.93 2010/04/07 19:37:54 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: October 31 2009 $
+.Dd $Mdocdate: April 7 2010 $
 .Dt MDOC 7
 .Os
 .
@@ -31,12 +31,9 @@ language is used to format
 .Bx
 .Ux
 manuals.  In this reference document, we describe its syntax, structure,
-and usage.  Our reference implementation is
-.Xr mandoc 1 .
-The
+and usage.  Our reference implementation is mandoc; the
 .Sx COMPATIBILITY
-section describes compatibility with
-.Xr groff 1 .
+section describes compatibility with other troff \-mdoc implementations.
 .
 .Pp
 An
@@ -131,18 +128,58 @@ and
 .Ss Text Decoration
 Terms may be text-decorated using the
 .Sq \ef
-escape followed by an indicator: B (bold), I, (italic), or P and R
-(Roman, or reset).  This form is not recommended for 
+escape followed by an indicator: B (bold), I, (italic), R (Roman), or P
+(revert to previous mode):
+.Pp
+.D1 \efBbold\efR \efIitalic\efP
+.Pp
+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
+its own scope, such as
+.Sx \&Bf
+.Cm \&Sy ,
+in-scope invocations of
+.Sq \ef
+are only valid within the font scope of the macro.  If
+.Sq \ef
+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
+.Em not
+recommended for
 .Nm ,
-which encourages semantic, not presentation, annotation.
+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,
@@ -212,9 +249,8 @@ In free-form mode, quotes are regarded as opaque text.
 .Ss Dates
 There are several macros in
 .Nm
-that require a date argument.  The 
-.Em canonical form
-for dates is the American format:
+that require a date argument.  The canonical form for dates is the
+American format:
 .Pp
 .D1 Cm Month Day , Year
 .Pp
@@ -226,26 +262,16 @@ value is the full month name.  The
 .Cm Year
 value is the full four-digit year.
 .Pp
-The
-.Em non-canonical form
-is the same as the canonical form, but without the comma between the
-.Cm Day
-and
-.Cm Year
-field.
+Reduced form dates are broken-down canonical form dates:
 .Pp
-Lastly,
-.Em reduced form
-dates range from only a
-.Cm Year
-to the full canonical or non-canonical form.
+.D1 Cm Month , Year
+.D1 Cm Year
 .Pp
 Some examples of valid dates follow:
 .Pp
 .D1 "May, 2009" Pq reduced form
 .D1 "2009" Pq reduced form
 .D1 "May 20, 2009" Pq canonical form
-.D1 "May 20 2009" Pq non-canonical form
 .
 .Ss Scaling Widths
 Many macros support scaled widths for their arguments, such as
@@ -314,7 +340,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
@@ -374,38 +400,199 @@ The sections in a
 .Nm
 document are conventionally ordered as they appear above.  Sections
 should be composed as follows:
-.Bl -tag -width Ds -offset Ds
-.It NAME
-Must contain at least one
+.Bl -ohang -offset Ds
+.It Em NAME
+The name(s) and a short description of the documented material.  The
+syntax for this as follows:
+.Bd -literal -offset indent
+\&.Nm name0
+\&.Nm name1
+\&.Nm name2
+\&.Nd a short description
+.Ed
+.Pp
+The
 .Sx \&Nm
-followed by
+macro(s) must precede the
+.Sx \&Nd
+macro.
+.Pp
+See
+.Sx \&Nm
+and
 .Sx \&Nd .
-The name needs re-stating since one
-.Nm
-documents can be used for more than one utility or function, such as
-.Xr grep 1
-also being referenced as
-.Xr egrep 1
+.
+.It Em LIBRARY
+The name of the library containing the documented material, which is
+assumed to be a function in a section 2 or 3 manual.  The syntax for
+this is as follows:
+.Bd -literal -offset indent
+\&.Lb libarm
+.Ed
+.Pp
+See
+.Sx \&Lb .
+.
+.It Em SYNOPSIS
+Documents the utility invocation syntax, function call syntax, or device
+configuration.
+.Pp
+For the first, utilities (sections 1, 6, and 8), this is
+generally structured as follows:
+.Bd -literal -offset indent
+\&.Nm foo
+\&.Op Fl v
+\&.Op Fl o Ar file
+\&.Op Ar
+\&.Nm bar
+\&.Op Fl v
+\&.Op Fl o Ar file
+\&.Op Ar
+.Ed
+.Pp
+For the second, function calls (sections 2, 3, 9):
+.Bd -literal -offset indent
+\&.Vt extern const char *global;
+\&.In header.h
+\&.Ft "char *"
+\&.Fn foo "const char *src"
+\&.Ft "char *"
+\&.Fn bar "const char *src"
+.Ed
+.Pp
+And for the third, configurations (section 4):
+.Bd -literal -offset indent
+\&.Cd \*qit* at isa? port 0x2e\*q
+\&.Cd \*qit* at isa? port 0x4e\*q
+.Ed
+.Pp
+Manuals not in these sections generally don't need a
+.Em SYNOPSIS .
+.Pp
+See
+.Sx \&Op ,
+.Sx \&Cd ,
+.Sx \&Fn ,
+.Sx \&Ft ,
 and
-.Xr fgrep 1 .
-.It LIBRARY
-.It SYNOPSIS
-.It DESCRIPTION
-.It IMPLEMENTATION NOTES
-.It EXIT STATUS
-.It RETURN VALUES
-.It ENVIRONMENT
-.It FILES
-.It EXAMPLES
-.It DIAGNOSTICS
-.It ERRORS
-.It SEE ALSO
-.It STANDARDS
-.It HISTORY
-.It AUTHORS
-.It CAVEATS
-.It BUGS
-.It SECURITY CONSIDERATIONS
+.Sx \&Vt .
+.
+.It Em DESCRIPTION
+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:
+.Bd -literal -offset indent
+The arguments are as follows:
+\&.Bl \-tag \-width Ds
+\&.It Fl v
+Print verbose information.
+\&.El
+.Ed
+.Pp
+Manuals not documenting a command won't include the above fragment.
+.
+.It Em IMPLEMENTATION NOTES
+Implementation-specific notes should be kept here.  This is useful when
+implementing standard functions that may have side effects or notable
+algorithmic implications.
+.
+.It Em EXIT STATUS
+Command exit status for section 1, 6, and 8 manuals.  This section is
+the dual of
+.Em RETURN VALUES ,
+which is used for functions.  Historically, this information was
+described in
+.Em DIAGNOSTICS ,
+a practise that is now discouraged.
+.Pp
+See
+.Sx \&Ex .
+.
+.It Em RETURN VALUES
+This section is the dual of
+.Em EXIT STATUS ,
+which is used for commands.  It documents the return values of functions
+in sections 2, 3, and 9.
+.Pp
+See
+.Sx \&Rv .
+.
+.It Em ENVIRONMENT
+Documents any usages of environment variables, e.g.,
+.Xr environ 7 .
+.Pp
+See
+.Sx \&Ev .
+.
+.It Em FILES
+Documents files used.  It's helpful to document both the file and a
+short description of how the file is used (created, modified, etc.).
+.Pp
+See
+.Sx \&Pa .
+.
+.It Em EXAMPLES
+Example usages.  This often contains snippets of well-formed,
+well-tested invocations.  Make doubly sure that your examples work
+properly!
+.
+.It Em DIAGNOSTICS
+Documents error conditions.  This is most useful in section 4 manuals.
+Historically, this section was used in place of
+.Em EXIT STATUS
+for manuals in sections 1, 6, and 8; however, this practise is
+discouraged.
+.Pp
+See
+.Sx \&Bl
+.Fl diag .
+.
+.It Em ERRORS
+Documents error handling in sections 2, 3, and 9.
+.Pp
+See
+.Sx \&Er .
+.
+.It Em SEE ALSO
+References other manuals with related topics.  This section should exist
+for most manuals.  Cross-references should conventionally be ordered
+first by section, then alphabetically.
+.Pp
+See
+.Sx \&Xr .
+.
+.It Em STANDARDS
+References any standards implemented or used.  If not adhering to any
+standards, the
+.Em HISTORY
+section should be used instead.
+.Pp
+See
+.Sx \&St .
+.
+.It Em HISTORY
+The history of any manual without a
+.Em STANDARDS
+section should be described in this section.
+.
+.It Em AUTHORS
+Credits to authors, if applicable, should appear in this section.
+Authors should generally be noted by both name and an e-mail address.
+.Pp
+See
+.Sx \&An .
+.
+.It Em CAVEATS
+Explanations of common misuses and misunderstandings should be explained
+in this section.
+.
+.It Em BUGS
+Extant bugs should be described in this section.
+.
+.It Em SECURITY CONSIDERATIONS
+Documents any security precautions that operators should consider.
+.
 .El
 .
 .
@@ -493,7 +680,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
@@ -580,7 +767,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
@@ -661,7 +857,7 @@ then the macro accepts an arbitrary number of argument
 .It Sx \&Ot  Ta    \&No     Ta    \&No     Ta    n
 .It Sx \&Ox  Ta    Yes      Ta    Yes      Ta    n
 .It Sx \&Pa  Ta    Yes      Ta    Yes      Ta    n
-.It Sx \&Pf  Ta    \&No     Ta    Yes      Ta    1
+.It Sx \&Pf  Ta    Yes      Ta    Yes      Ta    1
 .It Sx \&Pp  Ta    \&No     Ta    \&No     Ta    0
 .It Sx \&Rv  Ta    \&No     Ta    \&No     Ta    n
 .It Sx \&Sm  Ta    \&No     Ta    \&No     Ta    1
@@ -673,10 +869,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
@@ -710,10 +906,9 @@ this macro is not implemented in
 .Ss \&%D
 Publication date of an
 .Sx \&Rs
-block.  This should follow the reduced syntax for 
+block.  This should follow the reduced or canonical form syntax
+described in
 .Sx Dates .
-Canonical or non-canonical form is not necessary since publications are
-often referenced only by year, or month and year.
 .
 .Ss \&%I
 Publisher or issuer name of an
@@ -776,10 +971,8 @@ Address construct: usually in the context of an comput
 memory, not a physical (post) address.
 .Pp
 Examples:
-.Bd -literal -offset indent
-\&.Ad [0,$]
-\&.Ad 0x00000000
-.Ed
+.D1 \&.Ad [0,$]
+.D1 \&.Ad 0x00000000
 .
 .Ss \&An
 Author name.  This macro may alternatively accepts the following
@@ -800,11 +993,8 @@ will cause the first listing also to be split.  If not
 section, the default is not to split.
 .Pp
 Examples:
-.Bd -literal -offset indent
-\&.An -nosplit
-\&.An J. E. Hopcraft ,
-\&.An J. D. Ullman .
-.Ed
+.D1 \&.An -nosplit
+.D1 \&.An J. D. Ullman .
 .Pp
 .Em Remarks :
 the effects of
@@ -821,9 +1011,7 @@ Begins a block enclosed by angled brackets.  Does not 
 arguments.
 .Pp
 Examples:
-.Bd -literal -offset indent
-\&.Fl -key= Ns Ao Ar val Ac
-.Ed
+.D1 \&.Fl -key= \&Ns \&Ao \&Ar val \&Ac
 .Pp
 See also
 .Sx \&Aq .
@@ -837,12 +1025,10 @@ a function:
 .Ed
 .
 .Ss \&Aq
-Encloses its arguments in angled brackets.  
+Encloses its arguments in angled brackets.
 .Pp
 Examples:
-.Bd -literal -offset indent
-\&.Fl -key= Ns Aq Ar val
-.Ed
+.D1 \&.Fl -key= \&Ns \&Aq \&Ar val
 .Pp
 .Em Remarks :
 this macro is often abused for rendering URIs, which should instead use
@@ -863,11 +1049,9 @@ Command arguments.  If an argument is not provided, th
 is used as a default.
 .Pp
 Examples:
-.Bd -literal -offset indent
-\&.Fl o Ns Ar file1
-\&.Ar
-\&.Ar arg1 , arg2 .
-.Ed
+.D1 \&.Fl o \&Ns \&Ar file1
+.D1 \&.Ar
+.D1 \&.Ar arg1 , arg2 .
 .
 .Ss \&At
 Formats an AT&T version.  Accepts at most one parameter:
@@ -883,10 +1067,8 @@ A system version of
 Note that these parameters do not begin with a hyphen.
 .Pp
 Examples:
-.Bd -literal -offset indent
-\&.At 
-\&.At V.1
-.Ed
+.D1 \&.At
+.D1 \&.At V.1
 .Pp
 See also
 .Sx \&Bsx ,
@@ -985,7 +1167,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.
@@ -993,19 +1228,17 @@ arguments.
 Examples:
 .Bd -literal -offset indent
 \&.Bo 1 ,
-\&.Dv BUFSIZ Bc
+\&.Dv BUFSIZ \&Bc
 .Ed
 .Pp
 See also
 .Sx \&Bq .
 .
 .Ss \&Bq
-Encloses its arguments in square brackets.  
+Encloses its arguments in square brackets.
 .Pp
 Examples:
-.Bd -literal -offset indent
-\&.Bq 1 , Dv BUFSIZ
-.Ed
+.D1 \&.Bq 1 , \&Dv BUFSIZ
 .Pp
 .Em Remarks :
 this macro is sometimes abused to emulate optional arguments for
@@ -1030,7 +1263,7 @@ arguments.
 Examples:
 .Bd -literal -offset indent
 \&.Bro 1 , ... ,
-\&.Va n Brc
+\&.Va n \&Brc
 .Ed
 .Pp
 See also
@@ -1040,9 +1273,7 @@ See also
 Encloses its arguments in curly braces.
 .Pp
 Examples:
-.Bd -literal -offset indent
-\&.Brq 1 , ... , Va n
-.Ed
+.D1 \&.Brq 1 , ... , \&Va n
 .Pp
 See also
 .Sx \&Bro .
@@ -1052,10 +1283,8 @@ Format the BSD/OS version provided as an argument, or 
 no argument is provided.
 .Pp
 Examples:
-.Bd -literal -offset indent
-\&.Bsx 1.0
-\&.Bsx
-.Ed
+.D1 \&.Bsx 1.0
+.D1 \&.Bsx
 .Pp
 See also
 .Sx \&At ,
@@ -1076,10 +1305,8 @@ Format the BSD version provided as an argument, or a d
 argument is provided.
 .Pp
 Examples:
-.Bd -literal -offset indent
-\&.Bx 4.4
-\&.Bx
-.Ed
+.D1 \&.Bx 4.4
+.D1 \&.Bx
 .Pp
 See also
 .Sx \&At ,
@@ -1092,14 +1319,11 @@ and
 .Sx \&Ux .
 .
 .Ss \&Cd
-Configuration declaration (suggested for use only in section four
-manuals).  This denotes strings accepted by
+Configuration declaration.  This denotes strings accepted by
 .Xr config 8 .
 .Pp
 Examples:
-.Bd -literal -offset indent
-\&.Cd device le0 at scode?
-.Ed
+.D1 \&.Cd device le0 at scode?
 .Pp
 .Em Remarks :
 this macro is commonly abused by using quoted literals to retain
@@ -1112,10 +1336,8 @@ Command modifiers.  Useful when specifying configurati
 keys.
 .Pp
 Examples:
-.Bd -literal -offset indent
-\&.Cm ControlPath
-\&.Cm ControlMaster
-.Ed
+.D1 \&.Cm ControlPath
+.D1 \&.Cm ControlMaster
 .Pp
 See also
 .Sx \&Fl .
@@ -1125,9 +1347,7 @@ One-line indented display.  This is formatted by the d
 is useful for simple indented statements.  It is followed by a newline.
 .Pp
 Examples:
-.Bd -literal -offset indent
-\&.D1 Fl abcdefgh
-.Ed
+.D1 \&.D1 \&Fl abcdefgh
 .Pp
 See also
 .Sx \&Bd
@@ -1147,21 +1367,20 @@ 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$ ,
 which signifies the current manual revision date dictated by
-.Xr cvs 1
+.Xr cvs 1 ,
 or instead a valid canonical date as specified by
 .Sx Dates .
+If a date does not conform, the current date is used instead.
 .Pp
 Examples:
-.Bd -literal -offset indent
-\&.Dd $\&Mdocdate$
-\&.Dd $\&Mdocdate: July 21 2007$
-\&.Dd July 21, 2007
-.Ed
+.D1 \&.Dd $\&Mdocdate$
+.D1 \&.Dd $\&Mdocdate: July 21 2007$
+.D1 \&.Dd July 21, 2007
 .Pp
 See also
 .Sx \&Dt
@@ -1173,9 +1392,7 @@ One-line intended display.  This is formatted as liter
 useful for commands and invocations.  It is followed by a newline.
 .Pp
 Examples:
-.Bd -literal -offset indent
-\&.Dl % mandoc mdoc.7 | less
-.Ed
+.D1 \&.Dl % mandoc mdoc.7 | less
 .Pp
 See also
 .Sx \&Bd
@@ -1187,18 +1404,16 @@ Begins a block enclosed by double quotes.  Does not ha
 arguments.
 .Pp
 Examples:
-.Bd -literal -offset indent
-\&.D1 Do April is the cruellest month Dc \e(em T.S. Eliot
-.Ed
+.D1 \&.D1 \&Do April is the cruellest month \&Dc \e(em T.S. Eliot
 .Pp
 See also
 .Sx \&Dq .
 .
 .Ss \&Dq
-Encloses its arguments in double quotes.  
+Encloses its arguments in double quotes.
 .Pp
 Examples:
-.Bd -literal -offset indent
+.Bd -literal -offset indent -compact
 \&.Dq April is the cruellest month
 \e(em T.S. Eliot
 .Ed
@@ -1301,6 +1516,7 @@ subsequent that.  It, too, is optional.  It must be on
 .Ar hppa64 ,
 .Ar i386 ,
 .Ar landisk ,
+.Ar loongson ,
 .Ar luna88k ,
 .Ar mac68k ,
 .Ar macppc ,
@@ -1319,12 +1535,10 @@ or
 .El
 .Pp
 Examples:
-.Bd -literal -offset indent
-\&.Dt FOO 1
-\&.Dt FOO 4 KM
-\&.Dt FOO 9 i386
-\&.Dt FOO 9 KM i386
-.Ed
+.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
@@ -1335,10 +1549,8 @@ and
 Defined variables such as preprocessor constants.
 .Pp
 Examples:
-.Bd -literal -offset indent
-\&.Dv BUFSIZ
-\&.Dv STDOUT_FILENO
-.Ed
+.D1 \&.Dv BUFSIZ
+.D1 \&.Dv STDOUT_FILENO
 .Pp
 See also
 .Sx \&Er .
@@ -1348,10 +1560,8 @@ Format the DragonFly BSD version provided as an argume
 value if no argument is provided.
 .Pp
 Examples:
-.Bd -literal -offset indent
-\&.Dx 2.4.1
-\&.Dx
-.Ed
+.D1 \&.Dx 2.4.1
+.D1 \&.Dx
 .Pp
 See also
 .Sx \&At ,
@@ -1368,27 +1578,24 @@ and
 .Ss \&Ef
 .Ss \&Ek
 .Ss \&El
+.
 .Ss \&Em
 Denotes text that should be emphasised.  Note that this is a
 presentation term and should not be used for stylistically decorating
 technical terms.
 .Pp
 Examples:
-.Bd -literal -offset indent
-\&.Ed Warnings!
-\&.Ed Remarks :
-.Ed
+.D1 \&.Em Warnings!
+.D1 \&.Em Remarks :
 .
 .Ss \&En
 .Ss \&Eo
 .Ss \&Er
-Error constants (suggested for use only in section two manuals).
+Display error constants.
 .Pp
 Examples:
-.Bd -literal -offset indent
-\&.Er EPERM
-\&.Er ENOENT
-.Ed
+.D1 \&.Er EPERM
+.D1 \&.Er ENOENT
 .Pp
 See also
 .Sx \&Dv .
@@ -1400,10 +1607,8 @@ Environmental variables such as those specified in
 .Xr environ 7 .
 .Pp
 Examples:
-.Bd -literal -offset indent
-\&.Ev DISPLAY
-\&.Ev PATH
-.Ed
+.D1 \&.Ev DISPLAY
+.D1 \&.Ev PATH
 .
 .Ss \&Ex
 Inserts text regarding a utility's exit values.  This macro must have
@@ -1420,6 +1625,22 @@ is provided.
 .Ss \&Fc
 .Ss \&Fd
 .Ss \&Fl
+Command-line flag.  Used when listing arguments to command-line
+utilities.  Prints a fixed-width hyphen
+.Sq \-
+directly followed by each argument.  If no arguments are provided, a hyphen is
+printed followed by a space.  If the argument is a macro, a hyphen is
+prefixed to the subsequent macro output.
+.Pp
+Examples:
+.D1 \&.Fl a b c
+.D1 \&.Fl \&Pf a b
+.D1 \&.Fl
+.D1 \&.Op \&Fl o \&Ns \&Ar file
+.Pp
+See also
+.Sx \&Cm .
+.
 .Ss \&Fn
 .Ss \&Fo
 .Ss \&Fr
@@ -1429,10 +1650,8 @@ Format the FreeBSD version provided as an argument, or
 if no argument is provided.
 .Pp
 Examples:
-.Bd -literal -offset indent
-\&.Fx 7.1
-\&.Fx
-.Ed
+.D1 \&.Fx 7.1
+.D1 \&.Fx
 .Pp
 See also
 .Sx \&At ,
@@ -1456,10 +1675,8 @@ Format a hyperlink.  The calling syntax is as follows:
 .D1 \. Ns Sx \&Lk Cm uri Op Cm name
 .Pp
 Examples:
-.Bd -literal -offset indent
-\&.Lk http://bsd.lv "The BSD.lv Project"
-\&.Lk http://bsd.lv
-.Ed
+.D1 \&.Lk http://bsd.lv "The BSD.lv Project"
+.D1 \&.Lk http://bsd.lv
 .Pp
 See also
 .Sx \&Mt .
@@ -1476,10 +1693,8 @@ Format the NetBSD version provided as an argument, or 
 no argument is provided.
 .Pp
 Examples:
-.Bd -literal -offset indent
-\&.Nx 5.01
-\&.Nx
-.Ed
+.D1 \&.Nx 5.01
+.D1 \&.Nx
 .Pp
 See also
 .Sx \&At ,
@@ -1509,11 +1724,9 @@ unspecified, it defaults to the local operating system
 the suggested form.
 .Pp
 Examples:
-.Bd -literal -offset indent
-\&.Os
-\&.Os KTH/CSC/TCS
-\&.Os BSD 4.3
-.Ed
+.D1 \&.Os
+.D1 \&.Os KTH/CSC/TCS
+.D1 \&.Os BSD 4.3
 .Pp
 See also
 .Sx \&Dd
@@ -1531,10 +1744,8 @@ Format the OpenBSD version provided as an argument, or
 if no argument is provided.
 .Pp
 Examples:
-.Bd -literal -offset indent
-\&.Ox 4.5
-\&.Ox
-.Ed
+.D1 \&.Ox 4.5
+.D1 \&.Ox
 .Pp
 See also
 .Sx \&At ,
@@ -1584,7 +1795,7 @@ and
 child macros (at least one must be specified).
 .Pp
 Examples:
-.Bd -literal -offset indent
+.Bd -literal -offset indent -compact
 \&.Rs
 \&.%A J. E. Hopcroft
 \&.%A J. D. Ullman
@@ -1617,9 +1828,7 @@ line.
 Format the UNIX name.  Accepts no argument.
 .Pp
 Examples:
-.Bd -literal -offset indent
-\&.Ux
-.Ed
+.D1 \&.Ux
 .Pp
 See also
 .Sx \&At ,
@@ -1633,47 +1842,126 @@ 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:
+.D1 \&.Vt unsigned char
+.D1 \&.Vt extern const char * const sys_signame[] ;
+.Pp
+See also
+.Sx \&Ft
+and
+.Sx \&Va .
+.
 .Ss \&Xc
+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.
+.
 .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:
+.D1 \&.Xr mandoc 1
+.D1 \&.Xr mandoc 1 ;
+.D1 \&.Xr mandoc 1 \&Ns s behaviour
+.
 .Ss \&br
 .Ss \&sp
 .
 .
 .Sh COMPATIBILITY
-This section documents compatibility with other roff implementations, at
-this time limited to
-.Xr groff 1 .
+This section documents compatibility between mandoc and other other
+troff implementations, at this time limited to GNU troff
+.Pq Qq groff .
 The term
 .Qq historic groff
-refers to those versions before the
+refers to groff versions before the
 .Pa doc.tmac
 file re-write
 .Pq somewhere between 1.15 and 1.19 .
 .
 .Pp
+Heirloom troff, the other significant troff implementation accepting
+\-mdoc, is similar to historic groff.
+.
+.Pp
 .Bl -dash -compact
 .It
-Negative scaling units are now truncated to zero instead of creating
-interesting conditions, such as with
-.Sq \&sp -1i .
-Furthermore, the
+The comment syntax
+.Sq \e."
+is no longer accepted.
+.
+.It
+In groff, the
+.Sx \&Pa
+macro does not format its arguments when used in the FILES section under
+certain list types.  mandoc does.
+.
+.It
+Historic groff does not print a dash for empty
+.Sx \&Fl
+arguments.  mandoc and newer groff implementations do.
+.It
+groff behaves irregularly when specifying
+.Sq \ef
+.Sx Text Decoration
+within line-macro scopes.  mandoc follows a consistent system.
+.
+.It
+In mandoc, negative scaling units are truncated to zero; groff would
+move to prior lines.  Furthermore, the
 .Sq f
 scaling unit, while accepted, is rendered as the default unit.
+.
 .It
 In quoted literals, groff allowed pair-wise double-quotes to produce a
 standalone double-quote in formatted output.  This idiosyncratic
-behaviour is no longer applicable.
+behaviour is not applicable in mandoc.
+.
 .It
 Display types
-.Sx \&Bd Fl center
+.Sx \&Bd
+.Fl center
 and
 .Fl right
 are aliases for
-.Fl left .
-The
+.Fl left
+in manodc.  Furthermore, the
 .Fl file Ar file
-argument is ignored.  Since text is not right-justified,
+argument is ignored.  Lastly, since text is not right-justified in
+mandoc (or even groff),
 .Fl ragged
 and
 .Fl filled
@@ -1681,35 +1969,50 @@ are aliases, as are
 .Fl literal
 and
 .Fl unfilled .
+.
 .It
-Blocks of whitespace are stripped from both macro and free-form text
-lines (except when in literal mode), while groff would retain whitespace
-in free-form text lines.
+In mandoc, blocks of whitespace are stripped from both macro and
+free-form text lines (except when in literal mode); groff would retain
+whitespace in free-form text lines.
+.
 .It
 Historic groff has many un-callable macros.  Most of these (excluding
-some block-level macros) are now callable, conforming to the
-non-historic groff version.
+some block-level macros) are now callable.
+.
 .It
 The vertical bar
 .Sq \(ba
 made historic groff
 .Qq go orbital
-but is a proper delimiter in this implementation.
+but has been a proper delimiter since then.
+.
 .It
 .Sx \&It Fl nested
 is assumed for all lists (it wasn't in historic groff): any list may be
 nested and
 .Fl enum
 lists will restart the sequence only for the sub-list.
+.
 .It
 Some manuals use
 .Sx \&Li
 incorrectly by following it with a reserved character and expecting the
-delimiter to render.  This is not supported.
+delimiter to render.  This is not supported in mandoc.
+.
 .It
 In groff, the
 .Sx \&Fo
-macro only produces the first parameter.  This is no longer the case.
+macro only produces the first parameter.  This is not the case in
+mandoc.
+.
+.It
+In groff, the
+.Sx \&Cd ,
+.Sx \&Er ,
+and
+.Sx \&Ex
+macros were stipulated only to occur in certain manual sections.  mandoc
+does not have these restrictions.
 .El
 .
 .