improve NAME section diagnostics;

confusing messages reported by Jan Stary <hans at stare dot cz>

10 files changed, 70 insertions, 53 deletions

diff --git a/regress/usr.bin/mandoc/mdoc/Nd/broken.out_lint b/regress/usr.bin/mandoc/mdoc/Nd/broken.out_lint
index ffbf4a2f226..6606c52d020 100644
--- a/regress/usr.bin/mandoc/mdoc/Nd/broken.out_lint
+++ b/regress/usr.bin/mandoc/mdoc/Nd/broken.out_lint
@@ -1,4 +1,6 @@
-mandoc: broken.in:5:2: WARNING: bad NAME section contents: Oo
-mandoc: broken.in:9:1: WARNING: bad NAME section contents: text
+mandoc: broken.in:5:2: WARNING: bad NAME section content: Oo
+mandoc: broken.in:9:1: WARNING: bad NAME section content: text
+mandoc: broken.in:4:2: WARNING: NAME section without name
+mandoc: broken.in:4:2: WARNING: NAME section without description
 mandoc: broken.in:13:2: WARNING: moving content out of list: Bl
 mandoc: broken.in:18:1: WARNING: moving content out of list: text
diff --git a/regress/usr.bin/mandoc/mdoc/Nm/badNAME.out_lint b/regress/usr.bin/mandoc/mdoc/Nm/badNAME.out_lint
index c64b2006e83..8a5963d77e0 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: missing manual name, using "": Nm
-mandoc: badNAME.in:5:5: WARNING: bad NAME section contents: Bx
+mandoc: badNAME.in:5:5: WARNING: bad NAME section content: Bx
diff --git a/regress/usr.bin/mandoc/mdoc/Nm/badNAMEuse.out_lint b/regress/usr.bin/mandoc/mdoc/Nm/badNAMEuse.out_lint
index 6bc1f6fe6fa..7b1c802f962 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: missing manual name, using "": Nm
-mandoc: badNAMEuse.in:5:5: WARNING: bad NAME section contents: Bx
+mandoc: badNAMEuse.in:5:5: WARNING: bad NAME section content: Bx
diff --git a/regress/usr.bin/mandoc/mdoc/Sh/badNAME.out_lint b/regress/usr.bin/mandoc/mdoc/Sh/badNAME.out_lint
index a7e6980f3a1..9fbbf668377 100644
--- a/regress/usr.bin/mandoc/mdoc/Sh/badNAME.out_lint
+++ b/regress/usr.bin/mandoc/mdoc/Sh/badNAME.out_lint
@@ -1,2 +1,2 @@
-mandoc: badNAME.in:5:2: WARNING: bad NAME section contents: Em
-mandoc: badNAME.in:6:2: WARNING: bad NAME section contents: Nm
+mandoc: badNAME.in:5:2: WARNING: bad NAME section content: Em
+mandoc: badNAME.in:4:2: WARNING: NAME section without description
diff --git a/regress/usr.bin/mandoc/mdoc/Sh/emptyNAME.out_lint b/regress/usr.bin/mandoc/mdoc/Sh/emptyNAME.out_lint
index e0c2a62cac7..0713bec9ee3 100644
--- a/regress/usr.bin/mandoc/mdoc/Sh/emptyNAME.out_lint
+++ b/regress/usr.bin/mandoc/mdoc/Sh/emptyNAME.out_lint
@@ -1 +1,2 @@
-mandoc: emptyNAME.in:4:2: WARNING: bad NAME section contents: empty
+mandoc: emptyNAME.in:4:2: WARNING: NAME section without name
+mandoc: emptyNAME.in:4:2: WARNING: NAME section without description
diff --git a/share/man/man7/mdoc.7 b/share/man/man7/mdoc.7
index b487c6add62..848c529a5e1 100644
--- a/share/man/man7/mdoc.7
+++ b/share/man/man7/mdoc.7
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: mdoc.7,v 1.132 2015/02/15 17:57:26 schwarze Exp $
+.\"	$OpenBSD: mdoc.7,v 1.133 2015/02/23 13:30:02 schwarze Exp $
 .\"
 .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
 .\" Copyright (c) 2010, 2011, 2013 Ingo Schwarze <schwarze@openbsd.org>
