Removed lingering `Sp' reference (not -man).

[mandoc.git] / man.7

diff --git a/man.7 b/man.7
index c1eacb4eb6450e37f2ecb226386145674bc54722..10d5d086681b18daa524dfcb6ba3f3012a2bf51a 100644 (file)
--- a/man.7
+++ b/man.7
@@ -1,4 +1,4 @@
-.\"    $Id: man.7,v 1.57 2010/03/23 11:30:48 kristaps Exp $
+.\"    $Id: man.7,v 1.61 2010/04/05 07:25:23 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: March 23 2010 $
+.Dd $Mdocdate: April 5 2010 $
 .Dt MAN 7
 .Os
 .
@@ -403,9 +403,11 @@ Documents any security precautions that operators should consider.
 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:
+at the beginning of the line.  The
+.Sq \(aq
+macro control character is also accepted.  An arbitrary amount of
+whitespace (spaces or tabs) may sit between the control character and
+the macro name.  Thus, the following are equivalent:
 .Bd -literal -offset indent
 \&.PP
 \&.\ \ \ PP
@@ -438,7 +440,6 @@ If a next-line macro is followed by a non-next-line macro, an error is
 raised (unless in the case of
 .Sx \&br ,
 .Sx \&sp ,
-.Sx \&Sp ,
 or
 .Sx \&na ) .
 .Pp
@@ -458,14 +459,14 @@ The syntax is as follows:
 .It Sx \&I   Ta    n         Ta    next-line Ta    \&
 .It Sx \&IB  Ta    n         Ta    current   Ta    \&
 .It Sx \&IR  Ta    n         Ta    current   Ta    \&
-.It Sx \&PD  Ta    n         Ta    current   Ta    compat
+.\" .It Sx \&PD  Ta    n         Ta    current   Ta    compat
 .It Sx \&R   Ta    n         Ta    next-line Ta    \&
 .It Sx \&RB  Ta    n         Ta    current   Ta    \&
 .It Sx \&RI  Ta    n         Ta    current   Ta    \&
 .It Sx \&SB  Ta    n         Ta    next-line Ta    \&
 .It Sx \&SM  Ta    n         Ta    next-line Ta    \&
 .It Sx \&TH  Ta    >1, <6    Ta    current   Ta    \&
-.It Sx \&UC  Ta    n         Ta    current   Ta    compat
+.\" .It Sx \&UC  Ta    n         Ta    current   Ta    compat
 .It Sx \&br  Ta    0         Ta    current   Ta    compat
 .It Sx \&fi  Ta    0         Ta    current   Ta    compat
 .It Sx \&i   Ta    n         Ta    current   Ta    compat
@@ -473,9 +474,9 @@ The syntax is as follows:
 .It Sx \&nf  Ta    0         Ta    current   Ta    compat
 .It Sx \&r   Ta    0         Ta    current   Ta    compat
 .It Sx \&sp  Ta    1         Ta    current   Ta    compat
-.It Sx \&Sp  Ta    0         Ta    current   Ta    compat
-.It Sx \&Vb  Ta    <1        Ta    current   Ta    compat
-.It Sx \&Ve  Ta    0         Ta    current   Ta    compat
+.\" .It Sx \&Sp  Ta    0         Ta    current   Ta    compat
+.\" .It Sx \&Vb  Ta    <1        Ta    current   Ta    compat
+.\" .It Sx \&Ve  Ta    0         Ta    current   Ta    compat
 .El
 .
 .Pp
@@ -483,7 +484,9 @@ Macros marked as
 .Qq compat
 are included for compatibility with the significant corpus of existing
 manuals that mix dialects of roff.  These macros should not be used for
-portable manuals.
+portable
+.Nm
+manuals.
 .
 .
 .Ss Block Macros
@@ -519,6 +522,11 @@ or
 No closure refers to an explicit block closing macro.
 .
 .Pp
+As a rule, block macros may not be nested; thus, calling a block macro
+while another block macro scope is open, and the open scope is not
+implicitly closed, is syntactically incorrect.
+.
+.Pp
 .Bl -column -compact -offset indent "MacroX" "ArgumentsX" "Head ScopeX" "sub-sectionX" "compatX"
 .It Em Macro Ta Em Arguments Ta Em Head Scope Ta Em Body Scope  Ta Em Notes
 .It Sx \&HP  Ta    <2        Ta    current    Ta    paragraph   Ta    \&
@@ -896,14 +904,14 @@ See also
 .Sx \&P ,
 and
 .Sx \&PP .
-.
-.
-.Ss \&PD
-Has no effect.  Included for compatibility.
-.
-.
-.Ss \&UC
-Has no effect.  Included for compatibility.
+.\" .
+.\" .
+.\" .Ss \&PD
+.\" Has no effect.  Included for compatibility.
+.\" .
+.\" .
+.\" .Ss \&UC
+.\" Has no effect.  Included for compatibility.
 .
 .
 .Ss \&br
@@ -971,46 +979,54 @@ macro.  Defaults to 1, if unspecified.
 See also
 .Sx \&br .
 .
-.Ss \&Sp
-A synonym for
-.Sx \&sp
-.Cm 0.5v .
-.
-.Ss \&Vb
-A synonym for
-.Sx \&nf .
-Accepts an argument (the height of the formatted space) which is
-disregarded.
-.
-.Ss \&Ve
-A synonym for
-.Sx \&fi .
-.
+.\" .Ss \&Sp
+.\" A synonym for
+.\" .Sx \&sp
+.\" .Cm 0.5v .
+.\" .
+.\" .Ss \&Vb
+.\" A synonym for
+.\" .Sx \&nf .
+.\" Accepts an argument (the height of the formatted space) which is
+.\" disregarded.
+.\" .
+.\" .Ss \&Ve
+.\" A synonym for
+.\" .Sx \&fi .
+.\" .
 .
 .Sh COMPATIBILITY
-This section documents compatibility with other roff implementations, at
-this time limited to
-.Xr groff 1 .
+This section documents areas of questionable portability between
+implementations of the
+.Nm
+language.
+.
 .Pp
 .Bl -dash -compact
 .It
-The
-.Xr groff 1
-.Sx \&i
-macro will italicise all subsequent text if a line argument is not
-provided.  This behaviour is not implemented.
+In quoted literals, GNU troff allowed pair-wise double-quotes to produce
+a standalone double-quote in formatted output.  It is not known whether
+this behaviour is exhibited by other formatters.
+.
 .It
-In quoted literals, groff allowed pair-wise double-quotes to produce a
-standalone double-quote in formatted output.  This idiosyncratic
-behaviour is no longer applicable.
+Blocks of whitespace are stripped from macro and free-form text lines
+(except when in literal mode) in mandoc.  This is not the case for GNU
+troff: for maximum portability, whitespace sensitive blocks should be
+enclosed in literal contexts.
+.
 .It
 The
 .Sx \&sp
-macro does not accept negative numbers.
+macro does not accept negative values in mandoc.  In GNU troff, this
+would result in strange behaviour.
+.
 .It
-Blocks of whitespace are stripped from both macro and free-form text
-lines (except when in literal mode), while groff would retain whitespace
-in free-form text lines.
+The
+.Sq \(aq
+macro control character, in GNU troff (and prior troffs) suppresses a
+newline before macro output; in mandoc, it is an alias for the standard
+.Sq \&.
+control character.
 .El
 .
 .