Fixed up some documentation in man.7: only documenting man.7 macros, not related ones (de, Vb, etc.), which aren't technically man. It's an open question as to where these /should/ be documented, however.

1 files changed, 51 insertions, 47 deletions

diff --git a/man.7 b/man.7
index c1eacb4e..0f15f2f6 100644
--- 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.58 2010/03/25 07:28:16 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: March 25 2010 $
 .Dt MAN 7
 .Os
 .
@@ -458,14 +458,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 +473,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 +483,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 +521,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 +903,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 +978,43 @@ 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.
-.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.
+macro does not accept negative values in mandoc.  In GNU troff, this
+would result in strange behaviour.
 .El
 .
 .