@@ -15,7 +15,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: February 15 2015 $
+.Dd $Mdocdate: February 23 2015 $
 .Dt MDOC 7
 .Os
 .Sh NAME
@@ -1950,11 +1950,9 @@ Examples:
 .Dl \&.An Kristaps Dzonsons \&Aq \&Mt kristaps@bsd.lv
 .Ss \&Nd
 A one line description of the manual's content.
-This may only be invoked in the
-.Em SYNOPSIS
-section subsequent the
-.Sx \&Nm
-macro.
+This is the mandatory last macro of the
+.Em NAME
+section and not appropriate for other sections.
 .Pp
 Examples:
 .Dl Pf . Sx \&Nd mdoc language reference
diff --git a/usr.bin/mandoc/mandoc.1 b/usr.bin/mandoc/mandoc.1
index 79bc1c3385d..848a5d94cd8 100644
--- a/usr.bin/mandoc/mandoc.1
+++ b/usr.bin/mandoc/mandoc.1
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: mandoc.1,v 1.78 2015/02/16 19:02:32 schwarze Exp $
+.\"	$OpenBSD: mandoc.1,v 1.79 2015/02/23 13:30:02 schwarze Exp $
 .\"
 .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
 .\" Copyright (c) 2012, 2014, 2015 Ingo Schwarze <schwarze@openbsd.org>
@@ -15,7 +15,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: February 16 2015 $
+.Dd $Mdocdate: February 23 2015 $
 .Dt MANDOC 1
 .Os
 .Sh NAME
@@ -771,17 +771,27 @@ This may confuse
 .Xr makewhatis 8
 and
 .Xr apropos 1 .
-.It Sy "bad NAME section contents"
+.It Sy "NAME section without name"
 .Pq mdoc
-The last node in the NAME section is not an
+The NAME section does not contain any
+.Ic \&Nm
+child macro.
+.It Sy "NAME section without description"
+.Pq mdoc
+The NAME section lacks the mandatory
 .Ic \&Nd
-macro, or any preceding macro is not
-.Ic \&Nm ,
-or the NAME section is completely empty.
-This may confuse
-.Xr makewhatis 8
+child macro.
+.It Sy "description not at the end of NAME"
+.Pq mdoc
+The NAME section does contain an
+.Ic \&Nd
+child macro, but other content follows it.
+.It Sy "bad NAME section content"
+.Pq mdoc
+The NAME section contains plain text or macros other than
+.Ic \&Nm
 and
-.Xr apropos 1 .
+.Ic \&Nd .
 .It Sy "missing description line, using \(dq\(dq"
 .Pq mdoc
 The
diff --git a/usr.bin/mandoc/mandoc.h b/usr.bin/mandoc/mandoc.h
index a05485b3bf4..202f7169ea1 100644
--- a/usr.bin/mandoc/mandoc.h
+++ b/usr.bin/mandoc/mandoc.h
@@ -1,4 +1,4 @@
-/*	$OpenBSD: mandoc.h,v 1.142 2015/02/06 16:05:51 schwarze Exp $ */
+/*	$OpenBSD: mandoc.h,v 1.143 2015/02/23 13:30:02 schwarze Exp $ */
 /*
  * Copyright (c) 2010, 2011, 2014 Kristaps Dzonsons <kristaps@bsd.lv>
  * Copyright (c) 2010-2015 Ingo Schwarze <schwarze@openbsd.org>
@@ -65,7 +65,10 @@ enum	mandocerr {
 	MANDOCERR_DOC_EMPTY, /* no document body */
 	MANDOCERR_SEC_BEFORE, /* content before first section header: macro */
 	MANDOCERR_NAMESEC_FIRST, /* first section is not NAME: Sh title */
-	MANDOCERR_NAMESEC_BAD, /* bad NAME section contents: macro */
+	MANDOCERR_NAMESEC_NONM, /* NAME section without name */
+	MANDOCERR_NAMESEC_NOND, /* NAME section without description */
+	MANDOCERR_NAMESEC_ND, /* description not at the end of NAME */
+	MANDOCERR_NAMESEC_BAD, /* bad NAME section content: macro */
 	MANDOCERR_ND_EMPTY, /* missing description line, using "" */
 	MANDOCERR_SEC_ORDER, /* sections out of conventional order: Sh title */
 	MANDOCERR_SEC_REP, /* duplicate section title: Sh title */
