Clean up the warnings related to document structure.

* Hierarchical naming of the related enum mandocerr items.
* Mention the offending macro, section title, or string.
While here, improve some wordings:
* Descriptive instead of imperative style.
* Uniform style for "missing" and "skipping".
* Where applicable, mention the fallback used.

38 files changed, 186 insertions, 87 deletions

diff --git a/regress/usr.bin/mandoc/man/TH/baddate.out_lint b/regress/usr.bin/mandoc/man/TH/baddate.out_lint
index bef5060ab14..57f244042c9 100644
--- a/regress/usr.bin/mandoc/man/TH/baddate.out_lint
+++ b/regress/usr.bin/mandoc/man/TH/baddate.out_lint
@@ -1 +1 @@
-mandoc: baddate.in:1:18: WARNING: cannot parse date, using it verbatim
+mandoc: baddate.in:1:18: WARNING: cannot parse date, using it verbatim: three bad words
diff --git a/regress/usr.bin/mandoc/man/TH/case.out_lint b/regress/usr.bin/mandoc/man/TH/case.out_lint
index 1d1c2fdfa7d..8e91330c763 100644
--- a/regress/usr.bin/mandoc/man/TH/case.out_lint
+++ b/regress/usr.bin/mandoc/man/TH/case.out_lint
@@ -1 +1 @@
-mandoc: case.in:1:5: WARNING: document title should be all caps
+mandoc: case.in:1:8: WARNING: lower case character in document title: TH-case
diff --git a/regress/usr.bin/mandoc/man/TH/emptydate.out_lint b/regress/usr.bin/mandoc/man/TH/emptydate.out_lint
index 1d656a980b1..60e5394d4d0 100644
--- a/regress/usr.bin/mandoc/man/TH/emptydate.out_lint
+++ b/regress/usr.bin/mandoc/man/TH/emptydate.out_lint
@@ -1 +1 @@
-mandoc: emptydate.in:1:20: WARNING: date missing, using today's date
+mandoc: emptydate.in:1:20: WARNING: missing date, using today's date
diff --git a/regress/usr.bin/mandoc/man/TH/noTH.mandoc_lint b/regress/usr.bin/mandoc/man/TH/noTH.mandoc_lint
deleted file mode 100644
index d0d2efe10bf..00000000000
--- a/regress/usr.bin/mandoc/man/TH/noTH.mandoc_lint
+++ /dev/null
@@ -1,2 +0,0 @@
-noTH.in:0:1: WARNING: no TH macro in document
-noTH.in:0:1: WARNING: date missing, using today's date
diff --git a/regress/usr.bin/mandoc/man/TH/noTH.out_lint b/regress/usr.bin/mandoc/man/TH/noTH.out_lint
index f618330d217..6b7977668d3 100644
--- a/regress/usr.bin/mandoc/man/TH/noTH.out_lint
+++ b/regress/usr.bin/mandoc/man/TH/noTH.out_lint
@@ -1,2 +1,2 @@
-mandoc: noTH.in: WARNING: no TH macro in document
-mandoc: noTH.in: WARNING: date missing, using today's date
+mandoc: noTH.in: WARNING: missing .TH macro, using "unknown 1"
+mandoc: noTH.in: WARNING: missing date, using today's date
diff --git a/regress/usr.bin/mandoc/man/TH/twoargs.out_lint b/regress/usr.bin/mandoc/man/TH/twoargs.out_lint
index b849d8b8d53..eafb0ede867 100644
--- a/regress/usr.bin/mandoc/man/TH/twoargs.out_lint
+++ b/regress/usr.bin/mandoc/man/TH/twoargs.out_lint
@@ -1,2 +1,2 @@
 mandoc: twoargs.in:1:2: ERROR: argument count wrong: line arguments >= 2 (have 1)
