===================================================================
RCS file: /cvs/mandoc/mdoc.7,v
retrieving revision 1.5
retrieving revision 1.31
diff -u -p -r1.5 -r1.31
--- mandoc/mdoc.7	2009/03/16 22:19:19	1.5
+++ mandoc/mdoc.7	2009/06/22 12:22:35	1.31
@@ -1,28 +1,26 @@
-.\" $Id: mdoc.7,v 1.5 2009/03/16 22:19:19 kristaps Exp $
+.\"	$Id: mdoc.7,v 1.31 2009/06/22 12:22:35 kristaps Exp $
 .\"
 .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@kth.se>
 .\"
 .\" Permission to use, copy, modify, and distribute this software for any
-.\" purpose with or without fee is hereby granted, provided that the
-.\" above copyright notice and this permission notice appear in all
-.\" copies.
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
 .\"
-.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL
-.\" WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED
-.\" WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE
-.\" AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL
-.\" DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR
-.\" PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
-.\" TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
-.\" PERFORMANCE OF THIS SOFTWARE.
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\" 
-.Dd $Mdocdate: March 16 2009 $
-.Dt mdoc 7
+.Dd $Mdocdate: June 22 2009 $
+.Dt MDOC 7
 .Os
 .\" SECTION
 .Sh NAME
 .Nm mdoc
-.Nd mdoc macro reference
+.Nd mdoc language reference
 .\" SECTION
 .Sh DESCRIPTION
 The
@@ -30,29 +28,69 @@ The
 language is used to format 
 .Bx 
 .Ux
-manuals.  An
+manuals.  In this reference document, we describe the syntax, ontology
+and structure of the 
 .Nm
+language.  Our reference implementation is
+.Xr mandoc 1 .
+The
+.Sx COMPATIBILITY
+section describes compatibility with 
+.Xr groff 1 .
+.\" PARAGRAPH
+.Pp
+An
+.Nm
 document follows simple rules:  lines beginning with the control
-character
+character 
 .Sq \.
 are parsed for macros.  Other lines are interpreted within the scope of
-prior macros.  This document describes the encoding, ontology and syntax
-of these macros.
+prior macros:
+.Bd -literal -offset XXX
+\&.Sh Macro lines change control state.
+Other lines are interpreted within the current state.
+.Ed
 .\" SECTION
-.Sh CHARACTER ENCODING
+.Sh INPUT ENCODING
 .Nm
-documents may contain only printable alphanumeric characters, the space
+documents may contain only graphable 7-bit ASCII characters, the space
 character
 .Sq \  ,
 and, in certain circumstances, the tab character
 .Sq \et .
 All manuals must have
 .Sq \en
-line termination.
+line termination.  
+.Pp
+The only time a blank line is acceptable is within
+the context of 
+.Sq \&.Bd \-literal
+or
+.Sq \&.Bd \-unfilled .
+.Pp
+Tab characters 
+.Pq \et
+are only acceptable when delimiting 
+.Sq \&.Bl \-column 
+and in
+.Sq \&.Bd \-literal
+or
+.Sq \&.Bd \-unfilled
+contexts.
 .\" SUB-SECTION
+.Ss Comments
+Anything following a
+.Sq \e" 
+delimiter is considered a comment (unless the 
+.Sq \e
+itself has been escaped) and is ignored to the end of line.
+Furthermore, a macro line with only a control character
+.Sq \. ,
+optionally followed by whitespace, is ignored.
+.\" SUB-SECTION
 .Ss Reserved Characters
 Within a macro line, the following characters are reserved:
-.Bl -tag -width 12n -offset XXXX -compact
+.Bl -tag -width Ds -offset XXXX -compact
 .It \&.
 .Pq period
 .It \&,
@@ -73,6 +111,8 @@ Within a macro line, the following characters are rese
 .Pq question
 .It \&!
 .Pq exclamation 
+.It \&|
+.Pq vertical bar 
 .El
 .\" PARAGRAPH
 .Pp
@@ -85,7 +125,7 @@ or, if applicable, an appropriate escape-sequence used
 .\" SUB-SECTION
 .Ss Special Characters
 Special character sequences begin with the escape character
