===================================================================
RCS file: /cvs/mandoc/mdoc.7,v
retrieving revision 1.64
retrieving revision 1.87
diff -u -p -r1.64 -r1.87
--- mandoc/mdoc.7	2009/10/19 10:18:05	1.64
+++ mandoc/mdoc.7	2010/03/31 07:13:53	1.87
@@ -1,4 +1,4 @@
-.\"	$Id: mdoc.7,v 1.64 2009/10/19 10:18:05 kristaps Exp $
+.\"	$Id: mdoc.7,v 1.87 2010/03/31 07:13:53 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 19 2009 $
+.Dd $Mdocdate: March 31 2010 $
 .Dt MDOC 7
 .Os
 .
@@ -131,18 +131,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,
@@ -210,7 +250,31 @@ considered literal text.  Thus, the following produces
 In free-form mode, quotes are regarded as opaque text.
 .
 .Ss Dates
-TODO.
+There are several macros in
+.Nm
+that require a date argument.  The canonical form for dates is the
+American format:
+.Pp
+.D1 Cm Month Day , Year
+.Pp
+The
+.Cm Day
+value is an optionally zero-padded numeral.  The
+.Cm Month
+value is the full month name.  The
+.Cm Year
+value is the full four-digit year.
+.Pp
+Reduced form dates are broken-down canonical form dates:
+.Pp
+.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
 .
 .Ss Scaling Widths
 Many macros support scaled widths for their arguments, such as
@@ -267,17 +331,31 @@ is necessarily non-portable across output media.  See
 .
 .
 .Sh MANUAL STRUCTURE
-Each
+A well-formed
 .Nm
-document must begin with a document prologue, containing, in order,
+document consists of a document prologue followed by one or more
+sections.
+.Pp
+The prologue, which consists of (in order) the
 .Sx \&Dd ,
 .Sx \&Dt ,
 and
-.Sx \&Os ,
-then the NAME section containing at least one
+.Sx \&Os
+macros, is required for every document.
+.Pp
+The first section (sections are denoted by
+.Sx \&Sh )
+must be the NAME section, consisting of at least one
 .Sx \&Nm
 followed by
-.Sx \&Nd :
+.Sx \&Nd .
+.Pp
+Following that, convention dictates specifying at least the SYNOPSIS and
+DESCRIPTION sections, although this varies between manual sections.
+.Pp
+The following is a well-formed skeleton
+.Nm
+file:
 .Bd -literal -offset indent
 \&.Dd $\&Mdocdate$
 \&.Dt mdoc 7
@@ -320,12 +398,207 @@ utility processes files ...
 \&.\e\*q .Sh BUGS
 \&.\e\*q .Sh SECURITY CONSIDERATIONS
 .Ed
+.Pp
+The sections in a
+.Nm
+document are conventionally ordered as they appear above.  Sections
+should be composed as follows:
+.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
+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
+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
-Subsequent SYNOPSIS and DESCRIPTION sections are strongly encouraged,
-but non-compulsory.
+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
+.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
+.
+.
 .Sh MACRO SYNTAX
 Macros are one to three three characters in length and begin with a
 control character ,
@@ -410,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
@@ -497,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
@@ -528,8 +810,10 @@ then the macro accepts an arbitrary number of argument
 .It Sx \&%N  Ta    \&No     Ta    \&No     Ta    >0
 .It Sx \&%O  Ta    \&No     Ta    \&No     Ta    >0
 .It Sx \&%P  Ta    \&No     Ta    \&No     Ta    >0
+.It Sx \&%Q  Ta    \&No     Ta    \&No     Ta    >0
 .It Sx \&%R  Ta    \&No     Ta    \&No     Ta    >0
 .It Sx \&%T  Ta    \&No     Ta    \&No     Ta    >0
+.It Sx \&%U  Ta    \&No     Ta    \&No     Ta    >0
 .It Sx \&%V  Ta    \&No     Ta    \&No     Ta    >0
 .It Sx \&Ad  Ta    Yes      Ta    Yes      Ta    n
 .It Sx \&An  Ta    Yes      Ta    Yes      Ta    n
@@ -588,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
@@ -604,10 +888,8 @@ Author name of an
 .Sx \&Rs
 block.  Multiple authors should each be accorded their own
 .Sx \%%A
-line.
-.Pp
-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
@@ -620,14 +902,15 @@ Publication city or location of an
 .Sx \&Rs
 block.
 .Pp
-.Em Compatibility remark :
+.Em Remarks :
 this macro is not implemented in
 .Xr groff 1 .
 .
 .Ss \&%D
 Publication date of an
 .Sx \&Rs