diff --git a/usr.bin/mandoc/mdoc_validate.c b/usr.bin/mandoc/mdoc_validate.c
index 92aa434533a..d27957f8e7e 100644
--- a/usr.bin/mandoc/mdoc_validate.c
+++ b/usr.bin/mandoc/mdoc_validate.c
@@ -1,4 +1,4 @@
-/*	$OpenBSD: mdoc_validate.c,v 1.197 2015/02/17 20:33:44 schwarze Exp $ */
+/*	$OpenBSD: mdoc_validate.c,v 1.198 2015/02/23 13:30:02 schwarze Exp $ */
 /*
  * Copyright (c) 2008-2012 Kristaps Dzonsons <kristaps@bsd.lv>
  * Copyright (c) 2010-2015 Ingo Schwarze <schwarze@openbsd.org>
@@ -1739,34 +1739,34 @@ static void
 post_sh_name(POST_ARGS)
 {
 	struct mdoc_node *n;
+	int hasnm, hasnd;
 
-	/*
-	 * Warn if the NAME section doesn't contain the `Nm' and `Nd'
-	 * macros (can have multiple `Nm' and one `Nd').  Note that the
-	 * children of the BODY declaration can also be "text".
-	 */
-
-	if (NULL == (n = mdoc->last->child)) {
-		mandoc_msg(MANDOCERR_NAMESEC_BAD, mdoc->parse,
-		    mdoc->last->line, mdoc->last->pos, "empty");
-		return;
-	}
+	hasnm = hasnd = 0;
 
-	for ( ; n && n->next; n = n->next) {
-		if (MDOC_ELEM == n->type && MDOC_Nm == n->tok)
-			continue;
-		if (MDOC_TEXT == n->type)
-			continue;
-		mandoc_msg(MANDOCERR_NAMESEC_BAD, mdoc->parse,
-		    n->line, n->pos, mdoc_macronames[n->tok]);
+	for (n = mdoc->last->child; n != NULL; n = n->next) {
+		switch (n->tok) {
+		case MDOC_Nm:
+			hasnm = 1;
+			break;
+		case MDOC_Nd:
+			hasnd = 1;
+			if (n->next != NULL)
+				mandoc_msg(MANDOCERR_NAMESEC_ND,
+				    mdoc->parse, n->line, n->pos, NULL);
+			break;
+		default:
+			mandoc_msg(MANDOCERR_NAMESEC_BAD, mdoc->parse,
+			    n->line, n->pos, mdoc_macronames[n->tok]);
+			break;
+		}
 	}
 
-	assert(n);
-	if (MDOC_BLOCK == n->type && MDOC_Nd == n->tok)
-		return;
-
-	mandoc_msg(MANDOCERR_NAMESEC_BAD, mdoc->parse,
-	    n->line, n->pos, mdoc_macronames[n->tok]);
+	if ( ! hasnm)
+		mandoc_msg(MANDOCERR_NAMESEC_NONM, mdoc->parse,
+		    mdoc->last->line, mdoc->last->pos, NULL);
+	if ( ! hasnd)
+		mandoc_msg(MANDOCERR_NAMESEC_NOND, mdoc->parse,
+		    mdoc->last->line, mdoc->last->pos, NULL);
 }
 
 static void
diff --git a/usr.bin/mandoc/read.c b/usr.bin/mandoc/read.c
index bd20829759f..85f1238bbaa 100644
--- a/usr.bin/mandoc/read.c
+++ b/usr.bin/mandoc/read.c
@@ -1,4 +1,4 @@
-/*	$OpenBSD: read.c,v 1.102 2015/02/20 22:40:05 schwarze Exp $ */
+/*	$OpenBSD: read.c,v 1.103 2015/02/23 13:30:02 schwarze Exp $ */
 /*
  * Copyright (c) 2008, 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
  * Copyright (c) 2010-2015 Ingo Schwarze <schwarze@openbsd.org>
@@ -104,7 +104,10 @@ static	const char * const	mandocerrs[MANDOCERR_MAX] = {
 	"no document body",
 	"content before first section header",
 	"first section is not \"NAME\"",
-	"bad NAME section contents",
+	"NAME section without name",
+	"NAME section without description",
+	"description not at the end of NAME",
+	"bad NAME section content",
 	"missing description line, using \"\"",
 	"sections out of conventional order",
 	"duplicate section title",