complete the sync to 1.9.15-pre2: mostly minor fixes

 * bugfix: do not restore TERMP flags when leaving lists, just reset them
 * and a few HTML fixes
 * clarity: return width from a2width, not width+2, and adapt to it
 * manual: document .Bl and .Fl
 * portability: no need to escape '%' in macro names

5 files changed, 220 insertions, 77 deletions

diff --git a/usr.bin/mandoc/Makefile b/usr.bin/mandoc/Makefile
index 28338b2380e..011bd7c4454 100644
--- a/usr.bin/mandoc/Makefile
+++ b/usr.bin/mandoc/Makefile
@@ -1,8 +1,8 @@
-#	$OpenBSD: Makefile,v 1.24 2009/12/24 02:08:14 schwarze Exp $
+#	$OpenBSD: Makefile,v 1.25 2010/01/02 02:42:06 schwarze Exp $
 
 .include <bsd.own.mk>
 
-VERSION=1.9.14
+VERSION=1.9.15
 CFLAGS+=-DVERSION=\"${VERSION}\"
 CFLAGS+=-W -Wall -Wstrict-prototypes
 .if ${USE_GCC3:L} != "no"
diff --git a/usr.bin/mandoc/mdoc.7 b/usr.bin/mandoc/mdoc.7
index 80d2eac2019..0f3840f72a0 100644
--- a/usr.bin/mandoc/mdoc.7
+++ b/usr.bin/mandoc/mdoc.7
@@ -1,4 +1,4 @@
-.\"	$Id: mdoc.7,v 1.20 2009/12/24 02:08:14 schwarze Exp $
+.\"	$Id: mdoc.7,v 1.21 2010/01/02 02:42:06 schwarze 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: December 24 2009 $
+.Dd $Mdocdate: January 2 2010 $
 .Dt MDOC 7
 .Os
 .
@@ -419,6 +419,11 @@ The
 macro(s) must precede the
 .Sx \&Nd
 macro.
+.Pp
+See 
+.Sx \&Nm
+and
+.Sx \&Nd .
 .
 .It Em LIBRARY
 The name of the library containing the documented material, which is
@@ -429,8 +434,7 @@ this is as follows:
 .Ed
 .Pp
 See
-.Sx \&Lb
-for details.
+.Sx \&Lb .
 .
 .It Em SYNOPSIS
 Documents the utility invocation syntax, function call syntax, or device
@@ -467,6 +471,14 @@ And for the third, configurations (section 4):
 .Pp
 Manuals not in these sections generally don't need a 
 .Em SYNOPSIS .
+.Pp
+See 
+.Sx \&Op ,
+.Sx \&Cd ,
+.Sx \&Fn ,
+.Sx \&Ft ,
+and
+.Sx \&Vt .
 .
 .It Em DESCRIPTION
 This expands upon the brief, one-line description in 
@@ -480,6 +492,7 @@ The arguments are as follows:
 Print verbose information.
 \&.El
 .Ed
+.Pp
 Manuals not documenting a command won't include the above fragment.
 .
 .It Em IMPLEMENTATION NOTES
@@ -535,7 +548,8 @@ for manuals in sections 1, 6, and 8; however, this practise is
 discouraged.
 .Pp
 See
-.Sx \&Bl No \-diag .
+.Sx \&Bl
+.Fl diag .
 .
 .It Em ERRORS
 Documents error handling in sections 2, 3, and 9.
@@ -1160,7 +1174,60 @@ and
 .Ss \&Bf
 .Ss \&Bk
 .Ss \&Bl