-block.  This should follow the canonical syntax for 
+block.  This should follow the reduced or canonical form syntax
+described in
 .Sx Dates .
 .
 .Ss \&%I
@@ -673,6 +956,9 @@ Article title of an
 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
 Volume number of an
 .Sx \&Rs
@@ -698,7 +984,7 @@ Author name.  This macro may alternatively accepts the
 arguments, although these may not be specified along with a parameter:
 .Bl -tag -width 12n -offset indent
 .It Fl split
-Renders a line break is rendered before each author listing.
+Renders a line break before each author listing.
 .It Fl nosplit
 The opposite of
 .Fl split .
@@ -749,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
@@ -770,9 +1056,9 @@ See also
 .Sx \&Ao .
 .
 .Ss \&Ar
-Command arguments.  If an argument is not provided, the strings
+Command arguments.  If an argument is not provided, the string
 .Dq file ...
-are used as a default.
+is used as a default.
 .Pp
 Examples:
 .Bd -literal -offset indent
@@ -796,9 +1082,19 @@ Note that these parameters do not begin with a hyphen.
 .Pp
 Examples:
 .Bd -literal -offset indent
-\&.At 
+\&.At
 \&.At V.1
 .Ed
+.Pp
+See also
+.Sx \&Bsx ,
+.Sx \&Bx ,
+.Sx \&Dx ,
+.Sx \&Fx ,
+.Sx \&Nx ,
+.Sx \&Ox ,
+and
+.Sx \&Ux .
 .
 .Ss \&Bc
 Closes a
@@ -850,7 +1146,7 @@ which aligns around an imagined centre axis.
 .It
 As a precalculated width for a named macro.  The most popular is the
 imaginary macro
-.Ar Ds ,
+.Ar \&Ds ,
 which resolves to
 .Ar 6n .
 .It
@@ -874,64 +1170,549 @@ before any text or macros within the block.
 .Pp
 Examples:
 .Bd -literal -offset indent
-\&.Bd \-literal \-offset indent
-int 
-main(void) 
-{
-        printf("Hello, world!\en");
-}
-\&.Ed
-
 \&.Bd \-unfilled \-offset two-indent \-compact
-Hello
-      world.
+   Hello       world.
 \&.Ed
 .Ed
+.Pp
+See also
+.Sx \&D1
+and
+.Sx \&Dl .
 .
 .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.
+.Pp
+Examples:
+.Bd -literal -offset indent
+\&.Bo 1 ,
+\&.Dv BUFSIZ Bc
+.Ed
+.Pp
+See also
+.Sx \&Bq .
+.
 .Ss \&Bq
+Encloses its arguments in square brackets.
+.Pp
+Examples:
+.Bd -literal -offset indent
+\&.Bq 1 , Dv BUFSIZ
+.Ed
+.Pp
+.Em Remarks :
+this macro is sometimes abused to emulate optional arguments for
+commands; the correct macros to use for this purpose are
+.Sx \&Op ,
+.Sx \&Oo ,
+and
+.Sx \&Oc .
+.Pp
+See also
+.Sx \&Bo .
+.
 .Ss \&Brc
+Closes a
+.Sx \&Bro
+block.  Does not have any tail arguments.
+.
 .Ss \&Bro
+Begins a block enclosed by curly braces.  Does not have any head
+arguments.
+.Pp
+Examples:
+.Bd -literal -offset indent
+\&.Bro 1 , ... ,
+\&.Va n Brc
+.Ed
+.Pp
+See also
+.Sx \&Brq .
+.
 .Ss \&Brq
+Encloses its arguments in curly braces.
+.Pp
+Examples:
+.Bd -literal -offset indent
+\&.Brq 1 , ... , Va n
+.Ed
+.Pp
+See also
+.Sx \&Bro .
+.
 .Ss \&Bsx
+Format the BSD/OS version provided as an argument, or a default value if
+no argument is provided.
+.Pp
+Examples:
+.Bd -literal -offset indent
+\&.Bsx 1.0
+\&.Bsx
+.Ed
+.Pp
+See also
+.Sx \&At ,
+.Sx \&Bx ,
+.Sx \&Dx ,
+.Sx \&Fx ,
+.Sx \&Nx ,
+.Sx \&Ox ,
+and
+.Sx \&Ux .
+.
 .Ss \&Bt
+Prints
+.Dq is currently in beta test.
+.
 .Ss \&Bx
