Spelling "preceed" -> "precede" (naddy).

[mandoc.git] / mdoc.7

diff --git a/mdoc.7 b/mdoc.7
index 7d321aa7b9b39570bb02cf11829794dddeefd6b0..aec7fadf0d73e786c83371c2cee6f5f937018733 100644 (file)
--- a/mdoc.7
+++ b/mdoc.7
@@ -1,4 +1,4 @@
-.\" $Id: mdoc.7,v 1.14 2009/03/23 14:22:11 kristaps Exp $
+.\" $Id: mdoc.7,v 1.21 2009/04/12 19:30:45 kristaps Exp $

 .\"
 .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@openbsd.org>
 .\"
 .\"
 .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@openbsd.org>
 .\"


@@ -16,13 +16,13 @@
 .\" TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
 .\" PERFORMANCE OF THIS SOFTWARE.
 .\" 
 .\" TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
 .\" PERFORMANCE OF THIS SOFTWARE.
 .\" 

-.Dd $Mdocdate: March 23 2009 $
-.Dt mdoc 7
+.Dd $Mdocdate: April 12 2009 $
+.Dt MDOC 7

 .Os
 .\" SECTION
 .Sh NAME
 .Nm mdoc
 .Os
 .\" SECTION
 .Sh NAME
 .Nm mdoc

-.Nd mdoc macro reference
+.Nd mdoc language reference

 .\" SECTION
 .Sh DESCRIPTION
 The
 .\" SECTION
 .Sh DESCRIPTION
 The


@@ -47,11 +47,6 @@ prior macros:
 \&.Sh Macro lines change control state.
 Other lines are interpreted within the current state.
 .Ed
 \&.Sh Macro lines change control state.
 Other lines are interpreted within the current state.
 .Ed

-.\" PARAGRAPH
-.Pp
-Macros are two- or three-character sequences whose scope rules, rules
-that dictate handling of subsequent-line or same-line arguments, are
-governed by one of five classifications described in this document.

 .\" SECTION
 .Sh INPUT ENCODING
 .Nm
 .\" SECTION
 .Sh INPUT ENCODING
 .Nm


@@ -66,18 +61,18 @@ line termination.
 .Pp
 The only time a blank line is acceptable is within
 the context of 
 .Pp
 The only time a blank line is acceptable is within
 the context of 

-.Sq \&Bd \-literal
+.Sq \&.Bd \-literal

 or
 or

-.Sq \&Bd \-unfilled .
+.Sq \&.Bd \-unfilled .

 .Pp
 Tab characters 
 .Pq \et
 are only acceptable when delimiting 
 .Pp
 Tab characters 
 .Pq \et
 are only acceptable when delimiting 

-.Sq \&Bl \-column 
+.Sq \&.Bl \-column 

 and in
 and in

-.Sq \&Bd \-literal
+.Sq \&.Bd \-literal

 or
 or

-.Sq \&Bd \-unfilled
+.Sq \&.Bd \-unfilled

 contexts.
 .\" SUB-SECTION
 .Ss Reserved Characters
 contexts.
 .\" SUB-SECTION
 .Ss Reserved Characters