-.Sq \\
+.Sq \e
 followed by either an open-parenthesis 
 .Sq \&(
 for two-character sequences; an open-bracket
@@ -95,252 +135,15 @@ for n-character sequences (terminated at a close-brack
 or a single one-character sequence.
 .Pp
 Characters may alternatively be escaped by a slash-asterisk,
-.Sq \\* ,
+.Sq \e* ,
 with the same combinations as described above.  This form is deprecated.  
-.Pp
-The following is a table of all available escapes.
-.Pp
-Grammatic:
-.Bl -tag -width 12n -offset "XXXX" -compact
-.It \\(em
-.Pq em-dash
-.It \\(en
-.Pq en-dash
-.It \e-
-.Pq hyphen
-.It \\\\
-.Pq back-slash
-.It \e'
-.Pq apostrophe
-.It \e`
-.Pq back-tick
-.It \\
-.Pq space
-.It \\.
-.Pq period
-.El
-.\" PARAGRAPH
-.Pp
-Enclosures:
-.Bl -tag -width 12n -offset "XXXX" -compact
-.It \\(lh
-.Pq left hand
-.It \\(rh
-.Pq right hand
-.It \\(<<
-.Pq left guillemot
-.It \\(>>
-.Pq right guillemot
-.It \\(rC
-.Pq right brace
-.It \\(lC
-.Pq left brace
-.It \\(ra
-.Pq right angle
-.It \\(la
-.Pq left angle
-.It \\(rB
-.Pq right bracket
-.It \\(lB
-.Pq left bracket
-.It \\q
-.Pq double-quote
-.It \\(lq
-.Pq left double-quote
-.It \\(Lq
-.Pq left double-quote, deprecated
-.It \\(rq
-.Pq right double-quote
-.It \\(Rq
-.Pq right double-quote, deprecated
-.It \\(oq
-.Pq left single-quote
-.It \\(aq
-.Pq right single-quote
-.El
-.\" PARAGRAPH
-.Pp
-Indicatives:
-.Bl -tag -width 12n -offset "XXXX" -compact
-.It \\(<-
-.Pq left arrow
-.It \\(->
-.Pq right arrow
-.It \\(ua
-.Pq up arrow
-.It \\(da
-.Pq down arrow
-.It \\(<>
-.Pq left-right arrow
-.It \\(lA
-.Pq left double-arrow
-.It \\(rA
-.Pq right double-arrow
-.It \\(uA
-.Pq up double-arrow
-.It \\(dA
-.Pq down double-arrow
-.It \\(hA
-.Pq left-right double-arrow
-.El
-.\" PARAGRAPH
-.Pp
-Mathematical:
-.Bl -tag -width 12n -offset "XXXX" -compact
-.It \\(Gt
-.Pq greater-than, deprecated
-.It \\(Lt
-.Pq less-than, deprecated
-.It \\(<=
-.Pq less-than-equal
-.It \\(Le
-.Pq less-than-equal, deprecated
-.It \\(>=
-.Pq greater-than-equal
-.It \\(Ge
-.Pq greater-than-equal
-.It \\(==
-.Pq equal
-.It \\(!=
-.Pq not equal
-.It \\(Ne
-.Pq not equal, deprecated
-.It \\(if
-.Pq infinity
-.It \\(If
-.Pq infinity, deprecated
-.It \\(na
-.Pq NaN , an extension
-.It \\(Na
-.Pq NaN, deprecated
-.It \\(+-
-.Pq plus-minus
-.It \\(Pm
-.Pq plus-minus, deprecated
-.It \\(**
-.Pq asterisk
-.El
-.\" PARAGRAPH
-.Pp
-Diacritics and letter combinations:
-.Bl -tag -width 12n -offset "XXXX" -compact
-.It \\(ga
-.Pq accent grave
-.It \\(aa
-.Pq accent accute
-.It \\(ad
-.Pq accent dieresis
-.It \\(a~
-.Pq accent tilde
-.It \\(AE
-.Pq upper-case AE
-.It \\(ae
-.Pq lower-case AE
-.It \\(OE
-.Pq upper-case OE
-.It \\(oe
-.Pq lower-case OE
-.It \\('A
-.Pq upper-case acute A
-.It \\('E
-.Pq upper-case acute E
-.It \\('I
-.Pq upper-case acute I
-.It \\('O
-.Pq upper-case acute O
-.It \\('U
-.Pq upper-case acute U
-.It \\('a
-.Pq lower-case acute a
-.It \\('e
-.Pq lower-case acute e
-.It \\('i
-.Pq lower-case acute i
-.It \\('o
-.Pq lower-case acute o
-.It \\('u
-.Pq lower-case acute u
-.It \\(`A
-.Pq upper-case grave A
-.It \\(`E
-.Pq upper-case grave E
-.It \\(`I
-.Pq upper-case grave I
-.It \\(`O
-.Pq upper-case grave O
-.It \\(`U
-.Pq upper-case grave U
-.It \\(`a
-.Pq lower-case grave a
-.It \\(`e
-.Pq lower-case grave e
-.It \\(`i
-.Pq lower-case grave i
-.It \\(`o
-.Pq lower-case grave o
-.It \\(`u
-.Pq lower-case grave u
-.It \\(~A
-.Pq upper-case tilde A
-.It \\(~N
-.Pq upper-case tilde N
-.It \\(~O
-.Pq upper-case tilde O
-.It \\(~a
-.Pq lower-case tilde a
-.It \\(~n
-.Pq lower-case tilde n
-.It \\(~o
-.Pq lower-case tilde o
-.It \\(:A
-.Pq upper-case dieresis A
-.It \\(:E
-.Pq upper-case dieresis E
-.It \\(:I
-.Pq upper-case dieresis I
-.It \\(:O
-.Pq upper-case dieresis O
-.It \\(:U
-.Pq upper-case dieresis U
-.It \\(:a
-.Pq lower-case dieresis a
-.It \\(:e
-.Pq lower-case dieresis e
-.It \\(:i
-.Pq lower-case dieresis i
-.It \\(:o
-.Pq lower-case dieresis o
-.It \\(:u
-.Pq lower-case dieresis u
-.It \\(:y
-.Pq lower-case dieresis y
-.El
-.\" PARAGRAPH
-.Pp
-Special symbols:
-.Bl -tag -width 12n -offset "XXXX" -compact
-.It \\(bu
-.Pq bullet
-.It \\(ba
-.Pq bar
-.It \\(Ba
-.Pq bar, deprecated
-.It \\(co
-.Pq copyright
-.It \\(rg
-.Pq registered
-.It \\(tm
-.Pq trademarked
-.It \\&
-.Pq non-breaking space
-.It \\e
-.Pq escape
-.It \\(Am
-.Pq ampersand, deprecated
-.El 
 .\" SECTION
-.Sh ONTOLOGY
-Macros are classified in an ontology described by scope rules.  
+.Sh STRUCTURE
+Macros are classified in an ontology described by their scope rules.
+Some macros are allowed to deviate from their classifications to
+preserve backward-compatibility with old macro combinations still found
+in the manual corpus.  These are specifically noted on a per-macro
+basis.
 .\" SUB-SECTION
 .Ss Scope
 .Bl -inset 
@@ -422,8 +225,8 @@ subsequent tokens are interpreted as if the scope had 
 In other circumstances, scope is simply closed out.
 .\" SECTION
 .Sh SYNTAX
-Macros are generally two and at times three characters in length.  The
-syntax of macro invocation depends on its classification.  
+Macros are two or three characters in length.  The syntax of macro
+invocation depends on its classification.  
 .Qq \-arg
 refers to the macro arguments (which may contain zero or more values).
 In these illustrations, 
@@ -481,7 +284,7 @@ This section contains a complete list of all 
 .Nm
 macros, arranged ontologically.  A 
 .Qq callable
-macro is may be invoked subsequent to the initial macro-line macro.  A
+macro is invoked subsequent to the initial macro-line macro.  A
 .Qq parsable
 macro may be followed by further (ostensibly callable) macros.
 .\" SUB-SECTION
@@ -490,7 +293,7 @@ The head of these macros follows invocation; the body 
 subsequent lines prior to closure.  None of these macros have tails;
 some 
 .Po
-.Sq \&It \-bullet , 
+.Sq \&.It \-bullet , 
 .Sq \-hyphen , 
 .Sq \-dash ,
 .Sq \-enum ,
@@ -498,7 +301,7 @@ some 
 .Pc
 don't have heads.
 .Pp
-.Bl -column "MacroX" "CallableX" "ParsableX" "Closing" -compact -offset XXXX
+.Bl -column -compact -offset XXXX "MacroX" "CallableX" "ParsableX" "Closing"
 .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Closing
 .It \&.Sh    Ta    \&No    Ta    \&No    Ta    \&.Sh
 .It \&.Ss    Ta    \&No    Ta    \&No    Ta    \&.Sh, \&.Ss
@@ -510,7 +313,7 @@ None of these macros are callable or parsed.  The last
 the explicit scope rules.  All contains bodies, some may contain heads 
 .Pq So \&Bf Sc .
 .Pp
-.Bl -column "MacroX" "CallableX" "ParsableX" "closed by XXX" -compact -offset XXXX
+.Bl -column -compact -offset XXXX "MacroX" "CallableX" "ParsableX" "closed by XXX"
 .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope
 .It \&.Bd    Ta    \&No    Ta    \&No    Ta    closed by \&.Ed
 .It \&.Ed    Ta    \&No    Ta    \&No    Ta    opened by \&.Bd
@@ -540,13 +343,31 @@ close at the invocation's end-of-line.
 .It \&.Dl    Ta    \&No  Ta    Yes
 .It \&.Ql    Ta    Yes   Ta    Yes
 .El
+.\" PARAGRAPH
+.Pp
+The
+.Sq \&.Op
+may be broken by 
+.Sq \&.Oc 
+as in the following example:
+.Bd -literal -offset XXXX
+\&.Oo
+\&.Op Fl a Oc
+.Ed
+.Pp
+In the above example, the scope of
+.Sq \&.Op
+is technically broken by 
+.Sq \&.Oc ,
+however, due to the overwhelming existence of this sequence, it's
+allowed.
 .\" SUB-SECTION
 .Ss Block partial-explicit
 Each of these contains at least a body and, in limited circumstances, a
 head 
-.Pq So \&Fo Sc , So \&Eo Sc
+.Pq So \&.Fo Sc , So \&.Eo Sc
 and/or tail 
-.Pq So \&Ec Sc .
+.Pq So \&.Ec Sc .
 .Pp
 .Bl -column "MacroX" "CallableX" "ParsableX" "closed by XXXX" -compact -offset XXXX
 .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope
@@ -589,29 +410,29 @@ then the macro accepts an arbitrary number of argument
 .It \&.Os    Ta    \&No  Ta    \&No    Ta    n
 .It \&.Pp    Ta    \&No  Ta    \&No    Ta    0
 .It \&.Ad    Ta    Yes   Ta    Yes     Ta    n
-.It \&.An    Ta    \&No  Ta    Yes     Ta    n
+.It \&.An    Ta    Yes   Ta    Yes     Ta    n
 .It \&.Ar    Ta    Yes   Ta    Yes     Ta    n
 .It \&.Cd    Ta    Yes   Ta    \&No    Ta    >0
 .It \&.Cm    Ta    Yes   Ta    Yes     Ta    n
-.It \&.Dv    Ta    Yes   Ta    Yes     Ta    >0
+.It \&.Dv    Ta    Yes   Ta    Yes     Ta    n
 .It \&.Er    Ta    Yes   Ta    Yes     Ta    >0
-.It \&.Ev    Ta    Yes   Ta    Yes     Ta    >0
+.It \&.Ev    Ta    Yes   Ta    Yes     Ta    n
 .It \&.Ex    Ta    \&No  Ta    \&No    Ta    0
-.It \&.Fa    Ta    Yes   Ta    Yes     Ta    >0
+.It \&.Fa    Ta    Yes   Ta    Yes     Ta    n
 .It \&.Fd    Ta    \&No  Ta    \&No    Ta    >0
 .It \&.Fl    Ta    Yes   Ta    Yes     Ta    n
 .It \&.Fn    Ta    Yes   Ta    Yes     Ta    >0
-.It \&.Ft    Ta    \&No  Ta    Yes     Ta    n
+.It \&.Ft    Ta    Yes   Ta    Yes     Ta    n
 .It \&.Ic    Ta    Yes   Ta    Yes     Ta    >0
 .It \&.In    Ta    \&No  Ta    \&No    Ta    n
-.It \&.Li    Ta    Yes   Ta    Yes     Ta    >0
+.It \&.Li    Ta    Yes   Ta    Yes     Ta    n
 .It \&.Nd    Ta    \&No  Ta    \&No    Ta    n
 .It \&.Nm    Ta    Yes   Ta    Yes     Ta    n
 .It \&.Ot    Ta    \&No  Ta    \&No    Ta    n
 .It \&.Pa    Ta    Yes   Ta    Yes     Ta    n
 .It \&.Rv    Ta    \&No  Ta    \&No    Ta    0
 .It \&.St    Ta    \&No  Ta    Yes     Ta    1
-.It \&.Va    Ta    Yes   Ta    Yes     Ta    >0
+.It \&.Va    Ta    Yes   Ta    Yes     Ta    n
 .It \&.Vt    Ta    Yes   Ta    Yes     Ta    >0
 .It \&.Xr    Ta    Yes   Ta    Yes     Ta    >0, <3
 .It \&.%A    Ta    \&No  Ta    \&No    Ta    >0
@@ -632,7 +453,7 @@ then the macro accepts an arbitrary number of argument
 .It \&.Db    Ta    \&No  Ta    \&No    Ta    1
 .It \&.Em    Ta    Yes   Ta    Yes     Ta    >0
 .It \&.Fx    Ta    Yes   Ta    Yes     Ta    n
-.It \&.Ms    Ta    \&No  Ta    Yes     Ta    >0
+.It \&.Ms    Ta    Yes   Ta    Yes     Ta    >0
 .It \&.No    Ta    Yes   Ta    Yes     Ta    0
 .It \&.Ns    Ta    Yes   Ta    Yes     Ta    0
 .It \&.Nx    Ta    Yes   Ta    Yes     Ta    n
@@ -643,6 +464,7 @@ then the macro accepts an arbitrary number of argument
 .It \&.Sy    Ta    Yes   Ta    Yes     Ta    >0
 .It \&.Tn    Ta    Yes   Ta    Yes     Ta    >0
 .It \&.Ux    Ta    Yes   Ta    Yes     Ta    n
+.It \&.Dx    Ta    Yes   Ta    Yes     Ta    n
 .It \&.Bt    Ta    \&No  Ta    \&No    Ta    0
 .It \&.Hf    Ta    \&No  Ta    \&No    Ta    n
 .It \&.Fr    Ta    \&No  Ta    \&No    Ta    n
@@ -650,69 +472,79 @@ then the macro accepts an arbitrary number of argument
 .It \&.Lb    Ta    \&No  Ta    \&No    Ta    1
 .It \&.Ap    Ta    Yes   Ta    Yes     Ta    0
 .It \&.Lp    Ta    \&No  Ta    \&No    Ta    0
-.It \&.Lk    Ta    \&No  Ta    Yes     Ta    >0
-.It \&.Mt    Ta    \&No  Ta    Yes     Ta    >0
+.It \&.Lk    Ta    Yes   Ta    Yes     Ta    n
+.It \&.Mt    Ta    Yes   Ta    Yes     Ta    >0
+.It \&.Es    Ta    \&No  Ta    \&No    Ta    0
+.It \&.En    Ta    \&No  Ta    \&No    Ta    0
 .El
+.Pp
+The
+.Sq \&.Ot ,
+.Sq \&.Fr ,
+.Sq \&.Es 
+and
+.Sq \&.En ,
+macros are obsolete.
 .\" SECTION
 .Sh COMPATIBILITY
-The mdoc language was traditionally a 
-.Qq roff
-macro package; most existing manuals were written with mdoc syntax
-dictated by system-dependent roff installations.  This section documents
-compatibility with these systems.
+This section documents compatibility with other roff implementations, at
+this time limited to 
+.Xr groff 1 .
+The term 
+.Qq historic groff
+refers to those versions before the 
+.Pa doc.tmac
+file re-write 
+.Pq somewhere between 1.15 and 1.19 .
 .Pp
 .Bl -dash -compact
 .\" LIST-ITEM
 .It
-.Sq \&Fo
-and
-.Sq \&St
-historically weren't always callable.  Both are now correctly callable.
+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.
 .\" LIST-ITEM
 .It
-.Sq \&It \-nested
-is assumed for all lists: any list may be nested and
+The vertical bar 
+.Sq \(Ba
+made historic groff
+.Qq go orbital
+but is a proper delimiter in this implementation.
+.\" LIST-ITEM
+.It
+.Sq \&.It \-nested
+is assumed for all lists (it wasn't in historic groff): any list may be
+nested and
 .Sq \-enum
 lists will restart the sequence only for the sub-list.
 .\" LIST-ITEM
 .It
-.Sq \&It \-column
-syntax where column widths may be preceeded by other arguments (instead
+.Sq \&.It \-column
+syntax where column widths may be preceded by other arguments (instead
 of proceeded) is not supported.
 .\" LIST-ITEM
 .It
 The 
-.Sq \&At
+.Sq \&.At
 macro only accepts a single parameter.
 .\" LIST-ITEM
 .It
-The system-name macros (
-.Ns Sq \&At ,
-.Sq \&Bsx ,
-.Sq \&Bx ,
-.Sq \&Fx ,
-.Sq \&Nx ,
-.Sq \&Ox ,
-and
-.Sq \&Ux )
-are callable.
-.\" LIST-ITEM
-.It
 Some manuals use
-.Sq \&Li
+.Sq \&.Li
 incorrectly by following it with a reserved character and expecting the
 delimiter to render.  This is not supported.
 .\" LIST-ITEM
 .It
-.Sq \&Cd
-is callable.
+If an special-character control character 
+.Sq \e 
+is escaped, it will
+obviously not render the sequence.  Even newer versions of groff seem to
+dither on this.
 .El
 .\" SECTION
 .Sh SEE ALSO
-.Xr mdoctree 1 ,
-.Xr mdoclint 1 ,
-.Xr mdocterm 1 ,
-.Xr mdoc 3
+.Xr mandoc 1 ,
+.Xr mandoc_char 7
 .\" SECTION
 .Sh AUTHORS
 The
@@ -721,56 +553,74 @@ utility was written by 
 .An Kristaps Dzonsons Aq kristaps@kth.se .
 .\" SECTION
 .Sh CAVEATS
-There are several ambiguous parts of mdoc.
+There are many ambiguous parts of mdoc.
 .Pp
 .Bl -dash -compact
 .\" LIST-ITEM
 .It
-.Sq \&Fa
+.Sq \&.Fa
 should be 
-.Sq \&Va
+.Sq \&.Va
 as function arguments are variables.
 .\" LIST-ITEM
 .It
-.Sq \&Ft
+.Sq \&.Ft
 should be
-.Sq \&Vt
+.Sq \&.Vt
 as function return types are still types.  Furthermore, the
-.Sq \&Ft
+.Sq \&.Ft
 should be removed and
-.Sq \&Fo ,
+.Sq \&.Fo ,
 which ostensibly follows it, should follow the same convention as
-.Sq \&Va .
+.Sq \&.Va .
 .\" LIST-ITEM
 .It
-.Sq \&Va
+.Sq \&.Va
 should formalise that only one or two arguments are acceptable: a
-variable name and optional, preceeding type.
+variable name and optional, preceding type.
 .\" LIST-ITEM
 .It
-.Sq \&Fd
+.Sq \&.Fd
 is ambiguous.  It's commonly used to indicate an include file in the
 synopsis section.  
-.Sq \&In
+.Sq \&.In
 should be used, instead.
 .\" LIST-ITEM
 .It
 Only the
 .Sq \-literal
 argument to
-.Sq \&Bd
+.Sq \&.Bd
 makes sense.  The remaining ones should be removed.
 .\" LIST-ITEM
 .It
 The 
-.Sq \&Xo
+.Sq \&.Xo
 and
-.Sq \&Xc
+.Sq \&.Xc
 macros should be deprecated.
 .\" LIST-ITEM
 .It
 The
-.Sq \&Dt
+.Sq \&.Dt
 macro lacks clarity.  It should be absolutely clear which title will
 render when formatting the manual page.
+.\" LIST-ITEM
+.It
+A
+.Sq \&.Lx
+should be provided for Linux (\(`a la 
+.Sq \&.Ox ,
+.Sq \&.Nx 
+etc.).
+.\" LIST-ITEM
+.It
+There's no way to refer to references in
+.Sq \&.Rs/.Re
+blocks.
+.\" LIST-ITEM
+.It
+The \-split and \-nosplit arguments to 
+.Sq \&.An
+are inane.
 .El