+Format the BSD version provided as an argument, or a default value if no
+argument is provided.
+.Pp
+Examples:
+.Bd -literal -offset indent
+\&.Bx 4.4
+\&.Bx
+.Ed
+.Pp
+See also
+.Sx \&At ,
+.Sx \&Bsx ,
+.Sx \&Dx ,
+.Sx \&Fx ,
+.Sx \&Nx ,
+.Sx \&Ox ,
+and
+.Sx \&Ux .
+.
 .Ss \&Cd
+Configuration declaration (suggested for use only in section four
+manuals).  This denotes strings accepted by
+.Xr config 8 .
+.Pp
+Examples:
+.Bd -literal -offset indent
+\&.Cd device le0 at scode?
+.Ed
+.Pp
+.Em Remarks :
+this macro is commonly abused by using quoted literals to retain
+white-space and align consecutive
+.Sx \&Cd
+declarations.  This practise is discouraged.
+.
 .Ss \&Cm
+Command modifiers.  Useful when specifying configuration options or
+keys.
+.Pp
+Examples:
+.Bd -literal -offset indent
+\&.Cm ControlPath
+\&.Cm ControlMaster
+.Ed
+.Pp
+See also
+.Sx \&Fl .
+.
 .Ss \&D1
+One-line indented display.  This is formatted by the default rules and
+is useful for simple indented statements.  It is followed by a newline.
+.Pp
+Examples:
+.Bd -literal -offset indent
+\&.D1 Fl abcdefgh
+.Ed
+.Pp
+See also
+.Sx \&Bd
+and
+.Sx \&Dl .
+.
 .Ss \&Db
 .Ss \&Dc
+Closes a
+.Sx \&Do
+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:
+.Pp
+.D1 \. Ns Sx \&Dd Cm date
+.Pp
+The
+.Cm date
+field may be either
+.Ar $\&Mdocdate$ ,
+which signifies the current manual revision date dictated by
+.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
+.Pp
+See also
+.Sx \&Dt
+and
+.Sx \&Os .
+.
 .Ss \&Dl
+One-line intended display.  This is formatted as literal text and is
+useful for commands and invocations.  It is followed by a newline.
+.Pp
+Examples:
+.Bd -literal -offset indent
+\&.Dl % mandoc mdoc.7 | less
+.Ed
+.Pp
+See also
+.Sx \&Bd
+and
+.Sx \&D1 .
+.
 .Ss \&Do
