===================================================================
RCS file: /cvsrepo/anoncvs/cvs/src/usr.bin/mandoc/Attic/mdoc.7,v
retrieving revision 1.26
retrieving revision 1.27
diff -c -r1.26 -r1.27
*** src/usr.bin/mandoc/Attic/mdoc.7	2010/05/14 01:54:37	1.26
--- src/usr.bin/mandoc/Attic/mdoc.7	2010/05/14 14:47:44	1.27
***************
*** 1,4 ****
! .\"	$Id: mdoc.7,v 1.26 2010/05/14 01:54:37 schwarze Exp $
  .\"
  .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@bsd.lv>
  .\"
--- 1,4 ----
! .\"	$Id: mdoc.7,v 1.27 2010/05/14 14:47:44 schwarze Exp $
  .\"
  .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@bsd.lv>
  .\"
***************
*** 101,109 ****
  .Sq \&[
  for n-character sequences (terminated at a close-bracket
  .Sq \&] ) ;
! or a single one-character sequence.  See
  .Xr mandoc_char 7
! for a complete list.  Examples include
  .Sq \e(em
  .Pq em-dash
  and
--- 101,111 ----
  .Sq \&[
  for n-character sequences (terminated at a close-bracket
  .Sq \&] ) ;
! or a single one-character sequence.
! See
  .Xr mandoc_char 7
! for a complete list.
! Examples include
  .Sq \e(em
  .Pq em-dash
  and
***************
*** 118,131 ****
  .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.
--- 120,135 ----
  .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.
***************
*** 174,180 ****
  .Sq \e*[N] .
  See
  .Xr mandoc_char 7
! for a complete list.  Examples include
  .Sq \e*(Am
  .Pq ampersand
  and
--- 178,185 ----
  .Sq \e*[N] .
  See
  .Xr mandoc_char 7
! for a complete list.
! Examples include
  .Sq \e*(Am
  .Pq ampersand
  and
***************
*** 187,200 ****
  Blank free-form lines, which may include whitespace, are only permitted
  within literal contexts.
  .Pp
! In macro lines, whitespace delimits arguments and is discarded.  If
! arguments are quoted, whitespace within the quotes is retained.
  .Ss Quotation
  Macro arguments may be quoted with a double-quote to group
! space-delimited terms or to retain blocks of whitespace.  A quoted
! argument begins with a double-quote preceded by whitespace.  The next
! double-quote not pair-wise adjacent to another double-quote terminates
! the literal, regardless of surrounding whitespace.
  .Pp
  This produces tokens
  .Sq a" ,
--- 192,205 ----
  Blank free-form lines, which may include whitespace, are only permitted
  within literal contexts.
  .Pp
! In macro lines, whitespace delimits arguments and is discarded.
! If arguments are quoted, whitespace within the quotes is retained.
  .Ss Quotation
  Macro arguments may be quoted with a double-quote to group
! space-delimited terms or to retain blocks of whitespace.
! A quoted argument begins with a double-quote preceded by whitespace.
! The next double-quote not pair-wise adjacent to another double-quote
! terminates the literal, regardless of surrounding whitespace.
  .Pp
  This produces tokens
  .Sq a" ,
***************
*** 203,209 ****
  and
  .Sq fg" .
  Note that any quoted term, be it argument or macro, is indiscriminately
! considered literal text.  Thus, the following produces
  .Sq \&Em a :
  .Bd -literal -offset indent
  \&.Em "Em a"
--- 208,215 ----
  and
  .Sq fg" .
  Note that any quoted term, be it argument or macro, is indiscriminately
! considered literal text.
! Thus, the following produces
  .Sq \&Em a :
  .Bd -literal -offset indent
  \&.Em "Em a"
***************
*** 213,228 ****
  .Ss Dates
  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
--- 219,236 ----
  .Ss Dates
  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
***************
*** 246,253 ****
  The syntax for scaled widths is
  .Sq Li [+-]?[0-9]*.[0-9]*[:unit:] ,
  where a decimal must be preceded or proceeded by at least one digit.
! Negative numbers, while accepted, are truncated to zero.  The following
! scaling units are accepted:
  .Pp
  .Bl -tag -width Ds -offset indent -compact
  .It c
--- 254,261 ----
  The syntax for scaled widths is
  .Sq Li [+-]?[0-9]*.[0-9]*[:unit:] ,
  where a decimal must be preceded or proceeded by at least one digit.
! Negative numbers, while accepted, are truncated to zero.
! The following scaling units are accepted:
  .Pp
  .Bl -tag -width Ds -offset indent -compact
  .It c
***************
*** 285,291 ****
  .Sq u ,
  or
  .Sq v
! is necessarily non-portable across output media.  See
  .Sx COMPATIBILITY .
  .Sh MANUAL STRUCTURE
  A well-formed
--- 293,300 ----
  .Sq u ,
  or
  .Sq v
! is necessarily non-portable across output media.
! See
  .Sx COMPATIBILITY .
  .Sh MANUAL STRUCTURE
  A well-formed
***************
*** 334,346 ****
  \&.Nm
  utility processes files ...
  \&.\e\*q .Sh IMPLEMENTATION NOTES
- \&.\e\*q The next is for sections 1 & 8 only.
- \&.\e\*q .Sh EXIT STATUS
  \&.\e\*q The next is for sections 2, 3, & 9 only.
  \&.\e\*q .Sh RETURN VALUES
  \&.\e\*q The next is for sections 1, 6, 7, & 8 only.
  \&.\e\*q .Sh ENVIRONMENT
  \&.\e\*q .Sh FILES
  \&.\e\*q .Sh EXAMPLES
  \&.\e\*q The next is for sections 1, 4, 6, 7, & 8 only.
  \&.\e\*q .Sh DIAGNOSTICS
--- 343,355 ----
  \&.Nm
  utility processes files ...
  \&.\e\*q .Sh IMPLEMENTATION NOTES
  \&.\e\*q The next is for sections 2, 3, & 9 only.
  \&.\e\*q .Sh RETURN VALUES
  \&.\e\*q The next is for sections 1, 6, 7, & 8 only.
  \&.\e\*q .Sh ENVIRONMENT
  \&.\e\*q .Sh FILES
+ \&.\e\*q The next is for sections 1 & 8 only.
+ \&.\e\*q .Sh EXIT STATUS
  \&.\e\*q .Sh EXAMPLES
  \&.\e\*q The next is for sections 1, 4, 6, 7, & 8 only.
  \&.\e\*q .Sh DIAGNOSTICS
***************
*** 358,369 ****
  .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
--- 367,378 ----
  .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
***************
*** 383,390 ****
  .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
--- 392,399 ----
  .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
***************
*** 449,473 ****
  .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 .
--- 458,471 ----
  .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 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 .
***************
*** 478,494 ****
  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
--- 476,505 ----
  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 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 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
***************
*** 503,517 ****
  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
--- 514,529 ----
  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
***************
*** 539,553 ****
  Macros are one to three three characters in length and begin with a
  control character ,
  .Sq \&. ,
! at the beginning of the line.  An arbitrary amount of whitespace may
! sit between the control character and the macro name.  Thus, the
! following are equivalent:
  .Bd -literal -offset indent
  \&.Pp
  \&.\ \ \ \&Pp
  .Ed
  .Pp
! The syntax of a macro depends on its classification.  In this section,
  .Sq \-arg
  refers to macro arguments, which may be followed by zero or more
  .Sq parm
--- 551,567 ----
  Macros are one to three three characters in length and begin with a
  control character ,
  .Sq \&. ,
! at the beginning of the line.
! An arbitrary amount of whitespace may sit between the control character
! and the macro name.
! Thus, the following are equivalent:
  .Bd -literal -offset indent
  \&.Pp
  \&.\ \ \ \&Pp
  .Ed
  .Pp
! The syntax of a macro depends on its classification.
! In this section,
  .Sq \-arg
  refers to macro arguments, which may be followed by zero or more
  .Sq parm
***************
*** 560,567 ****
  The
  .Em Callable
  column indicates that the macro may be called subsequent to the initial
! line-macro.  If a macro is not callable, then its invocation after the
! initial line macro is interpreted as opaque text, such that
  .Sq \&.Fl \&Sh
  produces
  .Sq Fl \&Sh .
--- 574,582 ----
  The
  .Em Callable
  column indicates that the macro may be called subsequent to the initial
! line-macro.
! If a macro is not callable, then its invocation after the initial line
! macro is interpreted as opaque text, such that
  .Sq \&.Fl \&Sh
  produces
  .Sq Fl \&Sh .
***************
*** 569,583 ****
  The
  .Em Parsable
  column indicates whether the macro may be followed by further
! (ostensibly callable) macros.  If a macro is not parsable, subsequent
! macro invocations on the line will be interpreted as opaque text.
  .Pp
  The
  .Em Scope
  column, if applicable, describes closure rules.
  .Ss Block full-explicit
! Multi-line scope closed by an explicit closing macro.  All macros
! contains bodies; only
  .Sx \&Bf
  contains a head.
  .Bd -literal -offset indent
--- 584,599 ----
  The
  .Em Parsable
  column indicates whether the macro may be followed by further
! (ostensibly callable) macros.
! If a macro is not parsable, subsequent macro invocations on the line
! will be interpreted as opaque text.
  .Pp
  The
  .Em Scope
  column, if applicable, describes closure rules.
  .Ss Block full-explicit
! Multi-line scope closed by an explicit closing macro.
! All macros contains bodies; only
  .Sx \&Bf
  contains a head.
  .Bd -literal -offset indent
***************
*** 625,632 ****
  .It Sx \&Ss  Ta    \&No     Ta    \&No     Ta    closed by Sx \&Sh , Sx \&Ss
  .El
  .Ss Block partial-explicit
! Like block full-explicit, but also with single-line scope.  Each
! has at least a body and, in limited circumstances, a head
  .Po
  .Sx \&Fo ,
  .Sx \&Eo
--- 641,648 ----
  .It Sx \&Ss  Ta    \&No     Ta    \&No     Ta    closed by Sx \&Sh , Sx \&Ss
  .El
  .Ss Block partial-explicit
! Like block full-explicit, but also with single-line scope.
! Each has at least a body and, in limited circumstances, a head
  .Po
  .Sx \&Fo ,
  .Sx \&Eo
***************
*** 703,711 ****
  .Ss In-line
  Closed by
  .Sx Reserved Characters ,
! end of line, fixed argument lengths, and/or subsequent macros.  In-line
! macros have only text children.  If a number (or inequality) of
! arguments is
  .Pq n ,
  then the macro accepts an arbitrary number of arguments.
  .Bd -literal -offset indent
--- 719,727 ----
  .Ss In-line
  Closed by
  .Sx Reserved Characters ,
! end of line, fixed argument lengths, and/or subsequent macros.
! In-line macros have only text children.
! If a number (or inequality) of arguments is
  .Pq n ,
  then the macro accepts an arbitrary number of arguments.
  .Bd -literal -offset indent
***************
*** 795,801 ****
  .El
  .Sh REFERENCE
  This section is a canonical reference of all macros, arranged
! alphabetically.  For the scoping of individual macros, see
  .Sx MACRO SYNTAX .
  .Ss \&%A
  Author name of an
--- 811,818 ----
  .El
  .Sh REFERENCE
  This section is a canonical reference of all macros, arranged
! alphabetically.
! For the scoping of individual macros, see
  .Sx MACRO SYNTAX .
  .Ss \&%A
  Author name of an
***************
*** 876,883 ****
  .D1 \&.Ad [0,$]
  .D1 \&.Ad 0x00000000
  .Ss \&An
! Author name.  This macro may alternatively accepts the following
! arguments, although these may not be specified along with a parameter:
  .Bl -tag -width 12n -offset indent
  .It Fl split
  Renders a line break before each author listing.
--- 893,901 ----
  .D1 \&.Ad [0,$]
  .D1 \&.Ad 0x00000000
  .Ss \&An
! Author name.
! This macro may alternatively accepts the following arguments, although
! these may not be specified along with a parameter:
  .Bl -tag -width 12n -offset indent
  .It Fl split
  Renders a line break before each author listing.
***************
*** 888,897 ****
  .Pp
  In the AUTHORS section, the default is not to split the first author
  listing, but all subsequent author listings, whether or not they're
! interspersed by other macros or text, are split.  Thus, specifying
  .Fl split
! will cause the first listing also to be split.  If not in the AUTHORS
! section, the default is not to split.
  .Pp
  Examples:
  .D1 \&.An -nosplit
--- 906,916 ----
  .Pp
  In the AUTHORS section, the default is not to split the first author
  listing, but all subsequent author listings, whether or not they're
! interspersed by other macros or text, are split.
! Thus, specifying
  .Fl split
! will cause the first listing also to be split.
! If not in the AUTHORS section, the default is not to split.
  .Pp
  Examples:
  .D1 \&.An -nosplit
***************
*** 907,914 ****
  in the general document body, it must be re-specified in the AUTHORS
  section.
  .Ss \&Ao
! Begins a block enclosed by angled brackets.  Does not have any head
! arguments.
  .Pp
  Examples:
  .D1 \&.Fl -key= \&Ns \&Ao \&Ar val \&Ac
--- 926,933 ----
  in the general document body, it must be re-specified in the AUTHORS
  section.
  .Ss \&Ao
! Begins a block enclosed by angled brackets.
! Does not have any head arguments.
  .Pp
  Examples:
  .D1 \&.Fl -key= \&Ns \&Ao \&Ar val \&Ac
***************
*** 916,924 ****
  See also
  .Sx \&Aq .
  .Ss \&Ap
! Inserts an apostrophe without any surrounding white-space.  This is
! generally used as a grammatic device when referring to the verb form of
! a function:
  .Bd -literal -offset indent
  \&.Fn execve Ap d
  .Ed
--- 935,943 ----
  See also
  .Sx \&Aq .
  .Ss \&Ap
! Inserts an apostrophe without any surrounding white-space.
! This is generally used as a grammatic device when referring to the verb
! form of a function:
  .Bd -literal -offset indent
  \&.Fn execve Ap d
  .Ed
***************
*** 941,947 ****
  See also
  .Sx \&Ao .
  .Ss \&Ar
! Command arguments.  If an argument is not provided, the string
  .Dq file ...
  is used as a default.
  .Pp
--- 960,967 ----
  See also
  .Sx \&Ao .
  .Ss \&Ar
! Command arguments.
! If an argument is not provided, the string
  .Dq file ...
  is used as a default.
  .Pp
***************
*** 950,956 ****
  .D1 \&.Ar
  .D1 \&.Ar arg1 , arg2 .
  .Ss \&At
! Formats an AT&T version.  Accepts at most one parameter:
  .Bl -tag -width 12n -offset indent
  .It Cm v[1-7] | 32v
  A version of
--- 970,977 ----
  .D1 \&.Ar
  .D1 \&.Ar arg1 , arg2 .
  .Ss \&At
! Formats an AT&T version.
! Accepts at most one parameter:
  .Bl -tag -width 12n -offset indent
  .It Cm v[1-7] | 32v
  A version of
***************
*** 980,989 ****
  .Sx \&Bo
  block.  Does not have any tail arguments.
  .Ss \&Bd
! Begins a display block.  A display is collection of macros or text which
! may be collectively offset or justified in a manner different from that
! of the enclosing context.  By default, the block is preceded by a
! vertical space.
  .Pp
  Each display is associated with a type, which must be one of the
  following arguments:
--- 1001,1011 ----
  .Sx \&Bo
  block.  Does not have any tail arguments.
  .Ss \&Bd
! Begins a display block.
! A display is collection of macros or text which may be collectively
! offset or justified in a manner different from that
! of the enclosing context.
! By default, the block is preceded by a vertical space.
  .Pp
  Each display is associated with a type, which must be one of the
  following arguments:
***************
*** 1001,1007 ****
  Centre-justify each line.
  .El
  .Pp
! The type must be provided first.  Secondary arguments are as follows:
  .Bl -tag -width 12n -offset indent
  .It Fl offset Ar width
  Offset by the value of
--- 1023,1030 ----
  Centre-justify each line.
  .El
  .Pp
! The type must be provided first.
! Secondary arguments are as follows:
  .Bl -tag -width 12n -offset indent
  .It Fl offset Ar width
  Offset by the value of
***************
*** 1022,1029 ****
  .Ar center ,
  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 ,
  which resolves to
  .Ar 6n .
--- 1045,1052 ----
  .Ar center ,
  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 ,
  which resolves to
  .Ar 6n .
***************
*** 1115,1122 ****
  .\" More...
  .\" .
  .Ss \&Bo
! Begins a block enclosed by square brackets.  Does not have any head
! arguments.
  .Pp
  Examples:
  .Bd -literal -offset indent
--- 1138,1145 ----
  .\" More...
  .\" .
  .Ss \&Bo
! Begins a block enclosed by square brackets.
! Does not have any head arguments.
  .Pp
  Examples:
  .Bd -literal -offset indent
***************
*** 1147,1154 ****
  .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
--- 1170,1177 ----
  .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
***************
*** 1204,1210 ****
  and
  .Sx \&Ux .
  .Ss \&Cd
! Configuration declaration.  This denotes strings accepted by
  .Xr config 8 .
  .Pp
  Examples:
--- 1227,1234 ----
  and
  .Sx \&Ux .
  .Ss \&Cd
! Configuration declaration.
! This denotes strings accepted by
  .Xr config 8 .
  .Pp
  Examples:
***************
*** 1214,1223 ****
  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:
  .D1 \&.Cm ControlPath
--- 1238,1248 ----
  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:
  .D1 \&.Cm ControlPath
***************
*** 1226,1233 ****
  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:
  .D1 \&.D1 \&Fl abcdefgh
--- 1251,1260 ----
  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:
  .D1 \&.D1 \&Fl abcdefgh
***************
*** 1242,1250 ****
  .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
--- 1269,1279 ----
  .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
***************
*** 1268,1275 ****
  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:
  .D1 \&.Dl % mandoc mdoc.7 | less
--- 1297,1306 ----
  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:
  .D1 \&.Dl % mandoc mdoc.7 | less
***************
*** 1299,1317 ****
  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
--- 1330,1351 ----
  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
***************
*** 1377,1386 ****
  .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 ,
--- 1411,1423 ----
  .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 ,
***************
*** 1453,1461 ****
  .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:
  .D1 \&.Em Warnings!
--- 1490,1498 ----
  .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:
  .D1 \&.Em Warnings!
***************
*** 1480,1487 ****
  .D1 \&.Ev DISPLAY
  .D1 \&.Ev PATH
  .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 .
--- 1517,1524 ----
  .D1 \&.Ev DISPLAY
  .D1 \&.Ev PATH
  .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 .
***************
*** 1494,1505 ****
  .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
--- 1531,1544 ----
  .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
***************
*** 1537,1543 ****
  .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
--- 1576,1583 ----
  .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
***************
*** 1575,1581 ****
  .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:
--- 1615,1622 ----
  .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:
***************
*** 1584,1592 ****
  .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:
  .D1 \&.Os
--- 1625,1633 ----
  .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:
  .D1 \&.Os
***************
*** 1632,1643 ****
  .Ss \&Re
  Closes a
  .Sx \&Rs
! 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 may only
! contain
  .Sx \&%A ,
  .Sx \&%B ,
  .Sx \&%C ,
--- 1673,1686 ----
  .Ss \&Re
  Closes a
  .Sx \&Rs
! 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 may only contain
  .Sx \&%A ,
  .Sx \&%B ,
  .Sx \&%C ,
***************
*** 1684,1690 ****
  .Ss \&Tn
  .Ss \&Ud
  .Ss \&Ux
! Format the UNIX name.  Accepts no argument.
  .Pp
  Examples:
  .D1 \&.Ux
--- 1727,1734 ----
  .Ss \&Tn
  .Ss \&Ud
  .Ss \&Ux
! Format the UNIX name.
! Accepts no argument.
  .Pp
  Examples:
  .D1 \&.Ux
***************
*** 1700,1708 ****
  .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
--- 1744,1753 ----
  .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
***************
*** 1725,1733 ****
  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 .
--- 1770,1778 ----
  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 .
***************
*** 1739,1750 ****
  .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:
--- 1784,1796 ----
  .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:
***************
*** 1776,1800 ****
  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 not applicable in mandoc.
  .It
  Display types
  .Sx \&Bd
--- 1822,1850 ----
  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 not applicable in mandoc.
  .It
  Display types
  .Sx \&Bd
***************
*** 1805,1812 ****
  .Fl left
  in manodc.  Furthermore, the
  .Fl file Ar file
! argument is ignored.  Lastly, since text is not right-justified in
! mandoc (or even groff),
  .Fl ragged
  and
  .Fl filled
--- 1855,1862 ----
  .Fl left
  in manodc.  Furthermore, the
  .Fl file Ar file
! argument is ignored.
! Lastly, since text is not right-justified in mandoc (or even groff),
  .Fl ragged
  and
  .Fl filled
***************
*** 1815,1822 ****
  and
  .Fl unfilled .
  .It
! Historic groff has many un-callable macros.  Most of these (excluding
! some block-level macros) are now callable.
  .It
  The vertical bar
  .Sq \(ba
--- 1865,1872 ----
  and
  .Fl unfilled .
  .It
! Historic groff has many un-callable macros.
! Most of these (excluding some block-level macros) are now callable.
  .It
  The vertical bar
  .Sq \(ba
***************
*** 1833,1852 ****
  Some manuals use
  .Sx \&Li
  incorrectly by following it with a reserved character and expecting the
! delimiter to render.  This is not supported in mandoc.
  .It
  In groff, the
  .Sx \&Fo
! 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
  .Sh SEE ALSO
  .Xr mandoc 1 ,
--- 1883,1903 ----
  Some manuals use
  .Sx \&Li
  incorrectly by following it with a reserved character and expecting the
! delimiter to render.
! This is not supported in mandoc.
  .It
  In groff, the
  .Sx \&Fo
! 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
  .Sh SEE ALSO
  .Xr mandoc 1 ,