improve NAME section diagnostics;

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

diff --git a/mandoc.1 b/mandoc.1
index c8678cd123a1b7e703d113e74119167cf317c901..e218ed7af89c76b59ba27eae8894bfe874f92c5e 100644 (file)
--- a/mandoc.1
+++ b/mandoc.1
@@ -1,4 +1,4 @@
-.\"    $Id: mandoc.1,v 1.154 2015/02/16 19:02:48 schwarze Exp $
+.\"    $Id: mandoc.1,v 1.155 2015/02/23 13:31:03 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/mandoc.h b/mandoc.h
index c088d7de6281db957434d396d0f391edaa5597e5..eb8a1aa6f298e173271731d72054e0a8526eebc0 100644 (file)
--- a/mandoc.h
+++ b/mandoc.h
@@ -1,4 +1,4 @@
-/*     $Id: mandoc.h,v 1.200 2015/02/06 16:06:25 schwarze Exp $ */
+/*     $Id: mandoc.h,v 1.201 2015/02/23 13:31:04 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/mdoc.7 b/mdoc.7
index df25d8cbe42bdf081f28b847d06ea4bc9ec8786c..d4c8ccd11c4b9095722a44feb7b3f88d4a26686b 100644 (file)
--- a/mdoc.7
+++ b/mdoc.7
@@ -1,4 +1,4 @@
-.\"    $Id: mdoc.7,v 1.251 2015/02/15 17:57:45 schwarze Exp $
+.\"    $Id: mdoc.7,v 1.252 2015/02/23 13:31:04 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
@@ -1930,11 +1930,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/mdoc_validate.c b/mdoc_validate.c
index 082e49a6cdad9b1f04f1a5647e6ca909bed11889..7e8e9005becbd173fc16484ea8cfdc7aaed336f3 100644 (file)
--- a/mdoc_validate.c
+++ b/mdoc_validate.c
@@ -1,4 +1,4 @@
-/*     $Id: mdoc_validate.c,v 1.281 2015/02/17 20:37:17 schwarze Exp $ */
+/*     $Id: mdoc_validate.c,v 1.282 2015/02/23 13:31:04 schwarze Exp $ */
 /*
  * Copyright (c) 2008-2012 Kristaps Dzonsons <kristaps@bsd.lv>
  * Copyright (c) 2010-2015 Ingo Schwarze <schwarze@openbsd.org>
@@ -1748,34 +1748,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/read.c b/read.c
index 69d81f5a14d3f1a9029fbe597ef88202f383ab05..3fbedc81e758d9e393d5a562fdd74bb7b1a81fcf 100644 (file)
--- a/read.c
+++ b/read.c
@@ -1,4 +1,4 @@
-/*     $Id: read.c,v 1.127 2015/02/20 22:40:38 schwarze Exp $ */
+/*     $Id: read.c,v 1.128 2015/02/23 13:31:04 schwarze Exp $ */
 /*
  * Copyright (c) 2008, 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
  * Copyright (c) 2010-2015 Ingo Schwarze <schwarze@openbsd.org>
@@ -109,7 +109,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",