-.
+.\" Begins a list composed of one or more list entries.  A list entry is
+.\" specified by the
+.\" .Sx \&It
+.\" macro, which consists of a head and optional body.  By default, a list
+.\" is preceded by a blank line.  A list must specify one of the following
+.\" list types:
+.\" .Bl -tag -width 12n
+.\" .It Fl bullet
+.\" A list offset by a bullet.  The head of list entries must be empty.
+.\" List entry bodies are justified after the bullet.
+.\" .It Fl column
+.\" A columnated list.  The number of columns is specified as arguments to
+.\" the
+.\" .Sx \&Bl
+.\" macro (the deprecated form of following the invocation of
+.\" .Fl column
+.\" is also accepted).  Arguments dictate the width of columns specified in
+.\" list entries.  List entry bodies must be left empty.  Columns specified
+.\" in the list entry head are justified to their position in the sequence
+.\" of columns.
+.\" .It Fl dash
+.\" A list offset by a dash (hyphen).  The head of list entries must be
+.\" empty.  List entry bodies are justified past the dash.
+.\" .It Fl diag
+.\" Like
+.\" .Fl inset
+.\" lists, but with additional formatting to the head.
+.\" .It Fl enum
+.\" A list offset by a number indicating list entry position.  The head of
+.\" list entries must be empty.  List entry bodies are justified past the
+.\" enumeration.
+.\" .It Fl hang
+.\" Like
+.\" .Fl tag ,
+.\" but instead of list bodies justifying to the head on the first line,
+.\" they trail the head text.
+.\" .It Fl hyphen
+.\" Synonym for
+.\" .Fl dash .
+.\" .It Fl inset
+.\" Like
+.\" .Fl tag ,
+.\" but list entry bodies aren't justified.
+.\" .It Fl item
+.\" An un-justified list.  This produces blocks of text.
+.\" .It Fl ohang
+.\" List bodies are placed on the line following the head.
+.\" .It Fl tag
+.\" A list offset by list entry heads.  List entry bodies are justified
+.\" after the head.
+.\" .El
+.\" .Pp
+.\" More...
+.\" .
 .Ss \&Bo
 Begins a block enclosed by square brackets.  Does not have any head
 arguments.
@@ -1596,6 +1663,22 @@ is provided.
 .Ss \&Fc
 .Ss \&Fd
 .Ss \&Fl
+Command-line flag.  Used when listing arguments to command-line
+utilities.  Prints a fixed-width hyphen
+.Sq \-
+before each delimited argument.  If no arguments are provided, a hyphen
+is still printed.
+.Pp
+Examples:
+.Bd -literal -offset indent
+\&.Fl a b c
+\&.Fl
+\&.Op Fl o Ns Ar file
+.Ed
+.Pp
+See also
+.Sx \&Cm .
+.
 .Ss \&Fn
 .Ss \&Fo
 .Ss \&Fr
@@ -1830,6 +1913,23 @@ file re-write
 .Pp
 .Bl -dash -compact
 .It
+The comment syntax
+.Sq \e."
+is no longer accepted.
+.It
+In
+.Xr groff 1 ,
+the
+.Sx \&Pa
+macro does not format its arguments when used in the FILES section under
+certain list types.  This irregular behaviour has been discontinued.
+.It
+Historic 
+.Xr groff 1
+does not print a dash for empty 
+.Sx \&Fl
+arguments.  This behaviour has been discontinued.
+.It
 .Xr groff 1
 behaves strangely (even between versions) when specifying
 .Sq \ef
@@ -1839,7 +1939,7 @@ normalised.
 Negative scaling units are now truncated to zero instead of creating
 interesting conditions, such as with
 .Sx \&sp
-.Cm \-1i .
+.Fl 1i .
 Furthermore, the
 .Sq f
 scaling unit, while accepted, is rendered as the default unit.
diff --git a/usr.bin/mandoc/mdoc.c b/usr.bin/mandoc/mdoc.c
index ae69cb2f05c..e8eeed72a37 100644
--- a/usr.bin/mandoc/mdoc.c
+++ b/usr.bin/mandoc/mdoc.c
@@ -1,4 +1,4 @@
-/*	$Id: mdoc.c,v 1.32 2009/12/22 23:58:00 schwarze Exp $ */
+/*	$Id: mdoc.c,v 1.33 2010/01/02 02:42:06 schwarze Exp $ */
 /*
  * Copyright (c) 2008, 2009 Kristaps Dzonsons <kristaps@kth.se>
  *
@@ -93,11 +93,11 @@ const	char *const __mdoc_macronames[MDOC_MAX] = {
 	"Nm",		"Op",		"Ot",		"Pa",
 	"Rv",		"St",		"Va",		"Vt",
 	/* LINTED */
-	"Xr",		"\%A",		"\%B",		"\%D",
+	"Xr",		"%A",		"%B",		"%D",
 	/* LINTED */
-	"\%I",		"\%J",		"\%N",		"\%O",
+	"%I",		"%J",		"%N",		"%O",
 	/* LINTED */
-	"\%P",		"\%R",		"\%T",		"\%V",
+	"%P",		"%R",		"%T",		"%V",
 	"Ac",		"Ao",		"Aq",		"At",
 	"Bc",		"Bf",		"Bo",		"Bq",
 	"Bsx",		"Bx",		"Db",		"Dc",