@@ -115,7 +110,7 @@ or, if applicable, an appropriate escape-sequence used.
 .\" SUB-SECTION
 .Ss Special Characters
 Special character sequences begin with the escape character
 .\" 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
 followed by either an open-parenthesis 
 .Sq \&(
 for two-character sequences; an open-bracket


@@ -125,425 +120,10 @@ for n-character sequences (terminated at a close-bracket
 or a single one-character sequence.
 .Pp
 Characters may alternatively be escaped by a slash-asterisk,
 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.  
 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
-.It \\(r!
-.Pq upside-down exclamation
-.It \\(r?
-.Pq upside-down question
-.El
-.\" PARAGRAPH
-.Pp
-Enclosures:
-.Bl -tag -width 12n -offset "XXXX" -compact
-.It \\(lh
-.Pq left hand
-.It \\(rh
-.Pq right hand
-.It \\(Fo
-.Pq left guillemet
-.It \\(Fc
-.Pq right guillemet
-.It \\(fo
-.Pq left guilsing
-.It \\(fc
-.Pq right guilsing
-.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
-.It \\(Bq
-.Pq right low double-quote
-.It \\(bq
-.Pq right low 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 \\(es
-.Pq empty set
-.It \\(ca
-.Pq intersection
-.It \\(cu
-.Pq union
-.It \\(gr
-.Pq gradient
-.It \\(pd
-.Pq partial differential
-.It \\(ap
-.Pq similarity
-.It \\(=)
-.Pq proper superset
-.It \\((=
-.Pq proper subset
-.It \\(eq
-.Pq equals
-.It \\(di
-.Pq division
-.It \\(mu
-.Pq multiplication
-.It \\(pl
-.Pq addition
-.It \\(nm
-.Pq not element
-.It \\(mo
-.Pq element
-.It \\(Im
-.Pq imaginary
-.It \\(Re
-.Pq real
-.It \\(Ah
-.Pq aleph
-.It \\(te
-.Pq existential quantifier
-.It \\(fa
-.Pq universal quantifier
-.It \\(AN
-.Pq logical AND
-.It \\(OR
-.Pq logical OR
-.It \\(no
-.Pq logical NOT
-.It \\(st
-.Pq such that
-.It \\(tf
-.Pq therefore
-.It \\(~~
-.Pq approximate
-.It \\(~=
-.Pq approximately equals
-.It \\(=~
-.Pq congruent
-.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
-Ligatures:
-.Bl -tag -width 12n -offset "XXXX" -compact
-.It \\(ss
-.Pq German eszett
-.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 \\(ff
-.Pq ff ligature
-.It \\(fi
-.Pq fi ligature
-.It \\(fl
-.Pq fl ligature
-.It \\(Fi
-.Pq ffi ligature
-.It \\(Fl
-.Pq ffl ligature
-.El
-.\" PARAGRAPH
-.Pp
-Diacritics and letters:
-.Bl -tag -width 12n -offset "XXXX" -compact
-.It \\(ga
-.Pq grave accent
-.It \\(aa
-.Pq accute accent
-.It \\(a"
-.Pq umlaut accent
-.It \\(ad
-.Pq dieresis accent
-.It \\(a~
-.Pq tilde accent
-.It \\(a^
-.Pq circumflex accent
-.It \\(ac
-.Pq cedilla accent
-.It \\(ad
-.Pq dieresis accent
-.It \\(ah
-.Pq caron accent
-.It \\(ao
-.Pq ring accent
-.It \\(ho
-.Pq hook accent
-.It \\(ab
-.Pq breve accent
-.It \\(a-
-.Pq macron accent
-.It \\(-D
-.Pq upper-case eth
-.It \\(Sd
-.Pq lower-case eth
-.It \\(TP
-.Pq upper-case thorn
-.It \\(Tp
-.Pq lower-case thorn
-.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
-.It \\(^A
-.Pq upper-case circumflex A
-.It \\(^E
-.Pq upper-case circumflex E
-.It \\(^I
-.Pq upper-case circumflex I
-.It \\(^O
-.Pq upper-case circumflex O
-.It \\(^U
-.Pq upper-case circumflex U
-.It \\(^a
-.Pq lower-case circumflex a
-.It \\(^e
-.Pq lower-case circumflex e
-.It \\(^i
-.Pq lower-case circumflex i
-.It \\(^o
-.Pq lower-case circumflex o
-.It \\(^u
-.Pq lower-case circumflex u
-.It \\(,C
-.Pq upper-case cedilla C
-.It \\(,c
-.Pq lower-case cedilla c
-.It \\(/L
-.Pq upper-case stroke L
-.It \\(/l
-.Pq lower-case stroke l
-.It \\(/O
-.Pq upper-case stroke O
-.It \\(/o
-.Pq lower-case stroke o
-.It \\(oA
-.Pq upper-case ring A
-.It \\(oa
-.Pq lower-case ring a
-.El
-.\" PARAGRAPH
-.Pp
-Monetary:
-.Bl -tag -width 12n -offset "XXXX" -compact
-.It \\(Cs
-.Pq Scandinavian
-.It \\(Do
-.Pq dollar
-.It \\(Po
-.Pq pound
-.It \\(Ye
-.Pq yen
-.It \\(Fn
-.Pq florin
-.It \\(ct
-.Pq cent
-.El
-.\" PARAGRAPH
-.Pp
-Special symbols:
-.Bl -tag -width 12n -offset "XXXX" -compact
-.It \\(de
-.Pq degree
-.It \\(ps
-.Pq paragraph
-.It \\(sc
-.Pq section
-.It \\(dg
-.Pq dagger
-.It \\(dd
-.Pq double dagger
-.It \\(ci
-.Pq circle
-.It \\(ba
-.Pq bar
-.It \\(bb
-.Pq broken 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
 .\" SECTION

-.Sh ONTOLOGY
+.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
 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


@@ -630,8 +210,8 @@ subsequent tokens are interpreted as if the scope had just been opened.
 In other circumstances, scope is simply closed out.
 .\" SECTION
 .Sh SYNTAX
 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, 
 .Qq \-arg
 refers to the macro arguments (which may contain zero or more values).
 In these illustrations, 


@@ -689,7 +269,7 @@ This section contains a complete list of all
 .Nm
 macros, arranged ontologically.  A 
 .Qq callable
 .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
 .Qq parsable
 macro may be followed by further (ostensibly callable) macros.
 .\" SUB-SECTION


@@ -698,7 +278,7 @@ The head of these macros follows invocation; the body is the content of
 subsequent lines prior to closure.  None of these macros have tails;
 some 
 .Po
 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 ,
 .Sq \-hyphen , 
 .Sq \-dash ,
 .Sq \-enum ,


@@ -751,26 +331,28 @@ close at the invocation's end-of-line.
 .\" PARAGRAPH
 .Pp
 The
 .\" PARAGRAPH
 .Pp
 The

-.Sq \&Op
-may be broken by \&Oc as in the following example:
+.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
 .Bd -literal -offset XXXX
 \&.Oo
 \&.Op Fl a Oc
 .Ed
 .Pp
 In the above example, the scope of

-.Sq \&Op
+.Sq \&.Op

 is technically broken by 
 is technically broken by 

-.Sq \&Oc ,
+.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 
 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 
 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
 .Pp
 .Bl -column "MacroX" "CallableX" "ParsableX" "closed by XXXX" -compact -offset XXXX
 .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope


@@ -854,7 +436,7 @@ then the macro accepts an arbitrary number of arguments.
 .It \&.Bsx   Ta    Yes   Ta    Yes     Ta    n
 .It \&.Bx    Ta    Yes   Ta    Yes     Ta    n
 .It \&.Db    Ta    \&No  Ta    \&No    Ta    1
 .It \&.Bsx   Ta    Yes   Ta    Yes     Ta    n
 .It \&.Bx    Ta    Yes   Ta    Yes     Ta    n
 .It \&.Db    Ta    \&No  Ta    \&No    Ta    1

-.It \&.Em    Ta    Yes   Ta    Yes     Ta    n
+.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 \&.No    Ta    Yes   Ta    Yes     Ta    0
 .It \&.Fx    Ta    Yes   Ta    Yes     Ta    n
 .It \&.Ms    Ta    \&No  Ta    Yes     Ta    >0
 .It \&.No    Ta    Yes   Ta    Yes     Ta    0


@@ -882,11 +464,11 @@ then the macro accepts an arbitrary number of arguments.
 .El
 .Pp
 The
 .El
 .Pp
 The

-.Sq \&Ot ,
-.Sq \&Fr ,
-.Sq \&Es 
+.Sq \&.Ot ,
+.Sq \&.Fr ,
+.Sq \&.Es 

 and
 and

-.Sq \&En ,
+.Sq \&.En ,

 macros are obsolete.
 .\" SECTION
 .Sh COMPATIBILITY
 macros are obsolete.
 .\" SECTION
 .Sh COMPATIBILITY


@@ -899,55 +481,53 @@ compatibility with these systems.
 .Bl -dash -compact
 .\" LIST-ITEM
 .It
 .Bl -dash -compact
 .\" LIST-ITEM
 .It

-.Sq \&Fo
+.Sq \&.Fo

 and
 and

-.Sq \&St
+.Sq \&.St

 historically weren't always callable.  Both are now correctly callable.
 .\" LIST-ITEM
 .It
 historically weren't always callable.  Both are now correctly callable.
 .\" LIST-ITEM
 .It

-.Sq \&It \-nested
+.Sq \&.It \-nested

 is assumed for all lists: any list may be nested and
 .Sq \-enum
 lists will restart the sequence only for the sub-list.
 .\" LIST-ITEM
 .It
 is assumed for all lists: 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 
 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 (
 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 ,
+.Ns Sq \&.At ,
+.Sq \&.Bsx ,
+.Sq \&.Bx ,
+.Sq \&.Fx ,
+.Sq \&.Nx ,
+.Sq \&.Ox ,

 and
 and

-.Sq \&Ux )
+.Sq \&.Ux )

 are callable.
 .\" LIST-ITEM
 .It
 Some manuals use
 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
 incorrectly by following it with a reserved character and expecting the
 delimiter to render.  This is not supported.
 .\" LIST-ITEM
 .It

-.Sq \&Cd
+.Sq \&.Cd

 is callable.
 .El
 .\" SECTION
 .Sh SEE ALSO
 is callable.
 .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
 .\" SECTION
 .Sh AUTHORS
 The


@@ -961,64 +541,64 @@ There are several ambiguous parts of mdoc.
 .Bl -dash -compact
 .\" LIST-ITEM
 .It
 .Bl -dash -compact
 .\" LIST-ITEM
 .It

-.Sq \&Fa
+.Sq \&.Fa

 should be 
 should be 

-.Sq \&Va
+.Sq \&.Va

 as function arguments are variables.
 .\" LIST-ITEM
 .It
 as function arguments are variables.
 .\" LIST-ITEM
 .It

-.Sq \&Ft
+.Sq \&.Ft

 should be
 should be

-.Sq \&Vt
+.Sq \&.Vt

 as function return types are still types.  Furthermore, the
 as function return types are still types.  Furthermore, the

-.Sq \&Ft
+.Sq \&.Ft

 should be removed and
 should be removed and

-.Sq \&Fo ,
+.Sq \&.Fo ,

 which ostensibly follows it, should follow the same convention as
 which ostensibly follows it, should follow the same convention as

-.Sq \&Va .
+.Sq \&.Va .

 .\" LIST-ITEM
 .It
 .\" LIST-ITEM
 .It

-.Sq \&Va
+.Sq \&.Va

 should formalise that only one or two arguments are acceptable: a
 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
 .\" LIST-ITEM
 .It

-.Sq \&Fd
+.Sq \&.Fd

 is ambiguous.  It's commonly used to indicate an include file in the
 synopsis section.  
 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
 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 
 makes sense.  The remaining ones should be removed.
 .\" LIST-ITEM
 .It
 The 

-.Sq \&Xo
+.Sq \&.Xo

 and
 and

-.Sq \&Xc
+.Sq \&.Xc

 macros should be deprecated.
 .\" LIST-ITEM
 .It
 The
 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
 macro lacks clarity.  It should be absolutely clear which title will
 render when formatting the manual page.
 .\" LIST-ITEM
 .It
 A

-.Sq \&Lx
+.Sq \&.Lx

 should be provided for Linux (\(`a la 
 should be provided for Linux (\(`a la 

-.Sq \&Ox ,
-.Sq \&Nx 
+.Sq \&.Ox ,
+.Sq \&.Nx 

 etc.).
 .\" LIST-ITEM
 .It
 There's no way to refer to references in
 etc.).
 .\" LIST-ITEM
 .It
 There's no way to refer to references in

-.Sq \&Rs/Re
+.Sq \&.Rs/.Re

 blocks.
 .El
 blocks.
 .El