Added documentation for several more macros. Only a few remaining!

Applied "new-sentence, new-line" here and there.

Refer to "whitespace", not "white-space".

Remove long-commented-out CAVEATS, all of which have been addressed or
at least discussed to some extent or another.

1 files changed, 171 insertions, 110 deletions

diff --git a/mdoc.7 b/mdoc.7
index 570ef61f..0f7e551d 100644
--- a/mdoc.7
+++ b/mdoc.7
@@ -1,4 +1,4 @@
-.\"	$Id: mdoc.7,v 1.137 2010/07/19 10:48:36 kristaps Exp $
+.\"	$Id: mdoc.7,v 1.138 2010/07/19 15:28:11 kristaps Exp $
 .\"
 .\" Copyright (c) 2009, 2010 Kristaps Dzonsons <kristaps@bsd.lv>
 .\" Copyright (c) 2010 Ingo Schwarze <schwarze@openbsd.org>
@@ -27,8 +27,10 @@ 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
@@ -37,7 +39,8 @@ An
 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.
@@ -46,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\*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,
+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.
+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
@@ -445,8 +450,8 @@ section, particularly
 .Sx \&Vt ,
 and
 .Sx \&Ft .
-All of these macros are output on their own line.  If two such
-dissimilar macros are pair-wise invoked (except for
+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
@@ -858,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
@@ -878,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
@@ -904,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
@@ -914,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
@@ -925,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.
@@ -976,7 +987,7 @@ Examples:
 See also
 .Sx \&Aq .
 .Ss \&Ap
-Inserts an apostrophe without any surrounding white-space.
+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
@@ -1040,7 +1051,8 @@ 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:
@@ -1289,8 +1301,8 @@ 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
@@ -1328,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.
@@ -1396,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.
@@ -1432,7 +1445,8 @@ Its syntax is as follows:
 .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
@@ -1475,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
@@ -1484,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
@@ -1493,8 +1509,10 @@ Examples:
 .Ed
 .Pp
 See also
+.Ss \&Qq ,
+.Ss \&Sq ,
+and
 .Sx \&Do .
-.Ss \&Dt
 Document title.
 This is the mandatory second macro of any
 .Nm
@@ -1515,7 +1533,7 @@ Its arguments are as follows:
 .Bl -tag -width Ds -offset Ds
 .It Cm title
 The document's title (name), defaulting to
-.Qq UNKNOWN
+.Dq UNKNOWN
 if unspecified.
 It should be capitalised.
 .It Cm section
@@ -1555,7 +1573,7 @@ or
 .Ar paper
 .Pq paper .
 It should correspond to the manual's filename suffix and defaults to
-.Qq 1
+.Dq 1
 if unspecified.
 .It Cm volume
 This overrides the volume inferred from
@@ -1696,6 +1714,12 @@ 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
@@ -1913,13 +1937,13 @@ is preferred for displaying code; the
 macro is used when referring to specific instructions.
 .Ss \&In
 An
-.Qq include
+.Dq include
 file.
 In the
 .Em SYNOPSIS
 section (only if invoked as the line macro), the first argument is
 preceded by
-.Qq #include ,
+.Dq #include ,
 the arguments is enclosed in angled braces.
 .Pp
 Examples:
@@ -1991,8 +2015,8 @@ 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
+interpreted as a macro).
+Note that the tab phrase delimiter may only be used within the
 .Sx \&It
 line itself.
 Subsequent this, only the
@@ -2036,6 +2060,12 @@ Examples:
 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.
 Its syntax is as follows:
@@ -2052,9 +2082,14 @@ See also
 Synonym for
 .Sx \&Pp .
 .Ss \&Ms
+Display a mathematical symbol.
+.Pp
+Examples:
+.D1 \&.Ms sigma
+.D1 \&.Ms aleph
 .Ss \&Mt
 Format a
-.Qq mailto:
+.Dq mailto:
 hyperlink.
 Its syntax is as follows:
 .Pp
@@ -2125,12 +2160,23 @@ macro rather than
 to mark up the name of the manual page.
 .Ss \&No
 A
-.Qq noop
+.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.
@@ -2157,7 +2203,7 @@ Multi-line version of
 .Sx \&Op .
 .Pp
 Examples:
-.Bd -literal -offset indent
+.Bd -literal -offset indent -compact
 \&.Oo
 \&.Op Fl flag Ns Ar value
 \&.Oc
@@ -2234,7 +2280,7 @@ Close parenthesised context opened by
 .Sx \&Po .
 .Ss \&Pf
 Removes the space
-.Pq Qq prefix
+.Pq Dq prefix
 between its arguments.
 Its syntax is as follows:
 .Pp
@@ -2259,9 +2305,29 @@ Parenthesised enclosure.
 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
@@ -2309,7 +2375,23 @@ before the rendered output, else the block continues on the current
 line.
 .Ss \&Rv
 .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:
@@ -2324,12 +2406,59 @@ 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
 .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.
@@ -2571,71 +2700,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
-.\" .