@@ -114,11 +114,11 @@ const	char *const __mdoc_macronames[MDOC_MAX] = {
 	"Fr",		"Ud",		"Lb",		"Lp",
 	"Lk",		"Mt",		"Brq",		"Bro",
 	/* LINTED */
-	"Brc",		"\%C",		"Es",		"En",
+	"Brc",		"%C",		"Es",		"En",
 	/* LINTED */
-	"Dx",		"\%Q",		"br",		"sp",
+	"Dx",		"%Q",		"br",		"sp",
 	/* LINTED */
-	"\%U"
+	"%U"
 	};
 
 const	char *const __mdoc_argnames[MDOC_ARG_MAX] = {		 
@@ -148,7 +148,6 @@ static	int		  macrowarn(struct mdoc *, int, const char *);
 static	int		  pstring(struct mdoc *, int, int, 
 				const char *, size_t);
 
-
 const struct mdoc_node *
 mdoc_node(const struct mdoc *m)
 {
diff --git a/usr.bin/mandoc/mdoc_html.c b/usr.bin/mandoc/mdoc_html.c
index 24e549193bd..ca34fa46656 100644
--- a/usr.bin/mandoc/mdoc_html.c
+++ b/usr.bin/mandoc/mdoc_html.c
@@ -1,4 +1,4 @@
-/*	$Id: mdoc_html.c,v 1.5 2009/12/24 02:08:14 schwarze Exp $ */
+/*	$Id: mdoc_html.c,v 1.6 2010/01/02 02:42:06 schwarze Exp $ */
 /*
  * Copyright (c) 2008, 2009 Kristaps Dzonsons <kristaps@kth.se>
  *
@@ -15,7 +15,6 @@
  * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  */
 #include <sys/types.h>
-#include <sys/param.h>
 
 #include <assert.h>
 #include <ctype.h>
@@ -36,6 +35,10 @@
 			  const struct mdoc_node *n, \
 			  struct html *h
 
+#ifndef MIN
+#define	MIN(a,b)	((/*CONSTCOND*/(a)<(b))?(a):(b))
+#endif
+
 struct	htmlmdoc {
 	int		(*pre)(MDOC_ARGS);
 	void		(*post)(MDOC_ARGS);
@@ -656,10 +659,19 @@ mdoc_fl_pre(MDOC_ARGS)
 
 	PAIR_CLASS_INIT(&tag, "flag");
 	print_otag(h, TAG_SPAN, 1, &tag);
-	if (MDOC_Fl == n->tok) {
-		print_text(h, "\\-");
+
+	/* `Cm' has no leading hyphen. */
+
+	if (MDOC_Cm == n->tok)
+		return(1);
+
+	print_text(h, "\\-");
+
+	/* A blank `Fl' should incur a subsequent space. */
+
+	if (n->child)
 		h->flags |= HTML_NOSPACE;
-	}
+
 	return(1);
 }
 
@@ -1568,9 +1580,9 @@ mdoc_vt_pre(MDOC_ARGS)
 	struct roffsu	 su;
 
 	if (SEC_SYNOPSIS == n->sec) {
-		if (n->next && MDOC_Vt != n->next->tok) {
+		if (n->prev && MDOC_Vt != n->prev->tok) {
 			SCALE_VS_INIT(&su, 1);
-			bufcat_su(h, "margin-bottom", &su);
+			bufcat_su(h, "margin-top", &su);
 			PAIR_STYLE_INIT(&tag, h);
 			print_otag(h, TAG_DIV, 1, &tag);
 		} else
diff --git a/usr.bin/mandoc/mdoc_term.c b/usr.bin/mandoc/mdoc_term.c
index 9688fca09d3..b3e3f0116d1 100644
--- a/usr.bin/mandoc/mdoc_term.c
+++ b/usr.bin/mandoc/mdoc_term.c
@@ -1,4 +1,4 @@
-/*	$Id: mdoc_term.c,v 1.67 2010/01/01 23:28:03 schwarze Exp $ */
+/*	$Id: mdoc_term.c,v 1.68 2010/01/02 02:42:06 schwarze Exp $ */
 /*
  * Copyright (c) 2008, 2009 Kristaps Dzonsons <kristaps@kth.se>
  *
@@ -33,7 +33,6 @@
 
 struct	termpair {
 	struct termpair	 *ppair;
-	int	  	  flag;	
 	int		  count;
 };
 
@@ -466,12 +465,7 @@ a2width(const struct mdoc_argv *arg, int pos)
 	if ( ! a2roffsu(arg->value[pos], &su, SCALE_MAX))
 		SCALE_HS_INIT(&su, strlen(arg->value[pos]));
 
-	/*
-	 * This is a bit if a magic number on groff's part.  Be careful
-	 * in changing it, as the MDOC_Column handler will subtract one
-	 * from this for >5 columns (don't go below zero!).
-	 */
-	return(term_hspan(&su) + 2);
+	return(term_hspan(&su));
 }
 
 
@@ -536,6 +530,10 @@ a2offs(const struct mdoc_argv *arg)
 }
 
 
+/*
+ * Return 1 if an argument has a particular argument value or 0 if it
+ * does not.  See arg_getattr().
+ */
 static int
 arg_hasattr(int arg, const struct mdoc_node *n)
 {
@@ -544,6 +542,10 @@ arg_hasattr(int arg, const struct mdoc_node *n)
 }
 
 
+/*
+ * Get the index of an argument in a node's argument list or -1 if it
+ * does not exist.  See arg_getattrs().
+ */
 static int
 arg_getattr(int v, const struct mdoc_node *n)
 {
@@ -553,6 +555,12 @@ arg_getattr(int v, const struct mdoc_node *n)
 }
 
 
+/*
+ * Walk through the argument list for a node and fill an array "vals"
+ * with the positions of the argument structures listed in "keys".
+ * Return the number of elements that were written into "vals", which
+ * can be zero.
+ */
 static int
 arg_getattrs(const int *keys, int *vals, 
 		size_t sz, const struct mdoc_node *n)
@@ -572,6 +580,11 @@ arg_getattrs(const int *keys, int *vals,
 }
 
 
+/*
+ * Determine how much space to print out before block elements of `It'
+ * (and thus `Bl') and `Bd'.  And then go ahead and print that space,
+ * too.
+ */
 static void
 print_bvspace(struct termp *p, 
 		const struct mdoc_node *bl, 
@@ -650,8 +663,7 @@ termp_it_pre(DECL_ARGS)
 	const struct mdoc_node *bl, *nn;
 	char		        buf[7];
 	int		        i, type, keys[3], vals[3];
-	size_t		        width, offset, ncols;
-	int			dcol;
+	size_t		        width, offset, ncols, dcol;
 
 	if (MDOC_BLOCK == n->type) {
 		print_bvspace(p, n->parent->parent, n);
@@ -660,11 +672,7 @@ termp_it_pre(DECL_ARGS)
 
 	bl = n->parent->parent->parent;
 
-	/* Save parent attributes. */
-
-	pair->flag = p->flags;
-
-	/* Get list width and offset. */
+	/* Get list width, offset, and list type from argument list. */
 
 	keys[0] = MDOC_Width;
 	keys[1] = MDOC_Offset;
@@ -672,55 +680,71 @@ termp_it_pre(DECL_ARGS)
 
 	vals[0] = vals[1] = vals[2] = -1;
 
-	width = offset = 0;
-
-	(void)arg_getattrs(keys, vals, 3, bl);
+	arg_getattrs(keys, vals, 3, bl);
 
 	type = arg_listtype(bl);
 	assert(-1 != type);
 
+	/* 
+	 * First calculate width and offset.  This is pretty easy unless
+	 * we're a -column list, in which case all prior columns must
+	 * be accounted for.
+	 */
+
+	width = offset = 0;
+
 	if (vals[1] >= 0) 
 		offset = a2offs(&bl->args->argv[vals[1]]);
 
-	/* Calculate real width and offset. */
-
 	switch (type) {
 	case (MDOC_Column):
 		if (MDOC_BODY == n->type)
 			break;
-
 		/*
-		 * Imitate groff's column handling.
-		 * For each earlier column, add its width.
-		 * For less than 5 columns, add two more blanks per column.
-		 * For exactly 5 columns, add only one more blank per column.
-		 * For more than 5 columns, SUBTRACT one column.  We can
-		 * do this because a2width() pads exactly 2 spaces.
+		 * Imitate groff's column handling:
+		 * - For each earlier column, add its width.
+		 * - For less than 5 columns, add four more blanks per
+		 *   column.
+		 * - For exactly 5 columns, add three more blank per
+		 *   column.
+		 * - For more than 5 columns, add only one column.
 		 */
 		ncols = bl->args->argv[vals[2]].sz;
-		dcol = ncols < 5 ? 2 : ncols == 5 ? 1 : -1;
-		for (i=0, nn=n->prev; nn && i < (int)ncols; nn=nn->prev, i++)
-			offset += a2width(&bl->args->argv[vals[2]], i) + 
-				(size_t)dcol;
+		/* LINTED */
+		dcol = ncols < 5 ? 4 : ncols == 5 ? 3 : 1;
+
+		for (i = 0, nn = n->prev; 
+				nn && i < (int)ncols; 
+				nn = nn->prev, i++)
+			offset += dcol + a2width
+				(&bl->args->argv[vals[2]], i);
+
 
 		/*
-		 * Use the declared column widths,
-		 * extended as explained in the preceding paragraph.
+		 * When exceeding the declared number of columns, leave
+		 * the remaining widths at 0.  This will later be
+		 * adjusted to the default width of 10, or, for the last
+		 * column, stretched to the right margin.
 		 */
-		if (i < (int)ncols)
-			width = a2width(&bl->args->argv[vals[2]], i) + 
-				(size_t)dcol;
+		if (i >= (int)ncols)
+			break;
 
 		/*
-		 * When exceeding the declared number of columns,
-		 * leave the remaining widths at 0.
-		 * This will later be adjusted to the default width of 10,
-		 * or, for the last column, stretched to the right margin.
+		 * Use the declared column widths, extended as explained
+		 * in the preceding paragraph.
 		 */
+		width = a2width(&bl->args->argv[vals[2]], i) + dcol;
 		break;
 	default:
-		if (vals[0] >= 0) 
-			width = a2width(&bl->args->argv[vals[0]], 0);
+		if (vals[0] < 0) 
+			break;
+
+		/* 
+		 * Note: buffer the width by 2, which is groff's magic
+		 * number for buffering single arguments.  See the above
+		 * handling for column for how this changes.
+		 */
+		width = a2width(&bl->args->argv[vals[0]], 0) + 2;
 		break;
 	}
 
@@ -789,11 +813,10 @@ termp_it_pre(DECL_ARGS)
 	}
 
 	/*
-	 * Pad and break control.  This is the tricker part.  Lists with
-	 * set right-margins for the head get TERMP_NOBREAK because, if
-	 * they overrun the margin, they wrap to the new margin.
-	 * Correspondingly, the body for these types don't left-pad, as
-	 * the head will pad out to to the right.
+	 * Pad and break control.  This is the tricky part.  These flags
+	 * are documented in term_flushln() in term.c.  Note that we're
+	 * going to unset all of these flags in termp_it_post() when we
+	 * exit.
 	 */
 
 	switch (type) {
@@ -934,7 +957,7 @@ termp_it_pre(DECL_ARGS)
 			break;
 		case (MDOC_Enum):
 			(pair->ppair->ppair->count)++;
-			(void)snprintf(buf, sizeof(buf), "%d.", 
+			snprintf(buf, sizeof(buf), "%d.", 
 					pair->ppair->ppair->count);
 			term_word(p, buf);
 			break;
@@ -977,7 +1000,7 @@ termp_it_post(DECL_ARGS)
 {
 	int		   type;
 
-	if (MDOC_BODY != n->type && MDOC_HEAD != n->type)
+	if (MDOC_BLOCK == n->type)
 		return;
 
 	type = arg_listtype(n->parent->parent->parent);
@@ -1001,7 +1024,17 @@ termp_it_post(DECL_ARGS)
 		break;
 	}
 
-	p->flags = pair->flag;
+	/* 
+	 * Now that our output is flushed, we can reset our tags.  Since
+	 * only `It' sets these flags, we're free to assume that nobody
+	 * has munged them in the meanwhile.
+	 */
+
+	p->flags &= ~TERMP_DANGLE;
+	p->flags &= ~TERMP_NOBREAK;
+	p->flags &= ~TERMP_TWOSPACE;
+	p->flags &= ~TERMP_NOLPAD;
+	p->flags &= ~TERMP_HANG;
 }
 
 
@@ -1982,10 +2015,9 @@ termp_sm_pre(DECL_ARGS)
 {
 
 	assert(n->child && MDOC_TEXT == n->child->type);
-	if (0 == strcmp("on", n->child->string)) {
+	if (0 == strcmp("on", n->child->string))
 		p->flags &= ~TERMP_NONOSPACE;
-		p->flags &= ~TERMP_NOSPACE;
-	} else
+	else
 		p->flags |= TERMP_NONOSPACE;
 
 	return(0);