-mandoc: twoargs.in:1:2: WARNING: date missing, using today's date
+mandoc: twoargs.in:1:2: WARNING: missing date, using today's date
diff --git a/regress/usr.bin/mandoc/mdoc/Dt/badarch.out_lint b/regress/usr.bin/mandoc/mdoc/Dt/badarch.out_lint
index bce516888ce..8e33ece69ca 100644
--- a/regress/usr.bin/mandoc/mdoc/Dt/badarch.out_lint
+++ b/regress/usr.bin/mandoc/mdoc/Dt/badarch.out_lint
@@ -1 +1 @@
-mandoc: badarch.in:2:18: WARNING: unknown manual volume or arch
+mandoc: badarch.in:2:18: WARNING: unknown manual volume or arch: Cray
diff --git a/regress/usr.bin/mandoc/mdoc/Dt/baddate.out_lint b/regress/usr.bin/mandoc/mdoc/Dt/baddate.out_lint
index 6814b6948b2..0c6fed173bf 100644
--- a/regress/usr.bin/mandoc/mdoc/Dt/baddate.out_lint
+++ b/regress/usr.bin/mandoc/mdoc/Dt/baddate.out_lint
@@ -1 +1 @@
-mandoc: baddate.in:1:2: WARNING: cannot parse date, using it verbatim
+mandoc: baddate.in:1:2: WARNING: cannot parse date, using it verbatim: foo
diff --git a/regress/usr.bin/mandoc/mdoc/Dt/badsec.out_lint b/regress/usr.bin/mandoc/mdoc/Dt/badsec.out_lint
index 963966de6bf..eb7bfcf22d9 100644
--- a/regress/usr.bin/mandoc/mdoc/Dt/badsec.out_lint
+++ b/regress/usr.bin/mandoc/mdoc/Dt/badsec.out_lint
@@ -1 +1 @@
-mandoc: badsec.in:2:2: WARNING: unknown manual section
+mandoc: badsec.in:2:15: WARNING: unknown manual section: foo
diff --git a/regress/usr.bin/mandoc/mdoc/Dt/befSh.out_lint b/regress/usr.bin/mandoc/mdoc/Dt/befSh.out_lint
index baed9c38f10..faad27ec8c8 100644
--- a/regress/usr.bin/mandoc/mdoc/Dt/befSh.out_lint
+++ b/regress/usr.bin/mandoc/mdoc/Dt/befSh.out_lint
@@ -1 +1 @@
-mandoc: befSh.in:4:4: WARNING: content before the first section header
+mandoc: befSh.in:4:4: WARNING: content before first section header: Ox
diff --git a/regress/usr.bin/mandoc/mdoc/Dt/case.out_lint b/regress/usr.bin/mandoc/mdoc/Dt/case.out_lint
index 11a33d9ba15..ad3b4beb954 100644
--- a/regress/usr.bin/mandoc/mdoc/Dt/case.out_lint
+++ b/regress/usr.bin/mandoc/mdoc/Dt/case.out_lint
@@ -1 +1 @@
-mandoc: case.in:2:5: WARNING: document title should be all caps
+mandoc: case.in:2:6: WARNING: lower case character in document title: Dt-case
diff --git a/regress/usr.bin/mandoc/mdoc/Dt/dupe.in b/regress/usr.bin/mandoc/mdoc/Dt/dupe.in
index 1a905552c5d..cc6b742750d 100644
--- a/regress/usr.bin/mandoc/mdoc/Dt/dupe.in
+++ b/regress/usr.bin/mandoc/mdoc/Dt/dupe.in
@@ -1,6 +1,6 @@
 .Dd June 13, 2014
 .Dt DT-DUPE 1
-.Os OpenBSD
+.Dt DT-DUPE 1
 .Os OpenBSD
 .Sh NAME
 .Nm Dt-order
diff --git a/regress/usr.bin/mandoc/mdoc/Dt/dupe.out_lint b/regress/usr.bin/mandoc/mdoc/Dt/dupe.out_lint
index 5b7c39b5f9d..b64844b9c67 100644
--- a/regress/usr.bin/mandoc/mdoc/Dt/dupe.out_lint
+++ b/regress/usr.bin/mandoc/mdoc/Dt/dupe.out_lint
@@ -1 +1 @@
-mandoc: dupe.in:4:2: WARNING: macro not allowed in body: Os
+mandoc: dupe.in:3:2: WARNING: duplicate prologue macro: Dt
diff --git a/regress/usr.bin/mandoc/mdoc/Dt/lateos.out_lint b/regress/usr.bin/mandoc/mdoc/Dt/lateos.out_lint
index 2f1c0f243a1..a1787c4201d 100644
--- a/regress/usr.bin/mandoc/mdoc/Dt/lateos.out_lint
+++ b/regress/usr.bin/mandoc/mdoc/Dt/lateos.out_lint
@@ -1 +1 @@
-mandoc: lateos.in:8:2: WARNING: macro not allowed in body: Os
+mandoc: lateos.in:8:2: WARNING: skipping prologue macro in body: Os
diff --git a/regress/usr.bin/mandoc/mdoc/Dt/nodate.out_lint b/regress/usr.bin/mandoc/mdoc/Dt/nodate.out_lint
index 3ba46e06978..1e77175e1f9 100644
--- a/regress/usr.bin/mandoc/mdoc/Dt/nodate.out_lint
+++ b/regress/usr.bin/mandoc/mdoc/Dt/nodate.out_lint
@@ -1 +1 @@
-mandoc: nodate.in:1:2: WARNING: date missing, using today's date
+mandoc: nodate.in:1:2: WARNING: missing date, using today's date
diff --git a/regress/usr.bin/mandoc/mdoc/Dt/noos.out_lint b/regress/usr.bin/mandoc/mdoc/Dt/noos.out_lint
index d9dcd177dc0..427a08d8349 100644
--- a/regress/usr.bin/mandoc/mdoc/Dt/noos.out_lint
+++ b/regress/usr.bin/mandoc/mdoc/Dt/noos.out_lint
@@ -1 +1 @@
-mandoc: noos.in:3:2: WARNING: macro not allowed in prologue: Sh
+mandoc: noos.in:3:2: WARNING: incomplete prologue, terminated by: Sh
diff --git a/regress/usr.bin/mandoc/mdoc/Dt/order.out_lint b/regress/usr.bin/mandoc/mdoc/Dt/order.out_lint
index 19f1da2decd..bf213328718 100644
--- a/regress/usr.bin/mandoc/mdoc/Dt/order.out_lint
+++ b/regress/usr.bin/mandoc/mdoc/Dt/order.out_lint
@@ -1,2 +1,2 @@
-mandoc: order.in:2:2: WARNING: prologue macros out of order
-mandoc: order.in:3:2: WARNING: prologue macros out of order
+mandoc: order.in:2:2: WARNING: prologue macros out of order: Os
+mandoc: order.in:3:2: WARNING: prologue macros out of order: Dt
diff --git a/regress/usr.bin/mandoc/mdoc/Makefile b/regress/usr.bin/mandoc/mdoc/Makefile
index 852bc2de41f..6109f2be24d 100644
--- a/regress/usr.bin/mandoc/mdoc/Makefile
+++ b/regress/usr.bin/mandoc/mdoc/Makefile
@@ -1,9 +1,9 @@
-# $OpenBSD: Makefile,v 1.27 2014/06/20 18:32:51 schwarze Exp $
+# $OpenBSD: Makefile,v 1.28 2014/07/01 22:36:35 schwarze Exp $
 
 SUBDIR  = Ad An Ap Aq Ar At Bd Bf Bk Bl Brq Bx Cd Cm
 SUBDIR += D1 Dl Dq Dt Dv Em Eo Er Ev Fd Fl Fo Ft Ic In Lb Li Lk
 SUBDIR += Ms Mt Nd Nm No Ns Oo Op Ox Pa Pf Pp Qq Rs