+Begins a block enclosed by double quotes.  Does not have any head
+arguments.
+.Pp
+Examples:
+.Bd -literal -offset indent
+\&.D1 Do April is the cruellest month Dc \e(em T.S. Eliot
+.Ed
+.Pp
+See also
+.Sx \&Dq .
+.
 .Ss \&Dq
+Encloses its arguments in double quotes.
+.Pp
+Examples:
+.Bd -literal -offset indent
+\&.Dq April is the cruellest month
+\e(em T.S. Eliot
+.Ed
+.Pp
+See also
+.Sx \&Do .
+.
 .Ss \&Dt
+Document title.  This is the mandatory second macro of any
+.Nm
+file.  Its calling syntax is as follows:
+.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.
+.It Cm section
+The manual section.  This may be one of
+.Ar 1
+.Pq utilities ,
+.Ar 2
+.Pq system calls ,
+.Ar 3
+.Pq libraries ,
+.Ar 3p
+.Pq Perl libraries ,
+.Ar 4
+.Pq devices ,
+.Ar 5
+.Pq file formats ,
+.Ar 6
+.Pq games ,
+.Ar 7
+.Pq miscellaneous ,
+.Ar 8
+.Pq system utilities ,
+.Ar 9
+.Pq kernel functions ,
+.Ar X11
+.Pq X Window System ,
+.Ar X11R6
+.Pq X Window System ,
+.Ar unass
+.Pq unassociated ,
+.Ar local
+.Pq local system ,
+.Ar draft
+.Pq draft manual ,
+or
+.Ar paper
+.Pq paper .
+It is also required and should correspond to the manual's filename
+suffix.
+.It Cm volume
+This overrides the volume inferred from
+.Ar section .
+This field is optional, and if specified, must be one of
+.Ar USD
+.Pq users' supplementary documents ,
+.Ar PS1
+.Pq programmers' supplementary documents ,
+.Ar AMD
+.Pq administrators' supplementary documents ,
+.Ar SMM
+.Pq system managers' manuals ,
+.Ar URM
+.Pq users' reference manuals ,
+.Ar PRM
+.Pq programmers' reference manuals ,
+.Ar KM
+.Pq kernel manuals ,
+.Ar IND
+.Pq master index ,
+.Ar MMI
+.Pq master index ,
+.Ar LOCAL
+.Pq local manuals ,
+.Ar LOC
+.Pq local manuals ,
+or
+.Ar CON
+.Pq contributed manuals .
+.It Cm arch
+This specifies a specific relevant architecture.  If
+.Cm volume
+is not provided, it may be used in its place, else it may be used
+subsequent that.  It, too, is optional.  It must be one of
+.Ar alpha ,
+.Ar amd64 ,
+.Ar amiga ,
+.Ar arc ,
+.Ar arm ,
+.Ar armish ,
+.Ar aviion ,
+.Ar hp300 ,
+.Ar hppa ,
+.Ar hppa64 ,
+.Ar i386 ,
+.Ar landisk ,
+.Ar loongson ,
+.Ar luna88k ,
+.Ar mac68k ,
+.Ar macppc ,
+.Ar mvme68k ,
+.Ar mvme88k ,
+.Ar mvmeppc ,
+.Ar pmax ,
+.Ar sgi ,
+.Ar socppc ,
+.Ar sparc ,
+.Ar sparc64 ,
+.Ar sun3 ,
+.Ar vax ,
+or
+.Ar zaurus .
+.El
+.Pp
+Examples:
+.Bd -literal -offset indent
+\&.Dt FOO 1
+\&.Dt FOO 4 KM
+\&.Dt FOO 9 i386
+\&.Dt FOO 9 KM i386
+.Ed
+.Pp
+See also
+.Sx \&Dd
+and
+.Sx \&Os .
+.
 .Ss \&Dv
+Defined variables such as preprocessor constants.
+.Pp
+Examples:
+.Bd -literal -offset indent
+\&.Dv BUFSIZ
+\&.Dv STDOUT_FILENO
+.Ed
+.Pp
+See also
+.Sx \&Er .
+.
 .Ss \&Dx
+Format the DragonFly BSD version provided as an argument, or a default
+value if no argument is provided.
+.Pp
+Examples:
+.Bd -literal -offset indent
+\&.Dx 2.4.1
+\&.Dx
+.Ed
+.Pp
+See also
+.Sx \&At ,
+.Sx \&Bsx ,
+.Sx \&Bx ,
+.Sx \&Fx ,
+.Sx \&Nx ,
+.Sx \&Ox ,
+and
+.Sx \&Ux .
+.
 .Ss \&Ec
 .Ss \&Ed
 .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
+.
 .Ss \&En
 .Ss \&Eo
 .Ss \&Er
+Error constants (suggested for use only in section two manuals).
+.Pp
+Examples:
+.Bd -literal -offset indent
+\&.Er EPERM
+\&.Er ENOENT
+.Ed
+.Pp
+See also
+.Sx \&Dv .
+.
 .Ss \&Es
+.
 .Ss \&Ev
+Environmental variables such as those specified in
+.Xr environ 7 .
+.Pp
+Examples:
+.Bd -literal -offset indent
+\&.Ev DISPLAY
+\&.Ev PATH
+.Ed
+.
 .Ss \&Ex
+Inserts text regarding a utility's exit values.  This macro must have
+first the
+.Fl std
+argument specified, then an optional
+.Ar utility .
+If
+.Ar utility
+is not provided, the document's name as stipulated in
+.Sx \&Nm
+is provided.
 .Ss \&Fa
 .Ss \&Fc
 .Ss \&Fd
 .Ss \&Fl
+Command-line flag.  Used when listing arguments to command-line
+utilities.  Prints a fixed-width hyphen
+.Sq \-
+before each delimited argument.  If no arguments are provided, a hyphen
+is still printed.
+.Pp
+Examples:
+.Bd -literal -offset indent
+\&.Fl a b c
+\&.Fl
+\&.Op Fl o Ns Ar file
+.Ed
+.Pp
+See also
+.Sx \&Cm .
+.
 .Ss \&Fn
 .Ss \&Fo
 .Ss \&Fr
 .Ss \&Ft
 .Ss \&Fx
+Format the FreeBSD version provided as an argument, or a default value
+if no argument is provided.
+.Pp
+Examples:
+.Bd -literal -offset indent
+\&.Fx 7.1
+\&.Fx
+.Ed
+.Pp
+See also
+.Sx \&At ,
+.Sx \&Bsx ,
+.Sx \&Bx ,
+.Sx \&Dx ,
+.Sx \&Nx ,
+.Sx \&Ox ,
+and
+.Sx \&Ux .
+.
 .Ss \&Hf
 .Ss \&Ic
 .Ss \&In
@@ -939,6 +1720,19 @@ Hello
 .Ss \&Lb
 .Ss \&Li
 .Ss \&Lk
+Format a hyperlink.  The calling syntax is as follows:
+.Pp
+.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
+.Pp
+See also
+.Sx \&Mt .
+.
 .Ss \&Lp
 .Ss \&Ms
 .Ss \&Mt
@@ -947,12 +1741,80 @@ Hello
 .Ss \&No
 .Ss \&Ns
 .Ss \&Nx
+Format the NetBSD version provided as an argument, or a default value if
+no argument is provided.
+.Pp
+Examples:
+.Bd -literal -offset indent
+\&.Nx 5.01
+\&.Nx
+.Ed
+.Pp
+See also
+.Sx \&At ,
+.Sx \&Bsx ,
+.Sx \&Bx ,
+.Sx \&Dx ,
+.Sx \&Fx ,
+.Sx \&Ox ,
+and
+.Sx \&Ux .
+.
 .Ss \&Oc
 .Ss \&Oo
 .Ss \&Op
 .Ss \&Os
+Document operating system version.  This is the mandatory third macro of
+any
+.Nm
+file.  Its calling syntax is as follows:
+.Pp
+.D1 \. Ns Sx \&Os Op Cm system
+.Pp
+The optional
+.Cm system
+parameter specifies the relevant operating system or environment.  Left
+unspecified, it defaults to the local operating system version.  This is
+the suggested form.
+.Pp
+Examples:
+.Bd -literal -offset indent
+\&.Os
+\&.Os KTH/CSC/TCS
+\&.Os BSD 4.3
+.Ed
+.Pp
+See also
+.Sx \&Dd
+and
+.Sx \&Dt .
+.
 .Ss \&Ot
+Unknown usage.
+.Pp
+.Em Remarks :
+this macro has been deprecated.
+.
 .Ss \&Ox
+Format the OpenBSD version provided as an argument, or a default value
+if no argument is provided.
+.Pp
+Examples:
+.Bd -literal -offset indent
+\&.Ox 4.5
+\&.Ox
+.Ed
+.Pp
+See also
+.Sx \&At ,
+.Sx \&Bsx ,
+.Sx \&Bx ,
+.Sx \&Dx ,
+.Sx \&Fx ,
+.Sx \&Nx ,
+and
+.Sx \&Ux .
+.
 .Ss \&Pa
 .Ss \&Pc
 .Ss \&Pf
@@ -972,7 +1834,7 @@ block.  Does not have any tail arguments.
 .Ss \&Rs
 Begins a bibliographic
 .Pq Dq reference
-block.  Does not have any head arguments.  The block macro and may only
+block.  Does not have any head arguments.  The block macro may only
 contain
 .Sx \&%A ,
 .Sx \&%B ,
@@ -1021,11 +1883,84 @@ line.
 .Ss \&Tn
 .Ss \&Ud
 .Ss \&Ux
+Format the UNIX name.  Accepts no argument.
+.Pp
+Examples:
+.Bd -literal -offset indent
+\&.Ux
+.Ed
+.Pp
+See also
+.Sx \&At ,
+.Sx \&Bsx ,
+.Sx \&Bx ,
+.Sx \&Dx ,
+.Sx \&Fx ,
+.Sx \&Nx ,
+and
+.Sx \&Ox .
+.
 .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
+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:
+.Bd -literal -offset indent
+\&.Xr mandoc 1
+\&.Xr mandoc 1 ;
+\&.Xr mandoc 1 s behaviour
+.Ed
+.
 .Ss \&br
 .Ss \&sp
 .
@@ -1044,9 +1979,33 @@ file re-write
 .Pp
 .Bl -dash -compact
 .It
+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
+.Sx \&Fl
+arguments.  This behaviour has been discontinued.
+.It
+.Xr groff 1
+behaves strangely (even between versions) when specifying
+.Sq \ef
+escapes within line-macro scopes.  These aberrations have been
+normalised.
+.It
 Negative scaling units are now truncated to zero instead of creating
 interesting conditions, such as with
-.Sq \&sp -1i .
+.Sx \&sp
+.Fl 1i .
 Furthermore, the
 .Sq f
 scaling unit, while accepted, is rendered as the default unit.
@@ -1056,7 +2015,8 @@ standalone double-quote in formatted output.  This idi
 behaviour is no longer applicable.
 .It
 Display types
-.Sx \&Bd Fl center
+.Sx \&Bd
+.Fl center
 and
 .Fl right
 are aliases for
@@ -1086,7 +2046,8 @@ made historic groff
 .Qq go orbital
 but is a proper delimiter in this implementation.
 .It
-.Sx \&It Fl nested
+.Sx \&It
+.Fl nested
 is assumed for all lists (it wasn't in historic groff): any list may be
 nested and
 .Fl enum