===================================================================
RCS file: /cvs/mandoc/roff.c,v
retrieving revision 1.45
retrieving revision 1.55
diff -u -p -r1.45 -r1.55
--- mandoc/roff.c	2008/12/06 16:50:18	1.45
+++ mandoc/roff.c	2008/12/09 17:09:12	1.55
@@ -1,4 +1,4 @@
-/* $Id: roff.c,v 1.45 2008/12/06 16:50:18 kristaps Exp $ */
+/* $Id: roff.c,v 1.55 2008/12/09 17:09:12 kristaps Exp $ */
 /*
  * Copyright (c) 2008 Kristaps Dzonsons <kristaps@kth.se>
  *
@@ -28,28 +28,40 @@
 #include <string.h>
 #include <time.h>
 
-#include "libmdocml.h"
 #include "private.h"
 #include "roff.h"
 
 /* FIXME: First letters of quoted-text interpreted in rofffindtok. */
 /* FIXME: `No' not implemented. */
 /* TODO: warn if Pp occurs before/after Sh etc. (see mdoc.samples). */
-/* TODO: warn about "X section only" macros. */
 /* TODO: warn about empty lists. */
 /* TODO: (warn) some sections need specific elements. */
 /* TODO: (warn) NAME section has particular order. */
-/* TODO: unify empty-content tags a la <br />. */
 /* TODO: macros with a set number of arguments? */
 /* TODO: validate Dt macro arguments. */
 /* FIXME: Bl -diag supposed to ignore callable children. */
-/* FIXME: Nm has newline when used in NAME section. */
 
 struct	roffnode {
-	int		  tok;			/* Token id. */
-	struct roffnode	 *parent;		/* Parent (or NULL). */
+	int		  tok;		/* Token id. */
+	struct roffnode	 *parent;	/* Parent (or NULL). */
 };
 