-SUBDIR += Sm Sq St Sx Sy Tn Ux Va Vt Xr blank
+SUBDIR += Sh Sm Sq St Sx Sy Tn Ux Va Vt Xr blank
 
 .include "../Makefile.sub"
 .include <bsd.subdir.mk>
diff --git a/regress/usr.bin/mandoc/mdoc/Nm/badNAME.out_lint b/regress/usr.bin/mandoc/mdoc/Nm/badNAME.out_lint
index 57cf575d8fe..cc6edca3a3e 100644
--- a/regress/usr.bin/mandoc/mdoc/Nm/badNAME.out_lint
+++ b/regress/usr.bin/mandoc/mdoc/Nm/badNAME.out_lint
@@ -1,2 +1,2 @@
 mandoc: badNAME.in:5:2: ERROR: manual name not yet set
-mandoc: badNAME.in:4:2: WARNING: bad NAME section contents
+mandoc: badNAME.in:5:7: WARNING: bad NAME section contents: Bx
diff --git a/regress/usr.bin/mandoc/mdoc/Nm/badNAMEuse.out_lint b/regress/usr.bin/mandoc/mdoc/Nm/badNAMEuse.out_lint
index 05552ab2b9a..5349ab2cc07 100644
--- a/regress/usr.bin/mandoc/mdoc/Nm/badNAMEuse.out_lint
+++ b/regress/usr.bin/mandoc/mdoc/Nm/badNAMEuse.out_lint
@@ -1,2 +1,2 @@
 mandoc: badNAMEuse.in:5:2: ERROR: manual name not yet set
