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.

4 files changed, 74 insertions, 58 deletions

diff --git a/index.sgml b/index.sgml
index 41e50fcf..cdb7832c 100644
--- a/index.sgml
+++ b/index.sgml
@@ -221,8 +221,10 @@
 							<TR>
 								<TD VALIGN="top"><SPAN CLASS="date">xx-03-2010</SPAN></TD>
 								<TD VALIGN="top">
-								Version <SPAN CLASS="rev">1.9.17</SPAN> highlights: accept <A
-								HREF="http://perldoc.perl.org/" CLASS="external">perlpod</A> macros.
+								Version <SPAN CLASS="rev">1.9.17</SPAN> highlights: accept all <A
+								HREF="http://perldoc.perl.org/" CLASS="external">perlpod</A> macros.  Also
+								accept and ignore <Q>de</Q>, <Q>dei</Q>, <Q>am</Q>, <Q>ami</Q>, and <Q>ig</Q>
+								roff macro blocks.
 								</TD>
 							</TR>
 							<TR>
@@ -254,7 +256,7 @@
 			<TR>
 				<TD>
 					<DIV CLASS="foot">
-						Copyright &#169; 2008&#8211;2010 Kristaps Dzonsons, $Date: 2010/03/23 13:53:51 $
+						Copyright &#169; 2008&#8211;2010 Kristaps Dzonsons, $Date: 2010/03/25 07:28:16 $
 					</DIV>
 				</TD>
 			</TR>
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
 .
 .
diff --git a/man_macro.c b/man_macro.c
index 5281a905..74b59980 100644
--- a/man_macro.c
+++ b/man_macro.c
@@ -1,4 +1,4 @@
-/*	$Id: man_macro.c,v 1.35 2010/03/24 20:10:53 kristaps Exp $ */
+/*	$Id: man_macro.c,v 1.36 2010/03/25 07:28:16 kristaps Exp $ */
 /*
  * Copyright (c) 2008, 2009 Kristaps Dzonsons <kristaps@kth.se>
  *
@@ -217,7 +217,11 @@ rew_scope(enum man_type type, struct man *m, enum mant tok)
 }
 
 
-/* ARGSUSED */
+/*
+ * Closure for dotted macros (de, dei, am, ami, ign).  This must handle
+ * any of these as the parent node, so it needs special handling.
+ * Beyond this, it's the same as blk_close().
+ */
 int
 blk_dotted(MACRO_PROT_ARGS)
 {
@@ -248,7 +252,9 @@ blk_dotted(MACRO_PROT_ARGS)
 }
 
 
-/* ARGSUSED */
+/*
+ * Close out a generic explicit macro.
+ */
 int
 blk_close(MACRO_PROT_ARGS)
 {
@@ -286,7 +292,6 @@ blk_exp(MACRO_PROT_ARGS)
 {
 	int		 w, la;
 	char		*p;
-	struct man_node	*n;
 
 	/* 
 	 * Close out prior scopes.  "Regular" explicit macros cannot be
@@ -306,8 +311,6 @@ blk_exp(MACRO_PROT_ARGS)
 	if ( ! man_head_alloc(m, line, ppos, tok))
 		return(0);
 
-	n = m->last;
-
 	for (;;) {
 		la = *pos;
 		w = man_args(m, line, pos, buf, &p);
diff --git a/mandoc.1 b/mandoc.1
index dc19d34b..d2025ebe 100644
--- a/mandoc.1
+++ b/mandoc.1
@@ -1,4 +1,4 @@
-.\"	$Id: mandoc.1,v 1.52 2010/03/22 20:43:00 kristaps Exp $
+.\"	$Id: mandoc.1,v 1.53 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 22 2010 $
+.Dd $Mdocdate: March 25 2010 $
 .Dt MANDOC 1
 .Os
 .
@@ -543,3 +543,10 @@ will confuse
 and
 .Fl T Ns Ar xhtml
 and cause them to forget the formatting of the prior next-line scope.
+.Pp
+The
+.Sq i
+macro in
+.Fl m Ns Ar an
+should italicise all subsequent text if a line argument is not provided.
+This behaviour is not implemented.