+enum	rofferr {
+	ERR_ARGEQ1,			/* Macro requires arg == 1. */
+	ERR_ARGEQ0,			/* Macro requires arg == 0. */
+	ERR_ARGGE1,			/* Macro requires arg >= 1. */
+	ERR_ARGGE2,			/* Macro requires arg >= 2. */
+	ERR_ARGLEN,			/* Macro argument too long. */
+	ERR_BADARG,			/* Macro has bad arg. */
+	ERR_ARGMNY,			/* Too many macro arguments. */
+	ERR_NOTSUP,			/* Macro not supported. */
+	ERR_DEPREC,			/* Macro deprecated. */
+	ERR_PR_OOO,			/* Prelude macro bad order. */
+	ERR_PR_REP,			/* Prelude macro repeated. */
+	ERR_NOT_PR,			/* Not allowed in prelude. */
+	WRN_SECORD,			/* Sections out-of-order. */
+};
+
 struct	rofftree {
 	struct roffnode	 *last;			/* Last parsed node. */
 	char		 *cur;			/* Line start. */
@@ -57,29 +69,38 @@ struct	rofftree {
 	char		  name[64];		/* `Nm' results. */
 	char		  os[64];		/* `Os' results. */
 	char		  title[64];		/* `Dt' results. */
-	char		  section[64];		/* `Dt' results. */
+	enum roffmsec	  section;
 	char		  volume[64];		/* `Dt' results. */
 	int		  state;
-#define	ROFF_PRELUDE	 (1 << 1)		/* In roff prelude. */
+#define	ROFF_PRELUDE	 (1 << 1)		/* In roff prelude. */ /* FIXME: put into asec. */
 #define	ROFF_PRELUDE_Os	 (1 << 2)		/* `Os' is parsed. */
 #define	ROFF_PRELUDE_Dt	 (1 << 3)		/* `Dt' is parsed. */
 #define	ROFF_PRELUDE_Dd	 (1 << 4)		/* `Dd' is parsed. */
 #define	ROFF_BODY	 (1 << 5)		/* In roff body. */
 	struct roffcb	  cb;			/* Callbacks. */
 	void		 *arg;			/* Callbacks' arg. */
+	int		  csec;			/* Current section. */
+	int		  asec;			/* Thus-far sections. */
 };
 
 static	struct roffnode	 *roffnode_new(int, struct rofftree *);
 static	void		  roffnode_free(struct rofftree *);
-static	void		  roff_warn(const struct rofftree *, 
+static	int		  roff_warn(const struct rofftree *, 
 				const char *, char *, ...);
-static	void		  roff_err(const struct rofftree *, 
+static	int		  roff_warnp(const struct rofftree *, 
+				const char *, int, enum rofferr);
+static	int		  roff_err(const struct rofftree *, 
 				const char *, char *, ...);
+static	int		  roff_errp(const struct rofftree *, 
+				const char *, int, enum rofferr);
 static	int		  roffpurgepunct(struct rofftree *, char **);
 static	int		  roffscan(int, const int *);
 static	int		  rofffindtok(const char *);
 static	int		  rofffindarg(const char *);
 static	int		  rofffindcallable(const char *);
+static	int		  roffispunct(const char *);
+static	int		  roffchecksec(struct rofftree *, 
+				const char *, int);
 static	int		  roffargs(const struct rofftree *,
 				int, char *, char **);
 static	int		  roffargok(int, int);
@@ -88,11 +109,13 @@ static	int		  roffnextopt(const struct rofftree *,
 static	int		  roffparseopts(struct rofftree *, int, 
 				char ***, int *, char **);
 static	int		  roffcall(struct rofftree *, int, char **);
+static	int		  roffexit(struct rofftree *, int);
 static	int 		  roffparse(struct rofftree *, char *);
 static	int		  textparse(struct rofftree *, char *);
 static	int		  roffdata(struct rofftree *, int, char *);
 static	int		  roffspecial(struct rofftree *, int, 
-				const char *, size_t, char **);
+				const char *, const int *,
+				const char **, size_t, char **);
 static	int		  roffsetname(struct rofftree *, char **);
 
 #ifdef __linux__ 
@@ -118,21 +141,26 @@ roff_free(struct rofftree *tree, int flush)
 	error = 1;
 
 	if (ROFF_PRELUDE & tree->state) {
-		roff_err(tree, NULL, "prelude never finished");
+		(void)roff_err(tree, NULL, "prelude never finished");
 		goto end;
-	} 
+	} else if ( ! (ROFFSec_NAME & tree->asec)) {
+		(void)roff_err(tree, NULL, "missing `NAME' section");
+		goto end;
+	} else if ( ! (ROFFSec_NMASK & tree->asec))
+		(void)roff_warn(tree, NULL, "missing suggested `NAME', "
+				"`SYNOPSIS', `DESCRIPTION' sections");
 
 	for (n = tree->last; n; n = n->parent) {
 		if (0 != tokens[n->tok].ctx) 
 			continue;
-		roff_err(tree, NULL, "closing explicit scope `%s'", 
-				toknames[n->tok]);
+		(void)roff_err(tree, NULL, "closing explicit scope "
+				"`%s'", toknames[n->tok]);
 		goto end;
 	}
 
 	while (tree->last) {
 		t = tree->last->tok;
-		if ( ! (*tokens[t].cb)(t, tree, NULL, ROFF_EXIT))
+		if ( ! roffexit(tree, t))
 			goto end;
 	}
 
@@ -165,6 +193,7 @@ roff_alloc(const struct roffcb *cb, void *args)
 
 	tree->state = ROFF_PRELUDE;
 	tree->arg = args;
+	tree->section = ROFF_MSEC_MAX;
 
 	(void)memcpy(&tree->cb, cb, sizeof(struct roffcb));
 
@@ -179,10 +208,9 @@ roff_engine(struct rofftree *tree, char *buf)
 	tree->cur = buf;
 	assert(buf);
 
-	if (0 == *buf) {
-		roff_err(tree, buf, "blank line");
-		return(0);
-	} else if ('.' != *buf)
+	if (0 == *buf) 
+		return(roff_err(tree, buf, "blank line"));
+	else if ('.' != *buf)
 		return(textparse(tree, buf));
 
 	return(roffparse(tree, buf));
@@ -196,10 +224,8 @@ textparse(struct rofftree *tree, char *buf)
 
 	/* TODO: literal parsing. */
 
-	if ( ! (ROFF_BODY & tree->state)) {
-		roff_err(tree, buf, "data not in body");
-		return(0);
-	}
+	if ( ! (ROFF_BODY & tree->state))
+		return(roff_err(tree, buf, "data not in body"));
 
 	/* LINTED */
 	while (*buf) {
@@ -255,13 +281,9 @@ roffargs(const struct rofftree *tree, 
 			argv[i] = ++buf;
 			while (*buf && '\"' != *buf)
 				buf++;
-			if (0 == *buf) {
-				roff_err(tree, argv[i], "unclosed "
-						"quote in argument "
-						"list for `%s'", 
-						toknames[tok]);
-				return(0);
-			}
+			if (0 == *buf)
+				return(roff_err(tree, argv[i], 
+					"unclosed quote in arg list"));
 		} else { 
 			argv[i] = buf++;
 			while (*buf) {
@@ -284,11 +306,8 @@ roffargs(const struct rofftree *tree, 
 	}
 
 	assert(i > 0);
-	if (ROFF_MAXLINEARG == i && *buf) {
-		roff_err(tree, p, "too many arguments for `%s'", toknames
-				[tok]);
-		return(0);
-	}
+	if (ROFF_MAXLINEARG == i && *buf)
+		return(roff_err(tree, p, "too many args"));
 
 	argv[i] = NULL;
 	return(1);
@@ -322,19 +341,11 @@ roffparse(struct rofftree *tree, char *buf)
 		if (0 == strncmp(buf, ".\\\"", 3))
 			return(1);
 
-	if (ROFF_MAX == (tok = rofffindtok(buf + 1))) {
-		roff_err(tree, buf + 1, "bogus line macro");
+	if (ROFF_MAX == (tok = rofffindtok(buf + 1))) 
+		return(roff_err(tree, buf, "bogus line macro"));
+	else if ( ! roffargs(tree, tok, buf, argv)) 
 		return(0);
-	} else if (NULL == tokens[tok].cb) {
-		roff_err(tree, buf + 1, "unsupported macro `%s'", 
-				toknames[tok]);
-		return(0);
-	}
 
-	assert(ROFF___ != tok);
-	if ( ! roffargs(tree, tok, buf, argv)) 
-		return(0);
-
 	argvp = (char **)argv;
 
 	/* 
@@ -343,7 +354,7 @@ roffparse(struct rofftree *tree, char *buf)
 	
 	if (ROFF_PRELUDE & tree->state) {
 		assert(NULL == tree->last);
-		return((*tokens[tok].cb)(tok, tree, argvp, ROFF_ENTER));
+		return(roffcall(tree, tok, argvp));
 	} 
 
 	assert(ROFF_BODY & tree->state);
@@ -354,29 +365,25 @@ roffparse(struct rofftree *tree, char *buf)
 	 */
 
 	if (tree->last && ! roffscan
-			(tree->last->tok, tokens[tok].parents)) {
-		roff_err(tree, *argvp, "`%s' has invalid parent `%s'",
-				toknames[tok], 
-				toknames[tree->last->tok]);
-		return(0);
-	} 
+			(tree->last->tok, tokens[tok].parents))
+		return(roff_err(tree, *argvp, "`%s' has invalid "
+					"parent `%s'", toknames[tok], 
+					toknames[tree->last->tok]));
 
 	if (tree->last && ! roffscan
-			(tok, tokens[tree->last->tok].children)) {
-		roff_err(tree, *argvp, "`%s' is invalid child of `%s'",
-				toknames[tok],
-				toknames[tree->last->tok]);
-		return(0);
-	}
+			(tok, tokens[tree->last->tok].children))
+		return(roff_err(tree, *argvp, "`%s' has invalid "
+					"child `%s'", toknames[tok],
+					toknames[tree->last->tok]));
 
 	/*
 	 * Branch if we're not a layout token.
 	 */
 
 	if (ROFF_LAYOUT != tokens[tok].type)
-		return((*tokens[tok].cb)(tok, tree, argvp, ROFF_ENTER));
+		return(roffcall(tree, tok, argvp));
 	if (0 == tokens[tok].ctx)
-		return((*tokens[tok].cb)(tok, tree, argvp, ROFF_ENTER));
+		return(roffcall(tree, tok, argvp));
 
 	/*
 	 * First consider implicit-end tags, like as follows:
@@ -407,9 +414,10 @@ roffparse(struct rofftree *tree, char *buf)
 			}
 			if (tokens[n->tok].ctx == n->tok)
 				continue;
-			roff_err(tree, *argv, "`%s' breaks `%s' scope",
-					toknames[tok], toknames[n->tok]);
-			return(0);
+			return(roff_err(tree, *argv, "`%s' breaks "
+						"scope of prior`%s'",
+						toknames[tok], 
+						toknames[n->tok]));
 		}
 
 		/*
@@ -418,7 +426,7 @@ roffparse(struct rofftree *tree, char *buf)
 		 */
 
 		if (NULL == n)
-			return((*tokens[tok].cb)(tok, tree, argvp, ROFF_ENTER));
+			return(roffcall(tree, tok, argvp));
 
 		/* 
 		 * Close out all intermediary scoped blocks, then hang
@@ -427,11 +435,11 @@ roffparse(struct rofftree *tree, char *buf)
 
 		do {
 			t = tree->last->tok;
-			if ( ! (*tokens[t].cb)(t, tree, NULL, ROFF_EXIT))
+			if ( ! roffexit(tree, t))
 				return(0);
 		} while (t != tok);
 
-		return((*tokens[tok].cb)(tok, tree, argvp, ROFF_ENTER));
+		return(roffcall(tree, tok, argvp));
 	}
 
 	/*
@@ -450,24 +458,22 @@ roffparse(struct rofftree *tree, char *buf)
 		if (n->tok != tokens[tok].ctx) {
 			if (n->tok == tokens[n->tok].ctx)
 				continue;
-			roff_err(tree, *argv, "`%s' breaks `%s' scope",
-					toknames[tok], toknames[n->tok]);
-			return(0);
+			return(roff_err(tree, *argv, "`%s' breaks "
+						"scope of prior `%s'",
+						toknames[tok], 
+						toknames[n->tok]));
 		} else
 			break;
 
+	if (NULL == n)
+		return(roff_err(tree, *argv, "`%s' has no starting "
+					"tag `%s'", toknames[tok], 
+					toknames[tokens[tok].ctx]));
 
-	if (NULL == n) {
-		roff_err(tree, *argv, "`%s' has no starting tag `%s'",
-				toknames[tok], 
-				toknames[tokens[tok].ctx]);
-		return(0);
-	}
-
 	/* LINTED */
 	do {
 		t = tree->last->tok;
-		if ( ! (*tokens[t].cb)(t, tree, NULL, ROFF_EXIT))
+		if ( ! roffexit(tree, t))
 			return(0);
 	} while (t != tokens[tok].ctx);
 
@@ -519,6 +525,77 @@ rofffindtok(const char *buf)
 
 
 static int
+roffchecksec(struct rofftree *tree, const char *start, int sec)
+{
+	int		 prior;
+
+	switch (sec) {
+	case(ROFFSec_SYNOP):
+		if ((prior = ROFFSec_NAME) & tree->asec)
+			return(1);
+		break;
+	case(ROFFSec_DESC):
+		if ((prior = ROFFSec_SYNOP) & tree->asec)
+			return(1);
+		break;
+	case(ROFFSec_RETVAL):
+		if ((prior = ROFFSec_DESC) & tree->asec)
+			return(1);
+		break;
+	case(ROFFSec_ENV):
+		if ((prior = ROFFSec_RETVAL) & tree->asec)
+			return(1);
+		break;
+	case(ROFFSec_FILES):
+		if ((prior = ROFFSec_ENV) & tree->asec)
+			return(1);
+		break;
+	case(ROFFSec_EX):
+		if ((prior = ROFFSec_FILES) & tree->asec)
+			return(1);
+		break;
+	case(ROFFSec_DIAG):
+		if ((prior = ROFFSec_EX) & tree->asec)
+			return(1);
+		break;
+	case(ROFFSec_ERRS):
+		if ((prior = ROFFSec_DIAG) & tree->asec)
+			return(1);
+		break;
+	case(ROFFSec_SEEALSO):
+		if ((prior = ROFFSec_ERRS) & tree->asec)
+			return(1);
+		break;
+	case(ROFFSec_STAND):
+		if ((prior = ROFFSec_SEEALSO) & tree->asec)
+			return(1);
+		break;
+	case(ROFFSec_HIST):
+		if ((prior = ROFFSec_STAND) & tree->asec)
+			return(1);
+		break;
+	case(ROFFSec_AUTH):
+		if ((prior = ROFFSec_HIST) & tree->asec)
+			return(1);
+		break;
+	case(ROFFSec_CAVEATS):
+		if ((prior = ROFFSec_AUTH) & tree->asec)
+			return(1);
+		break;
+	case(ROFFSec_BUGS):
+		if ((prior = ROFFSec_CAVEATS) & tree->asec)
+			return(1);
+		break;
+	default:
+		return(1);
+	}
+
+	return(roff_warnp(tree, start, ROFF_Sh, WRN_SECORD));
+}
+
+
+/* FIXME: move this into literals.c (or similar). */
+static int
 roffispunct(const char *p)
 {
 
@@ -618,79 +695,114 @@ roffnode_free(struct rofftree *tree)
 
 
 static int
-roffspecial(struct rofftree *tree, int tok, 
-		const char *start, size_t sz, char **ordp)
+roffspecial(struct rofftree *tree, int tok, const char *start, 
+		const int *argc, const char **argv, 
+		size_t sz, char **ordp)
 {
 
 	switch (tok) {
+	case (ROFF_At):
+		if (0 == sz)
+			break;
+		if (ROFF_ATT_MAX == roff_att(*ordp))
+			break;
+		return(roff_errp(tree, *ordp, tok, ERR_BADARG));
+	
+	case (ROFF_Xr):
+		if (2 == sz) {
+			assert(ordp[1]);
+			if (ROFF_MSEC_MAX != roff_msec(ordp[1]))
+				break;
+			if ( ! roff_warn(tree, start, "invalid `%s' manual "
+						"section", toknames[tok]))
+				return(0);
+		}
+		/* FALLTHROUGH */
+
+	case (ROFF_Sx):
+		/* FALLTHROUGH*/
+	case (ROFF_Fn):
+		if (0 != sz) 
+			break;
+		return(roff_errp(tree, start, tok, ERR_ARGGE1));
+
 	case (ROFF_Nm):
 		if (0 == sz) {
-			if (0 == tree->name[0]) {
-				roff_err(tree, start, "`Nm' not set");
-				return(0);
+			if (0 != tree->name[0]) {
+				ordp[0] = tree->name;
+				ordp[1] = NULL;
+				break;
 			}
-			ordp[0] = tree->name;
-			ordp[1] = NULL;
+			return(roff_err(tree, start, "`Nm' not set"));
 		} else if ( ! roffsetname(tree, ordp))
 			return(0);
 		break;
 
+	case (ROFF_Rv):
+		/* FALLTHROUGH*/
 	case (ROFF_Ex):
-		if (0 == sz) {
-			roff_err(tree, start, "`Ex' expects an arg");
-			return(0);
-		} else if (1 != sz) {
-			roff_err(tree, start, "`Ex' expects one arg");
-			return(0);
-		}
-		break;
+		if (1 == sz) 
+			break;
+		return(roff_errp(tree, start, tok, ERR_ARGEQ1));
 
 	case (ROFF_Sm):
-		if (0 == sz) {
-			roff_err(tree, start, "`Sm' expects an arg");
-			return(0);
-		} else if (1 != sz) {
-			roff_err(tree, start, "`Sm' expects one arg");
-			return(0);
-		} 
-		
-		if (0 != strcmp(ordp[0], "on") &&
-				0 != strcmp(ordp[0], "off")) {
-			roff_err(tree, start, "`Sm' has invalid argument");
-			return(0);
-		}
-		break;
+		if (1 != sz)
+			return(roff_errp(tree, start, tok, ERR_ARGEQ1));
+		else if (0 == strcmp(ordp[0], "on") || 
+				0 == strcmp(ordp[0], "off"))
+			break;
+		return(roff_errp(tree, *ordp, tok, ERR_BADARG));
 	
 	case (ROFF_Ud):
 		/* FALLTHROUGH */
+	case (ROFF_Ux):
+		/* FALLTHROUGH */
 	case (ROFF_Bt):
-		if (0 != sz) {
-			roff_err(tree, start, "`%s' expects no args",
-					toknames[tok]);
-			return(0);
-		}
-		break;
+		if (0 == sz) 
+			break;
+		return(roff_errp(tree, start, tok, ERR_ARGEQ0));
 	default:
 		break;
 	}
 
-	return((*tree->cb.roffspecial)
-			(tree->arg, tok, tree->cur, ordp));
+	return((*tree->cb.roffspecial)(tree->arg, tok, tree->cur, 
+				argc, argv, (const char **)ordp));
 }
 
 
 static int
+roffexit(struct rofftree *tree, int tok)
+{
+
+	assert(tokens[tok].cb);
+	return((*tokens[tok].cb)(tok, tree, NULL, ROFF_EXIT));
+}
+
+
+static int
 roffcall(struct rofftree *tree, int tok, char **argv)
 {
+	int		 i;
+	enum roffmsec	 c;
 
-	if (NULL == tokens[tok].cb) {
-		roff_err(tree, *argv, "unsupported macro `%s'", 
-				toknames[tok]);
-		return(0);
+	if (NULL == tokens[tok].cb)
+		return(roff_errp(tree, *argv, tok, ERR_NOTSUP));
+
+	if (tokens[tok].sections && ROFF_MSEC_MAX != tree->section) {
+		i = 0;
+		while (ROFF_MSEC_MAX != 
+				(c = tokens[tok].sections[i++]))
+			if (c == tree->section)
+				break;
+		if (ROFF_MSEC_MAX == c) {
+			if ( ! roff_warn(tree, *argv, "`%s' is not a valid "
+					"macro in this manual section",
+					toknames[tok]))
+				return(0);
+		}
 	}
-	if ( ! (*tokens[tok].cb)(tok, tree, argv, ROFF_ENTER))
-		return(0);
-	return(1);
+
+	return((*tokens[tok].cb)(tok, tree, argv, ROFF_ENTER));
 }
 
 
@@ -711,14 +823,16 @@ roffnextopt(const struct rofftree *tree, int tok, 
 		return(-1);
 
 	if (ROFF_ARGMAX == (v = rofffindarg(arg + 1))) {
-		roff_warn(tree, arg, "argument-like parameter `%s' to "
-				"`%s'", arg, toknames[tok]);
+		if ( ! roff_warn(tree, arg, "argument-like parameter `%s' to "
+					"`%s'", arg, toknames[tok]))
+			return(ROFF_ARGMAX);
 		return(-1);
 	} 
 	
 	if ( ! roffargok(tok, v)) {
-		roff_warn(tree, arg, "invalid argument parameter `%s' to "
-				"`%s'", tokargnames[v], toknames[tok]);
+		if ( ! roff_warn(tree, arg, "invalid argument parameter `%s' to "
+				"`%s'", tokargnames[v], toknames[tok]))
+			return(ROFF_ARGMAX);
 		return(-1);
 	} 
 	
@@ -728,7 +842,7 @@ roffnextopt(const struct rofftree *tree, int tok, 
 	*in = ++argv;
 
 	if (NULL == *argv) {
-		roff_err(tree, arg, "empty value of `%s' for `%s'",
+		(void)roff_err(tree, arg, "empty value of `%s' for `%s'",
 				tokargnames[v], toknames[tok]);
 		return(ROFF_ARGMAX);
 	}
@@ -802,6 +916,7 @@ roff_Dd(ROFFCALL_ARGS)
 {
 	time_t		 t;
 	char		*p, buf[32];
+	size_t		 sz;
 
 	if (ROFF_BODY & tree->state) {
 		assert( ! (ROFF_PRELUDE & tree->state));
@@ -812,19 +927,22 @@ roff_Dd(ROFFCALL_ARGS)
 	assert(ROFF_PRELUDE & tree->state);
 	assert( ! (ROFF_BODY & tree->state));
 
-	if (ROFF_PRELUDE_Dd & tree->state) {
-		roff_err(tree, *argv, "repeated `Dd' in prelude");
-		return(0);
-	} else if (ROFF_PRELUDE_Dt & tree->state) {
-		roff_err(tree, *argv, "out-of-order `Dd' in prelude");
-		return(0);
-	}
+	if (ROFF_PRELUDE_Dd & tree->state)
+		return(roff_errp(tree, *argv, tok, ERR_PR_REP));
+	if (ROFF_PRELUDE_Dt & tree->state)
+		return(roff_errp(tree, *argv, tok, ERR_PR_OOO));
 
 	assert(NULL == tree->last);
 
 	argv++;
 
-	if (0 == strcmp(*argv, "$Mdocdate: December 6 2008 $")) {
+	/*
+	 * This is a bit complex because there are many forms the date
+	 * can be in:  it can be simply $Mdocdate: December 9 2008 $, $Mdocdate <date>$,
+	 * or a raw date.  Process accordingly.
+	 */
+
+	if (0 == strcmp(*argv, "$Mdocdate: December 9 2008 $")) {
 		t = time(NULL);
 		if (NULL == localtime_r(&t, &tree->tm))
 			err(1, "localtime_r");
@@ -832,49 +950,36 @@ roff_Dd(ROFFCALL_ARGS)
 		return(1);
 	} 
 
-	/* Build this from Mdocdate or raw date. */
-	
 	buf[0] = 0;
 	p = *argv;
+	sz = sizeof(buf);
 
 	if (0 != strcmp(*argv, "$Mdocdate:")) {
 		while (*argv) {
-			if (strlcat(buf, *argv++, sizeof(buf))
-					< sizeof(buf)) 
+			if (strlcat(buf, *argv++, sz) < sz)
 				continue;
-			roff_err(tree, p, "bad `Dd' date");
-			return(0);
+			return(roff_errp(tree, p, tok, ERR_BADARG));
 		}
 		if (strptime(buf, "%b%d,%Y", &tree->tm)) {
 			tree->state |= ROFF_PRELUDE_Dd;
 			return(1);
 		}
-		roff_err(tree, *argv, "bad `Dd' date");
-		return(0);
+		return(roff_errp(tree, p, tok, ERR_BADARG));
 	}
 
 	argv++;
+
 	while (*argv && **argv != '$') {
-		if (strlcat(buf, *argv++, sizeof(buf))
-				>= sizeof(buf)) {
-			roff_err(tree, p, "bad `Dd' Mdocdate");
-			return(0);
-		} 
-		if (strlcat(buf, " ", sizeof(buf))
-				>= sizeof(buf)) {
-			roff_err(tree, p, "bad `Dd' Mdocdate");
-			return(0);
-		}
+		if (strlcat(buf, *argv++, sz) >= sz)
+			return(roff_errp(tree, p, tok, ERR_BADARG));
+		if (strlcat(buf, " ", sz) >= sz) 
+			return(roff_errp(tree, p, tok, ERR_BADARG));
 	}
-	if (NULL == *argv) {
-		roff_err(tree, p, "bad `Dd' Mdocdate");
-		return(0);
-	}
 
-	if (NULL == strptime(buf, "%b %d %Y", &tree->tm)) {
-		roff_err(tree, *argv, "bad `Dd' Mdocdate");
-		return(0);
-	}
+	if (NULL == *argv) 
+		return(roff_errp(tree, p, tok, ERR_BADARG));
+	if (NULL == strptime(buf, "%b %d %Y", &tree->tm)) 
+		return(roff_errp(tree, p, tok, ERR_BADARG));
 
 	tree->state |= ROFF_PRELUDE_Dd;
 	return(1);
@@ -885,6 +990,7 @@ roff_Dd(ROFFCALL_ARGS)
 static	int
 roff_Dt(ROFFCALL_ARGS)
 {
+	size_t		 sz;
 
 	if (ROFF_BODY & tree->state) {
 		assert( ! (ROFF_PRELUDE & tree->state));
@@ -895,42 +1001,33 @@ roff_Dt(ROFFCALL_ARGS)
 	assert(ROFF_PRELUDE & tree->state);
 	assert( ! (ROFF_BODY & tree->state));
 
-	if ( ! (ROFF_PRELUDE_Dd & tree->state)) {
-		roff_err(tree, *argv, "out-of-order `Dt' in prelude");
-		return(0);
-	} else if (ROFF_PRELUDE_Dt & tree->state) {
-		roff_err(tree, *argv, "repeated `Dt' in prelude");
-		return(0);
-	}
+	if ( ! (ROFF_PRELUDE_Dd & tree->state))
+		return(roff_errp(tree, *argv, tok, ERR_PR_OOO));
+	if (ROFF_PRELUDE_Dt & tree->state)
+		return(roff_errp(tree, *argv, tok, ERR_PR_REP));
 
 	argv++;
-	if (NULL == *argv) {
-		roff_err(tree, *argv, "`Dt' needs document title");
-		return(0);
-	} else if (strlcpy(tree->title, *argv, sizeof(tree->title))
-			>= sizeof(tree->title)) {
-		roff_err(tree, *argv, "`Dt' document title too long");
-		return(0);
-	}
+	sz = sizeof(tree->title);
 
+	if (NULL == *argv) 
+		return(roff_errp(tree, *argv, tok, ERR_ARGGE2));
+	if (strlcpy(tree->title, *argv, sz) >= sz)
+		return(roff_errp(tree, *argv, tok, ERR_ARGLEN));
+
 	argv++;
-	if (NULL == *argv) {
-		roff_err(tree, *argv, "`Dt' needs section");
-		return(0);
-	} else if (strlcpy(tree->section, *argv, sizeof(tree->section))
-			>= sizeof(tree->section)) {
-		roff_err(tree, *argv, "`Dt' section too long");
-		return(0);
-	}
+	if (NULL == *argv)
+		return(roff_errp(tree, *argv, tok, ERR_ARGGE2));
 
+	if (ROFF_MSEC_MAX == (tree->section = roff_msec(*argv)))
+		return(roff_errp(tree, *argv, tok, ERR_BADARG));
+
 	argv++;
+	sz = sizeof(tree->volume);
+
 	if (NULL == *argv) {
 		tree->volume[0] = 0;
-	} else if (strlcpy(tree->volume, *argv, sizeof(tree->volume))
-			>= sizeof(tree->volume)) {
-		roff_err(tree, *argv, "`Dt' volume too long");
-		return(0);
-	}
+	} else if (strlcpy(tree->volume, *argv, sz) >= sz)
+		return(roff_errp(tree, *argv, tok, ERR_ARGLEN));
 
 	assert(NULL == tree->last);
 	tree->state |= ROFF_PRELUDE_Dt;
@@ -942,40 +1039,24 @@ roff_Dt(ROFFCALL_ARGS)
 static int
 roffsetname(struct rofftree *tree, char **ordp)
 {
+	size_t		 sz;
 	
 	assert(*ordp);
 
 	/* FIXME: not all sections can set this. */
 
-	if (NULL != *(ordp + 1)) {
-		roff_err(tree, *ordp, "too many `Nm' args");
-		return(0);
-	} 
+	if (NULL != *(ordp + 1))
+		return(roff_errp(tree, *ordp, ROFF_Nm, ERR_ARGMNY));
 	
-	if (strlcpy(tree->name, *ordp, sizeof(tree->name)) 
-			>= sizeof(tree->name)) {
-		roff_err(tree, *ordp, "`Nm' arg too long");
-		return(0);
-	}
+	sz = sizeof(tree->name);
+	if (strlcpy(tree->name, *ordp, sz) >= sz)
+		return(roff_errp(tree, *ordp, ROFF_Nm, ERR_ARGLEN));
 
 	return(1);
 }
 
 
 /* ARGSUSED */
-static int
-roff_Sm(ROFFCALL_ARGS)
-{
-	char		*ordp[1], *p;
-
-	p = *argv++;
-	*ordp = *argv;
-
-	return(roffspecial(tree, tok, p, *ordp ? 1 : 0, ordp));
-}
-
-
-/* ARGSUSED */
 static	int
 roff_Ns(ROFFCALL_ARGS)
 {
@@ -985,7 +1066,7 @@ roff_Ns(ROFFCALL_ARGS)
 	first = (*argv++ == tree->cur);
 	morep[0] = NULL;
 
-	if ( ! roffspecial(tree, tok, *argv, 0, morep))
+	if ( ! roffspecial(tree, tok, *argv, NULL, NULL, 0, morep))
 		return(0);
 
 	while (*argv) {
@@ -1026,6 +1107,7 @@ static	int
 roff_Os(ROFFCALL_ARGS)
 {
 	char		*p;
+	size_t		 sz;
 
 	if (ROFF_BODY & tree->state) {
 		assert( ! (ROFF_PRELUDE & tree->state));
@@ -1035,39 +1117,35 @@ roff_Os(ROFFCALL_ARGS)
 
 	assert(ROFF_PRELUDE & tree->state);
 	if ( ! (ROFF_PRELUDE_Dt & tree->state) ||
-			! (ROFF_PRELUDE_Dd & tree->state)) {
-		roff_err(tree, *argv, "out-of-order `Os' in prelude");
-		return(0);
-	}
+			! (ROFF_PRELUDE_Dd & tree->state)) 
+		return(roff_errp(tree, *argv, tok, ERR_PR_OOO));
 
 	tree->os[0] = 0;
 
 	p = *++argv;
+	sz = sizeof(tree->os);
 
-	while (*argv) {
-		if (strlcat(tree->os, *argv++, sizeof(tree->os))
-				< sizeof(tree->os)) 
-			continue;
-		roff_err(tree, p, "`Os' value too long");
-		return(0);
-	}
+	while (*argv)
+		if (strlcat(tree->os, *argv++, sz) >= sz)
+			return(roff_errp(tree, p, tok, ERR_ARGLEN));
 
 	if (0 == tree->os[0])
-		if (strlcpy(tree->os, "LOCAL", sizeof(tree->os))
-				>= sizeof(tree->os)) {
-			roff_err(tree, p, "`Os' value too long");
-			return(0);
-		}
+		if (strlcpy(tree->os, "LOCAL", sz) >= sz)
+			return(roff_errp(tree, p, tok, ERR_ARGLEN));
 
 	tree->state |= ROFF_PRELUDE_Os;
 	tree->state &= ~ROFF_PRELUDE;
 	tree->state |= ROFF_BODY;
 
+	assert(ROFF_MSEC_MAX != tree->section);
+	assert(0 != tree->title[0]);
+	assert(0 != tree->os[0]);
+
 	assert(NULL == tree->last);
 
 	return((*tree->cb.roffhead)(tree->arg, &tree->tm,
-				tree->os, tree->title, tree->section,
-				tree->volume));
+				tree->os, tree->title, 
+				tree->section, tree->volume));
 }
 
 
@@ -1076,13 +1154,26 @@ static int
 roff_layout(ROFFCALL_ARGS) 
 {
 	int		 i, c, argcp[ROFF_MAXLINEARG];
-	char		*argvp[ROFF_MAXLINEARG];
+	char		*argvp[ROFF_MAXLINEARG], *p;
 
-	if (ROFF_PRELUDE & tree->state) {
-		roff_err(tree, *argv, "bad `%s' in prelude", 
-				toknames[tok]);
-		return(0);
-	} else if (ROFF_EXIT == type) {
+	/*
+	 * The roff_layout function is for multi-line macros.  A layout
+	 * has a start and end point, which is either declared
+	 * explicitly or implicitly.  An explicit start and end is
+	 * embodied by `.Bl' and `.El', with the former being the start
+	 * and the latter being an end.  The `.Sh' and `.Ss' tags, on
+	 * the other hand, are implicit.  The scope of a layout is the
+	 * space between start and end.  Explicit layouts may not close
+	 * out implicit ones and vice versa; implicit layouts may close
+	 * out other implicit layouts.
+	 */
+
+	assert( ! (ROFF_CALLABLE & tokens[tok].flags));
+
+	if (ROFF_PRELUDE & tree->state)
+		return(roff_errp(tree, *argv, tok, ERR_NOT_PR));
+
+	if (ROFF_EXIT == type) {
 		roffnode_free(tree);
 		if ( ! (*tree->cb.roffblkbodyout)(tree->arg, tok))
 			return(0);
@@ -1091,7 +1182,7 @@ roff_layout(ROFFCALL_ARGS) 
 
 	assert( ! (ROFF_CALLABLE & tokens[tok].flags));
 
-	++argv;
+	p = *argv++;
 
 	if ( ! roffparseopts(tree, tok, &argv, argcp, argvp))
 		return(0);
@@ -1102,15 +1193,65 @@ roff_layout(ROFFCALL_ARGS) 
 	 * Layouts have two parts: the layout body and header.  The
 	 * layout header is the trailing text of the line macro, while
 	 * the layout body is everything following until termination.
+	 * Example:
+	 *
+	 * .It Fl f ) ;
+	 * Bar.
+	 *
+	 * ...Produces...
+	 *
+	 * <block>
+	 * 	<head>
+	 * 		<!Fl f!> ;
+	 * 	</head>
+	 * 	
+	 *	<body>
+	 *		Bar.
+	 *	</body>
+	 * </block>
 	 */
 
-	if ( ! (*tree->cb.roffblkin)(tree->arg, tok, argcp, argvp))
+	if ( ! (*tree->cb.roffblkin)(tree->arg, tok, argcp, 
+				(const char **)argvp))
 		return(0);
+
+	/* +++ Begin run macro-specific hooks over argv. */
+
+	switch (tok) {
+	case (ROFF_Sh):
+		if (NULL == *argv) {
+			argv--;
+			return(roff_errp(tree, *argv, tok, ERR_ARGGE1));
+		}
+
+		tree->csec = roff_sec((const char **)argv);
+
+		if ( ! (ROFFSec_OTHER & tree->csec) &&
+				tree->asec & tree->csec) 
+			if ( ! roff_warn(tree, *argv, "section repeated"))
+				return(0);
+
+		if (0 == tree->asec && ! (ROFFSec_NAME & tree->csec))
+			return(roff_err(tree, *argv, "`NAME' section "
+						"must be first"));
+		if ( ! roffchecksec(tree, *argv, tree->csec))
+			return(0);
+
+		tree->asec |= tree->csec;
+		break;
+	default:
+		break;
+	}
+
+	/* --- End run macro-specific hooks over argv. */
+
 	if (NULL == *argv)
 		return((*tree->cb.roffblkbodyin)
-				(tree->arg, tok, argcp, argvp));
+				(tree->arg, tok, argcp, 
+				 (const char **)argvp));
 
-	if ( ! (*tree->cb.roffblkheadin)(tree->arg, tok, argcp, argvp))
+	if ( ! (*tree->cb.roffblkheadin)(tree->arg, tok, argcp, 
+				(const char **)argvp))
 		return(0);
 
 	/*
@@ -1126,8 +1267,8 @@ roff_layout(ROFFCALL_ARGS) 
 
 		if ( ! (*tree->cb.roffblkheadout)(tree->arg, tok))
 			return(0);
-		return((*tree->cb.roffblkbodyin)
-				(tree->arg, tok, argcp, argvp));
+		return((*tree->cb.roffblkbodyin)(tree->arg, tok, argcp,
+				 (const char **)argvp));
 	}
 
 	/*
@@ -1158,7 +1299,8 @@ roff_layout(ROFFCALL_ARGS) 
 		if ( ! (*tree->cb.roffblkheadout)(tree->arg, tok))
 			return(0);
 		return((*tree->cb.roffblkbodyin)
-				(tree->arg, tok, argcp, argvp));
+				(tree->arg, tok, argcp, 
+				 (const char **)argvp));
 	}
 
 	/*
@@ -1168,11 +1310,10 @@ roff_layout(ROFFCALL_ARGS) 
 
 	if ( ! roffpurgepunct(tree, argv))
 		return(0);
-
 	if ( ! (*tree->cb.roffblkheadout)(tree->arg, tok))
 		return(0);
-	return((*tree->cb.roffblkbodyin)
-			(tree->arg, tok, argcp, argvp));
+	return((*tree->cb.roffblkbodyin)(tree->arg, 
+				tok, argcp, (const char **)argvp));
 }
 
 
@@ -1184,24 +1325,34 @@ roff_ordered(ROFFCALL_ARGS) 
 	char		*ordp[ROFF_MAXLINEARG], *p,
 			*argvp[ROFF_MAXLINEARG];
 
-	if (ROFF_PRELUDE & tree->state) {
-		roff_err(tree, *argv, "`%s' disallowed in prelude", 
-				toknames[tok]);
-		return(0);
-	}
+	/*
+	 * Ordered macros pass their arguments directly to handlers,
+	 * instead of considering it free-form text.  Thus, the
+	 * following macro looks as follows:
+	 *
+	 * .Xr foo 1 ) ,
+	 *
+	 * .Xr arg1 arg2 punctuation
+	 */
 
+	if (ROFF_PRELUDE & tree->state)
+		return(roff_errp(tree, *argv, tok, ERR_NOT_PR));
+
 	first = (*argv == tree->cur);
 	p = *argv++;
+	ordp[0] = NULL;
 
 	if ( ! roffparseopts(tree, tok, &argv, argcp, argvp))
 		return(0);
 
 	if (NULL == *argv)
-		return(roffspecial(tree, tok, p, 0, ordp));
+		return(roffspecial(tree, tok, p, argcp, 
+					(const char **)argvp, 0, ordp));
 
 	i = 0;
 	while (*argv && i < ROFF_MAXLINEARG) {
-		c = rofffindcallable(*argv);
+		c = ROFF_PARSED & tokens[tok].flags ?
+			rofffindcallable(*argv) : ROFF_MAX;
 
 		if (ROFF_MAX == c && ! roffispunct(*argv)) {
 			ordp[i++] = *argv++;
@@ -1212,16 +1363,20 @@ roff_ordered(ROFFCALL_ARGS) 
 		if (ROFF_MAX == c)
 			break;
 
-		if ( ! roffspecial(tree, tok, p, (size_t)i, ordp))
+		if ( ! roffspecial(tree, tok, p, argcp, 
+					(const char **)argvp,
+					(size_t)i, ordp))
 			return(0);
 
-		return(roffcall(tree, c, ordp));
+		return(roffcall(tree, c, argv));
 	}
 
 	assert(i != ROFF_MAXLINEARG);
 	ordp[i] = NULL;
 
-	if ( ! roffspecial(tree, tok, p, (size_t)i, ordp))
+	if ( ! roffspecial(tree, tok, p, argcp, 
+				(const char**)argvp,
+				(size_t)i, ordp))
 		return(0);
 
 	/* FIXME: error if there's stuff after the punctuation. */
@@ -1240,18 +1395,28 @@ roff_text(ROFFCALL_ARGS) 
 	int		 i, j, first, c, argcp[ROFF_MAXLINEARG];
 	char		*argvp[ROFF_MAXLINEARG];
 
-	if (ROFF_PRELUDE & tree->state) {
-		roff_err(tree, *argv, "`%s' disallowed in prelude", 
-				toknames[tok]);
-		return(0);
-	}
+	/*
+	 * Text macros are similar to special tokens, except that
+	 * arguments are instead flushed as pure data: we're only
+	 * concerned with the macro and its arguments.  Example:
+	 * 
+	 * .Fl v W f ;
+	 *
+	 * ...Produces...
+	 *
+	 * <fl> v W f </fl> ;
+	 */
 
+	if (ROFF_PRELUDE & tree->state)
+		return(roff_errp(tree, *argv, tok, ERR_NOT_PR));
+
 	first = (*argv == tree->cur);
 	argv++;
 
 	if ( ! roffparseopts(tree, tok, &argv, argcp, argvp))
 		return(0);
-	if ( ! (*tree->cb.roffin)(tree->arg, tok, argcp, argvp))
+	if ( ! (*tree->cb.roffin)(tree->arg, tok, argcp, 
+				(const char **)argvp))
 		return(0);
 	if (NULL == *argv)
 		return((*tree->cb.roffout)(tree->arg, tok));
@@ -1261,7 +1426,6 @@ roff_text(ROFFCALL_ARGS) 
 		while (*argv)
 			if ( ! roffdata(tree, i++, *argv++))
 				return(0);
-
 		return((*tree->cb.roffout)(tree->arg, tok));
 	}
 
@@ -1270,6 +1434,8 @@ roff_text(ROFFCALL_ARGS) 
 	 * terminating punctuation.  If we encounter it and all
 	 * subsequent tokens are punctuation, then stop processing (the
 	 * line-dominant macro will print these tokens after closure).
+	 * If the punctuation is followed by non-punctuation, then close
+	 * and re-open our scope, then continue.
 	 */
 
 	i = 0;
@@ -1281,11 +1447,9 @@ roff_text(ROFFCALL_ARGS) 
 	
 			if ( ! roffcall(tree, c, argv))
 				return(0);
-	
 			if (ROFF_LSCOPE & tokens[tok].flags)
 				if ( ! (*tree->cb.roffout)(tree->arg, tok))
 					return(0);
-	
 			break;
 		}
 
@@ -1301,8 +1465,21 @@ roff_text(ROFFCALL_ARGS) 
 				break;
 
 		if (argv[j]) {
+			if (ROFF_LSCOPE & tokens[tok].flags) {
+				if ( ! roffdata(tree, 0, *argv++))
+					return(0);
+				continue;
+			}
+			if ( ! (*tree->cb.roffout)(tree->arg, tok))
+				return(0);
 			if ( ! roffdata(tree, 0, *argv++))
 				return(0);
+			if ( ! (*tree->cb.roffin)(tree->arg, tok, 
+						argcp, 
+						(const char **)argvp))
+				return(0);
+
+			i = 0;
 			continue;
 		}
 
@@ -1334,12 +1511,30 @@ static int
 roff_depr(ROFFCALL_ARGS)
 {
 
-	roff_err(tree, *argv, "`%s' is deprecated", toknames[tok]);
-	return(0);
+	return(roff_errp(tree, *argv, tok, ERR_DEPREC));
 }
 
 
-static void
+static int
+roff_warnp(const struct rofftree *tree, const char *pos,
+		int tok, enum rofferr type)
+{
+	char		 *p;
+
+	switch (type) {
+	case (WRN_SECORD):
+		p = "section at `%s' out of order";
+		break;
+	default:
+		abort();
+		/* NOTREACHED */
+	}
+
+	return(roff_warn(tree, pos, p, toknames[tok]));
+}
+
+
+static int
 roff_warn(const struct rofftree *tree, const char *pos, char *fmt, ...)
 {
 	va_list		 ap;
@@ -1349,22 +1544,75 @@ roff_warn(const struct rofftree *tree, const char *pos
 	(void)vsnprintf(buf, sizeof(buf), fmt, ap);
 	va_end(ap);
 
-	(*tree->cb.roffmsg)(tree->arg, 
-			ROFF_WARN, tree->cur, pos, buf);
+	return((*tree->cb.roffmsg)(tree->arg, 
+				ROFF_WARN, tree->cur, pos, buf));
 }
 
 
-static void
+static int
+roff_errp(const struct rofftree *tree, const char *pos, 
+		int tok, enum rofferr type)
+{
+	char		 *p;
+
+	switch (type) {
+	case (ERR_ARGEQ1):
+		p = "`%s' expects exactly one argument";
+		break;
+	case (ERR_ARGEQ0):
+		p = "`%s' expects exactly zero arguments";
+		break;
+	case (ERR_ARGGE1):
+		p = "`%s' expects one or more arguments";
+		break;
+	case (ERR_ARGGE2):
+		p = "`%s' expects two or more arguments";
+		break;
+	case (ERR_BADARG):
+		p = "invalid argument for `%s'";
+		break;
+	case (ERR_NOTSUP):
+		p = "macro `%s' is not supported";
+		break;
+	case(ERR_PR_OOO):
+		p = "prelude macro `%s' is out of order";
+		break;
+	case(ERR_PR_REP):
+		p = "prelude macro `%s' repeated";
+		break;
+	case(ERR_ARGLEN):
+		p = "macro argument for `%s' is too long";
+		break;
+	case(ERR_DEPREC):
+		p = "macro `%s' is deprecated";
+		break;
+	case(ERR_NOT_PR):
+		p = "macro `%s' disallowed in prelude";
+		break;
+	case(ERR_ARGMNY):
+		p = "too many arguments for macro `%s'";
+		break;
+	default:
+		abort();
+		/* NOTREACHED */
+	}
+
+	return(roff_err(tree, pos, p, toknames[tok]));
+}
+
+
+static int
 roff_err(const struct rofftree *tree, const char *pos, char *fmt, ...)
 {
 	va_list		 ap;
 	char		 buf[128];
 
 	va_start(ap, fmt);
-	(void)vsnprintf(buf, sizeof(buf), fmt, ap);
+	if (-1 == vsnprintf(buf, sizeof(buf), fmt, ap))
+		err(1, "vsnprintf");
 	va_end(ap);
 
-	(*tree->cb.roffmsg)(tree->arg, 
-			ROFF_ERROR, tree->cur, pos, buf);
+	return((*tree->cb.roffmsg)
+			(tree->arg, ROFF_ERROR, tree->cur, pos, buf));
 }