-mandoc: badNAMEuse.in:4:2: WARNING: bad NAME section contents
+mandoc: badNAMEuse.in:5:7: WARNING: bad NAME section contents: Bx
diff --git a/regress/usr.bin/mandoc/mdoc/Sh/Makefile b/regress/usr.bin/mandoc/mdoc/Sh/Makefile
new file mode 100644
index 00000000000..40d9c3e787c
--- /dev/null
+++ b/regress/usr.bin/mandoc/mdoc/Sh/Makefile
@@ -0,0 +1,9 @@
+# $OpenBSD: Makefile,v 1.1 2014/07/01 22:36:35 schwarze Exp $
+
+REGRESS_TARGETS	= first emptyNAME badNAME order
+LINT_TARGETS	= first emptyNAME badNAME order
+
+SKIP_GROFF	= first
+SKIP_ASCII	= first
+
+.include <bsd.regress.mk>
diff --git a/regress/usr.bin/mandoc/mdoc/Sh/badNAME.in b/regress/usr.bin/mandoc/mdoc/Sh/badNAME.in
new file mode 100644
index 00000000000..85ebdbf71c5
--- /dev/null
+++ b/regress/usr.bin/mandoc/mdoc/Sh/badNAME.in
@@ -0,0 +1,8 @@
+.Dd July 1, 2014
+.Dt SH-BADNAME 1
+.Os OpenBSD
+.Sh NAME
+.Em bad NAME section
+.Nm Sh-badNAME
+.Sh DESCRIPTION
+The description appears before the name and is not marked up with Nd.
diff --git a/regress/usr.bin/mandoc/mdoc/Sh/badNAME.out_ascii b/regress/usr.bin/mandoc/mdoc/Sh/badNAME.out_ascii
new file mode 100644
index 00000000000..657c5ba2f86
--- /dev/null
+++ b/regress/usr.bin/mandoc/mdoc/Sh/badNAME.out_ascii
@@ -0,0 +1,9 @@
+SH-BADNAME(1)              OpenBSD Reference Manual              SH-BADNAME(1)
+
+NNAAMMEE
+     _b_a_d _N_A_M_E _s_e_c_t_i_o_n SShh--bbaaddNNAAMMEE
+
+DDEESSCCRRIIPPTTIIOONN
+     The description appears before the name and is not marked up with Nd.
+
+OpenBSD                          July 1, 2014                          OpenBSD
diff --git a/regress/usr.bin/mandoc/mdoc/Sh/badNAME.out_lint b/regress/usr.bin/mandoc/mdoc/Sh/badNAME.out_lint
new file mode 100644
index 00000000000..a7e6980f3a1
--- /dev/null
+++ b/regress/usr.bin/mandoc/mdoc/Sh/badNAME.out_lint
@@ -0,0 +1,2 @@
+mandoc: badNAME.in:5:2: WARNING: bad NAME section contents: Em
+mandoc: badNAME.in:6:2: WARNING: bad NAME section contents: Nm
diff --git a/regress/usr.bin/mandoc/mdoc/Sh/emptyNAME.in b/regress/usr.bin/mandoc/mdoc/Sh/emptyNAME.in
new file mode 100644
index 00000000000..621724e5e48
--- /dev/null
+++ b/regress/usr.bin/mandoc/mdoc/Sh/emptyNAME.in
@@ -0,0 +1,6 @@
+.Dd July 1, 2014
+.Dt SH-EMPTYNAME 1
+.Os OpenBSD
+.Sh NAME
+.Sh DESCRIPTION
+The NAME section is empty.
diff --git a/regress/usr.bin/mandoc/mdoc/Sh/emptyNAME.out_ascii b/regress/usr.bin/mandoc/mdoc/Sh/emptyNAME.out_ascii
new file mode 100644
index 00000000000..9979b9366fa
--- /dev/null
+++ b/regress/usr.bin/mandoc/mdoc/Sh/emptyNAME.out_ascii
@@ -0,0 +1,7 @@
+SH-EMPTYNAME(1)            OpenBSD Reference Manual            SH-EMPTYNAME(1)
+
+NNAAMMEE
+DDEESSCCRRIIPPTTIIOONN
+     The NAME section is empty.
+
+OpenBSD                          July 1, 2014                          OpenBSD
diff --git a/regress/usr.bin/mandoc/mdoc/Sh/emptyNAME.out_lint b/regress/usr.bin/mandoc/mdoc/Sh/emptyNAME.out_lint
new file mode 100644
index 00000000000..e0c2a62cac7
--- /dev/null
+++ b/regress/usr.bin/mandoc/mdoc/Sh/emptyNAME.out_lint
@@ -0,0 +1 @@
+mandoc: emptyNAME.in:4:2: WARNING: bad NAME section contents: empty
diff --git a/regress/usr.bin/mandoc/mdoc/Sh/first.in b/regress/usr.bin/mandoc/mdoc/Sh/first.in
new file mode 100644
index 00000000000..f0d4b0b480c
--- /dev/null
+++ b/regress/usr.bin/mandoc/mdoc/Sh/first.in
@@ -0,0 +1,5 @@
+.Dd July 1, 2014
+.Dt SH-FIRST 1
+.Os OpenBSD
+.Sh DESCRIPTION
+The first section is not a NAME section.
diff --git a/regress/usr.bin/mandoc/mdoc/Sh/first.out_lint b/regress/usr.bin/mandoc/mdoc/Sh/first.out_lint
new file mode 100644
index 00000000000..8e44f6fef62
--- /dev/null
+++ b/regress/usr.bin/mandoc/mdoc/Sh/first.out_lint
@@ -0,0 +1 @@
+mandoc: first.in:4:2: WARNING: first section is not "NAME": DESCRIPTION
diff --git a/regress/usr.bin/mandoc/mdoc/Sh/order.in b/regress/usr.bin/mandoc/mdoc/Sh/order.in
new file mode 100644
index 00000000000..ffab6878187
--- /dev/null
+++ b/regress/usr.bin/mandoc/mdoc/Sh/order.in
@@ -0,0 +1,12 @@
+.Dd July 1, 2014
+.Dt SH-ORDER 1
+.Os OpenBSD
+.Sh NAME
+.Nm Sh-order
+.Nd sections out of conventional order
+.Sh DESCRIPTION
+some text
+.Sh SYNOPSIS
+.Sh SYNOPSIS
+.Sh ERRORS
+.Vt int errno
diff --git a/regress/usr.bin/mandoc/mdoc/Sh/order.out_ascii b/regress/usr.bin/mandoc/mdoc/Sh/order.out_ascii
new file mode 100644
index 00000000000..5f25e91025b
--- /dev/null
+++ b/regress/usr.bin/mandoc/mdoc/Sh/order.out_ascii
@@ -0,0 +1,14 @@
+SH-ORDER(1)                OpenBSD Reference Manual                SH-ORDER(1)
+
+NNAAMMEE
+     SShh--oorrddeerr - sections out of conventional order
+
+DDEESSCCRRIIPPTTIIOONN
+     some text
+
+SSYYNNOOPPSSIISS
+SSYYNNOOPPSSIISS
+EERRRROORRSS
+     _i_n_t _e_r_r_n_o
+
+OpenBSD                          July 1, 2014                          OpenBSD
diff --git a/regress/usr.bin/mandoc/mdoc/Sh/order.out_lint b/regress/usr.bin/mandoc/mdoc/Sh/order.out_lint
new file mode 100644
index 00000000000..817be0caa8d
--- /dev/null
+++ b/regress/usr.bin/mandoc/mdoc/Sh/order.out_lint
@@ -0,0 +1,3 @@
+mandoc: order.in:9:2: WARNING: sections out of conventional order: SYNOPSIS
+mandoc: order.in:10:2: WARNING: duplicate section title: SYNOPSIS
+mandoc: order.in:11:2: WARNING: unexpected section: ERRORS for 2, 3, 4, 9 only
diff --git a/usr.bin/mandoc/man_validate.c b/usr.bin/mandoc/man_validate.c
index 81f67e1ecdd..fc59f8696d1 100644
--- a/usr.bin/mandoc/man_validate.c
+++ b/usr.bin/mandoc/man_validate.c
@@ -1,4 +1,4 @@
-/*	$Id: man_validate.c,v 1.65 2014/06/20 22:58:41 schwarze Exp $ */
+/*	$Id: man_validate.c,v 1.66 2014/07/01 22:36:35 schwarze Exp $ */
 /*
  * Copyright (c) 2008, 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
  * Copyright (c) 2010, 2012, 2013, 2014 Ingo Schwarze <schwarze@openbsd.org>
@@ -410,7 +410,10 @@ post_TH(CHKARGS)
 			/* Only warn about this once... */
 			if (isalpha((unsigned char)*p) &&
 			    ! isupper((unsigned char)*p)) {
-				man_nmsg(man, n, MANDOCERR_TITLE_CASE);
+				mandoc_msg(MANDOCERR_TITLE_CASE,
+				    man->parse, n->line,
+				    n->pos + (p - n->string),
+				    n->string);
 				break;
 			}
 		}
diff --git a/usr.bin/mandoc/mandoc.c b/usr.bin/mandoc/mandoc.c
index 7d187af9133..afd68cd652c 100644
--- a/usr.bin/mandoc/mandoc.c
+++ b/usr.bin/mandoc/mandoc.c
@@ -1,4 +1,4 @@
-/*	$Id: mandoc.c,v 1.49 2014/06/20 17:23:09 schwarze Exp $ */
+/*	$Id: mandoc.c,v 1.50 2014/07/01 22:36:35 schwarze Exp $ */
 /*
  * Copyright (c) 2008, 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
  * Copyright (c) 2011, 2012, 2013, 2014 Ingo Schwarze <schwarze@openbsd.org>
@@ -509,7 +509,7 @@ mandoc_normdate(struct mparse *parse, char *in, int ln, int pos)
 		t = 0;
 	else if (!a2time(&t, "$" "Mdocdate: %b %d %Y $", in) &&
 	    !a2time(&t, "%b %d, %Y", in)) {
-		mandoc_msg(MANDOCERR_DATE_BAD, parse, ln, pos, NULL);
+		mandoc_msg(MANDOCERR_DATE_BAD, parse, ln, pos, in);
 		t = 0;
 	}
 	out = t ? time2a(t) : NULL;
diff --git a/usr.bin/mandoc/mandoc.h b/usr.bin/mandoc/mandoc.h
index 21f5e1355f0..b800670779f 100644
--- a/usr.bin/mandoc/mandoc.h
+++ b/usr.bin/mandoc/mandoc.h
@@ -1,4 +1,4 @@
-/*	$Id: mandoc.h,v 1.68 2014/06/30 23:45:03 schwarze Exp $ */
+/*	$Id: mandoc.h,v 1.69 2014/07/01 22:36:35 schwarze Exp $ */
 /*
  * Copyright (c) 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
  * Copyright (c) 2010-2014 Ingo Schwarze <schwarze@openbsd.org>
@@ -49,26 +49,26 @@ enum	mandocerr {
 	MANDOCERR_WARNING, /* ===== start of warnings ===== */
 
 	/* related to the prologue */
-	MANDOCERR_TH_MISSING, /* no TH macro in document */
-	MANDOCERR_TITLE_CASE, /* document title should be all caps */
-	MANDOCERR_MSEC_BAD, /* unknown manual section */
-	MANDOCERR_ARCH_BAD, /* unknown manual volume or arch */
-	MANDOCERR_DATE_MISSING, /* date missing, using today's date */
-	MANDOCERR_DATE_BAD, /* cannot parse date, using it verbatim */
-	MANDOCERR_PROLOG_ORDER, /* prologue macros out of order */
-	MANDOCERR_PROLOG_REP, /* duplicate prologue macro */
-	MANDOCERR_PROLOG_BAD, /* macro not allowed in prologue: macro */
-	MANDOCERR_PROLOG_ONLY, /* macro not allowed in body: macro */
+	MANDOCERR_TH_MISSING, /* missing .TH macro, using "unknown 1" */
+	MANDOCERR_TITLE_CASE, /* lower case character in document title */
+	MANDOCERR_MSEC_BAD, /* unknown manual section: section */
+	MANDOCERR_ARCH_BAD, /* unknown manual volume or arch: volume */
+	MANDOCERR_DATE_MISSING, /* missing date, using today's date */
+	MANDOCERR_DATE_BAD, /* cannot parse date, using it verbatim: date */
+	MANDOCERR_PROLOG_ORDER, /* prologue macros out of order: macro */
+	MANDOCERR_PROLOG_REP, /* duplicate prologue macro: macro */
+	MANDOCERR_PROLOG_BAD, /* incomplete prologue, terminated by: macro */
+	MANDOCERR_PROLOG_ONLY, /* skipping prologue macro in body: macro */
 
 	/* related to document structure */
 	MANDOCERR_SO, /* .so is fragile, better use ln(1): .so path */
 	MANDOCERR_DOC_EMPTY, /* no document body */
-	MANDOCERR_SEC_BEFORE, /* content before the first section header */
-	MANDOCERR_NAMESECFIRST, /* NAME section must come first */
-	MANDOCERR_BADNAMESEC, /* bad NAME section contents */
-	MANDOCERR_SECOOO, /* sections out of conventional order */
-	MANDOCERR_SECREP, /* duplicate section name */
-	MANDOCERR_SECMSEC, /* section header suited to sections ... */
+	MANDOCERR_SEC_BEFORE, /* content before first section header: macro */
+	MANDOCERR_NAMESEC_FIRST, /* first section is not "NAME": title */
+	MANDOCERR_NAMESEC_BAD, /* bad NAME section contents: macro */
+	MANDOCERR_SEC_ORDER, /* sections out of conventional order: title */
+	MANDOCERR_SEC_REP, /* duplicate section title: title */
+	MANDOCERR_SEC_MSEC, /* unexpected section: title for ... only */
 
 	/* related to macros and nesting */
 	MANDOCERR_MACROOBS, /* skipping obsolete macro */
@@ -132,7 +132,7 @@ enum	mandocerr {
 	MANDOCERR_BADCHAR, /* skipping bad character */
 	MANDOCERR_NAMESC, /* escaped character not allowed in a name */
 	MANDOCERR_NONAME, /* manual name not yet set */
-	MANDOCERR_NOTEXT, /* skipping text before the first section header */
+	MANDOCERR_NOTEXT, /* skipping text before first section header */
 	MANDOCERR_MACRO, /* skipping unknown macro */
 	MANDOCERR_REQUEST, /* NOT IMPLEMENTED: skipping request */
 	MANDOCERR_ARGCOUNT, /* argument count wrong */
diff --git a/usr.bin/mandoc/mdoc.c b/usr.bin/mandoc/mdoc.c
index c59fb662f2f..9efbee769d2 100644
--- a/usr.bin/mandoc/mdoc.c
+++ b/usr.bin/mandoc/mdoc.c
@@ -1,4 +1,4 @@
-/*	$Id: mdoc.c,v 1.105 2014/06/20 17:23:09 schwarze Exp $ */
+/*	$Id: mdoc.c,v 1.106 2014/07/01 22:36:35 schwarze Exp $ */
 /*
  * Copyright (c) 2008, 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
  * Copyright (c) 2010, 2012, 2013, 2014 Ingo Schwarze <schwarze@openbsd.org>
@@ -31,7 +31,7 @@
 #include "libmdoc.h"
 #include "libmandoc.h"
 
-const	char *const __mdoc_macronames[MDOC_MAX] = {
+const	char *const __mdoc_macronames[MDOC_MAX + 1] = {
 	"Ap",		"Dd",		"Dt",		"Os",
 	"Sh",		"Ss",		"Pp",		"D1",
 	"Dl",		"Bd",		"Ed",		"Bl",
@@ -62,7 +62,7 @@ const	char *const __mdoc_macronames[MDOC_MAX] = {
 	"Lk",		"Mt",		"Brq",		"Bro",
 	"Brc",		"%C",		"Es",		"En",
 	"Dx",		"%Q",		"br",		"sp",
-	"%U",		"Ta",		"ll",
+	"%U",		"Ta",		"ll",		"text",
 	};
 
 const	char *const __mdoc_argnames[MDOC_ARG_MAX] = {
diff --git a/usr.bin/mandoc/mdoc_validate.c b/usr.bin/mandoc/mdoc_validate.c
index d704b3a57fe..98e4c9c76d2 100644
--- a/usr.bin/mandoc/mdoc_validate.c
+++ b/usr.bin/mandoc/mdoc_validate.c
@@ -1,4 +1,4 @@
-/*	$Id: mdoc_validate.c,v 1.134 2014/06/20 22:58:41 schwarze Exp $ */
+/*	$Id: mdoc_validate.c,v 1.135 2014/07/01 22:36:35 schwarze Exp $ */
 /*
  * Copyright (c) 2008-2012 Kristaps Dzonsons <kristaps@bsd.lv>
  * Copyright (c) 2010-2014 Ingo Schwarze <schwarze@openbsd.org>
@@ -931,10 +931,12 @@ pre_dt(PRE_ARGS)
 {
 
 	if (NULL == mdoc->meta.date || mdoc->meta.os)
-		mdoc_nmsg(mdoc, n, MANDOCERR_PROLOG_ORDER);
+		mandoc_msg(MANDOCERR_PROLOG_ORDER, mdoc->parse,
+		    n->line, n->pos, "Dt");
 
 	if (mdoc->meta.title)
-		mdoc_nmsg(mdoc, n, MANDOCERR_PROLOG_REP);
+		mandoc_msg(MANDOCERR_PROLOG_REP, mdoc->parse,
+		    n->line, n->pos, "Dt");
 
 	return(1);
 }
@@ -944,10 +946,12 @@ pre_os(PRE_ARGS)
 {
 
 	if (NULL == mdoc->meta.title || NULL == mdoc->meta.date)
-		mdoc_nmsg(mdoc, n, MANDOCERR_PROLOG_ORDER);
+		mandoc_msg(MANDOCERR_PROLOG_ORDER, mdoc->parse,
+		    n->line, n->pos, "Os");
 
 	if (mdoc->meta.os)
-		mdoc_nmsg(mdoc, n, MANDOCERR_PROLOG_REP);
+		mandoc_msg(MANDOCERR_PROLOG_REP, mdoc->parse,
+		    n->line, n->pos, "Os");
 
 	return(1);
 }
@@ -957,10 +961,12 @@ pre_dd(PRE_ARGS)
 {
 
 	if (mdoc->meta.title || mdoc->meta.os)
-		mdoc_nmsg(mdoc, n, MANDOCERR_PROLOG_ORDER);
+		mandoc_msg(MANDOCERR_PROLOG_ORDER, mdoc->parse,
+		    n->line, n->pos, "Dd");
 
 	if (mdoc->meta.date)
-		mdoc_nmsg(mdoc, n, MANDOCERR_PROLOG_REP);
+		mandoc_msg(MANDOCERR_PROLOG_REP, mdoc->parse,
+		    n->line, n->pos, "Dd");
 
 	return(1);
 }
@@ -1660,9 +1666,10 @@ post_root(POST_ARGS)
 
 	if (NULL == n->child)
 		mdoc_nmsg(mdoc, n, MANDOCERR_DOC_EMPTY);
-	else if (MDOC_BLOCK != n->child->type ||
-	    MDOC_Sh != n->child->tok)
-		mdoc_nmsg(mdoc, n->child, MANDOCERR_SEC_BEFORE);
+	else if (MDOC_Sh != n->child->tok)
+		mandoc_msg(MANDOCERR_SEC_BEFORE, mdoc->parse,
+		    n->child->line, n->child->pos,
+		    mdoc_macronames[n->child->tok]);
 
 	return(ret);
 }
@@ -1885,7 +1892,8 @@ post_sh_body(POST_ARGS)
 	 */
 
 	if (NULL == (n = mdoc->last->child)) {
-		mdoc_nmsg(mdoc, mdoc->last, MANDOCERR_BADNAMESEC);
+		mandoc_msg(MANDOCERR_NAMESEC_BAD, mdoc->parse,
+		    mdoc->last->line, mdoc->last->pos, "empty");
 		return(1);
 	}
 
@@ -1894,14 +1902,16 @@ post_sh_body(POST_ARGS)
 			continue;
 		if (MDOC_TEXT == n->type)
 			continue;
-		mdoc_nmsg(mdoc, mdoc->last, MANDOCERR_BADNAMESEC);
+		mandoc_msg(MANDOCERR_NAMESEC_BAD, mdoc->parse,
+		    n->line, n->pos, mdoc_macronames[n->tok]);
 	}
 
 	assert(n);
 	if (MDOC_BLOCK == n->type && MDOC_Nd == n->tok)
 		return(1);
 
-	mdoc_nmsg(mdoc, mdoc->last, MANDOCERR_BADNAMESEC);
+	mandoc_msg(MANDOCERR_NAMESEC_BAD, mdoc->parse,
+	    n->line, n->pos, mdoc_macronames[n->tok]);
 	return(1);
 }
 
@@ -1909,6 +1919,7 @@ static int
 post_sh_head(POST_ARGS)
 {
 	struct mdoc_node *n;
+	const char	*goodsec;
 	char		*secname;
 	enum mdoc_sec	 sec;
 
@@ -1927,7 +1938,8 @@ post_sh_head(POST_ARGS)
 	/* The NAME should be first. */
 
 	if (SEC_NAME != sec && SEC_NONE == mdoc->lastnamed)
-		mdoc_nmsg(mdoc, mdoc->last, MANDOCERR_NAMESECFIRST);
+		mandoc_msg(MANDOCERR_NAMESEC_FIRST, mdoc->parse,
+		    mdoc->last->line, mdoc->last->pos, secname);
 
 	/* The SYNOPSIS gets special attention in other areas. */
 
@@ -1970,10 +1982,12 @@ post_sh_head(POST_ARGS)
 	 */
 
 	if (sec == mdoc->lastnamed)
-		mdoc_nmsg(mdoc, mdoc->last, MANDOCERR_SECREP);
+		mandoc_msg(MANDOCERR_SEC_REP, mdoc->parse,
+		    mdoc->last->line, mdoc->last->pos, secname);
 
 	if (sec < mdoc->lastnamed)
-		mdoc_nmsg(mdoc, mdoc->last, MANDOCERR_SECOOO);
+		mandoc_msg(MANDOCERR_SEC_ORDER, mdoc->parse,
+		    mdoc->last->line, mdoc->last->pos, secname);
 
 	/* Mark the last named section. */
 
@@ -1983,10 +1997,12 @@ post_sh_head(POST_ARGS)
 
 	assert(mdoc->meta.msec);
 
+	goodsec = NULL;
 	switch (sec) {
 	case SEC_ERRORS:
 		if (*mdoc->meta.msec == '4')
 			break;
+		goodsec = "2, 3, 4, 9";
 		/* FALLTHROUGH */
 	case SEC_RETURN_VALUES:
 		/* FALLTHROUGH */
@@ -1995,12 +2011,17 @@ post_sh_head(POST_ARGS)
 			break;
 		if (*mdoc->meta.msec == '3')
 			break;
+		if (NULL == goodsec)
+			goodsec = "2, 3, 9";
 		/* FALLTHROUGH */
 	case SEC_CONTEXT:
 		if (*mdoc->meta.msec == '9')
 			break;
-		mandoc_msg(MANDOCERR_SECMSEC, mdoc->parse,
-		    mdoc->last->line, mdoc->last->pos, secname);
+		if (NULL == goodsec)
+			goodsec = "9";
+		mandoc_vmsg(MANDOCERR_SEC_MSEC, mdoc->parse,
+		    mdoc->last->line, mdoc->last->pos,
+		    "%s for %s only", secname, goodsec);
 		break;
 	default:
 		break;
@@ -2165,18 +2186,16 @@ post_dt(POST_ARGS)
 
 	mdoc->meta.title = mdoc->meta.vol = mdoc->meta.arch = NULL;
 
-	/* First make all characters uppercase. */
+	/* First check that all characters are uppercase. */
 
 	if (NULL != (nn = n->child))
 		for (p = nn->string; *p; p++) {
 			if (toupper((unsigned char)*p) == *p)
 				continue;
-
-			/*
-			 * FIXME: don't be lazy: have this make all
-			 * characters be uppercase and just warn once.
-			 */
-			mdoc_nmsg(mdoc, nn, MANDOCERR_TITLE_CASE);
+			mandoc_msg(MANDOCERR_TITLE_CASE,
+			    mdoc->parse, nn->line,
+			    nn->pos + (p - nn->string),
+			    nn->string);
 			break;
 		}
 
@@ -2220,7 +2239,8 @@ post_dt(POST_ARGS)
 		mdoc->meta.vol = mandoc_strdup(cp);
 		mdoc->meta.msec = mandoc_strdup(nn->string);
 	} else {
-		mdoc_nmsg(mdoc, n, MANDOCERR_MSEC_BAD);
+		mandoc_msg(MANDOCERR_MSEC_BAD, mdoc->parse,
+		    nn->line, nn->pos, nn->string);
 		mdoc->meta.vol = mandoc_strdup(nn->string);
 		mdoc->meta.msec = mandoc_strdup(nn->string);
 	}
@@ -2242,7 +2262,8 @@ post_dt(POST_ARGS)
 	} else {
 		cp = mdoc_a2arch(nn->string);
 		if (NULL == cp) {
-			mdoc_nmsg(mdoc, nn, MANDOCERR_ARCH_BAD);
+			mandoc_msg(MANDOCERR_ARCH_BAD, mdoc->parse,
+			    nn->line, nn->pos, nn->string);
 			free(mdoc->meta.vol);
 			mdoc->meta.vol = mandoc_strdup(nn->string);
 		} else
diff --git a/usr.bin/mandoc/read.c b/usr.bin/mandoc/read.c
index 4eb2b4d14e5..c9955f7b1b5 100644
--- a/usr.bin/mandoc/read.c
+++ b/usr.bin/mandoc/read.c
@@ -1,4 +1,4 @@
-/*	$Id: read.c,v 1.31 2014/06/30 23:45:03 schwarze Exp $ */
+/*	$Id: read.c,v 1.32 2014/07/01 22:36:35 schwarze Exp $ */
 /*
  * Copyright (c) 2008, 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
  * Copyright (c) 2010-2014 Ingo Schwarze <schwarze@openbsd.org>
@@ -85,26 +85,26 @@ static	const char * const	mandocerrs[MANDOCERR_MAX] = {
 	"generic warning",
 
 	/* related to the prologue */
-	"no TH macro in document",
-	"document title should be all caps",
+	"missing .TH macro, using \"unknown 1\"",
+	"lower case character in document title",
 	"unknown manual section",
 	"unknown manual volume or arch",
-	"date missing, using today's date",
+	"missing date, using today's date",
 	"cannot parse date, using it verbatim",
 	"prologue macros out of order",
 	"duplicate prologue macro",
-	"macro not allowed in prologue",
-	"macro not allowed in body",
+	"incomplete prologue, terminated by",
+	"skipping prologue macro in body",
 
 	/* related to document structure */
 	".so is fragile, better use ln(1)",
 	"no document body",
-	"content before the first section header",
-	"NAME section must come first",
+	"content before first section header",
+	"first section is not \"NAME\"",
 	"bad NAME section contents",
 	"sections out of conventional order",
-	"duplicate section name",
-	"section header suited to sections 2, 3, and 9 only",
+	"duplicate section title",
+	"unexpected section",
 
 	/* related to macros and nesting */
 	"skipping obsolete macro",
@@ -168,7 +168,7 @@ static	const char * const	mandocerrs[MANDOCERR_MAX] = {
 	"skipping bad character",
 	"escaped character not allowed in a name",
 	"manual name not yet set",
-	"skipping text before the first section header",
+	"skipping text before first section header",
 	"skipping unknown macro",
 	"NOT IMPLEMENTED, please use groff: skipping request",
 	"argument count wrong",