From f219a129fd68f9a8fd81fca8b18ef3fb534854a0 Mon Sep 17 00:00:00 2001 From: Ingo Schwarze Date: Mon, 23 Feb 2015 13:31:03 +0000 Subject: improve NAME section diagnostics; confusing messages reported by Jan Stary --- mandoc.1 | 30 ++++++++++++++++++++---------- mandoc.h | 7 +++++-- mdoc.7 | 12 +++++------- mdoc_validate.c | 50 +++++++++++++++++++++++++------------------------- read.c | 7 +++++-- 5 files changed, 60 insertions(+), 46 deletions(-) diff --git a/mandoc.1 b/mandoc.1 index c8678cd1..e218ed7a 100644 --- 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 .\" Copyright (c) 2012, 2014, 2015 Ingo Schwarze @@ -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 c088d7de..eb8a1aa6 100644 --- 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 * Copyright (c) 2010-2015 Ingo Schwarze @@ -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 df25d8cb..d4c8ccd1 100644 --- 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 .\" Copyright (c) 2010, 2011, 2013 Ingo Schwarze @@ -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 082e49a6..7e8e9005 100644 --- 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 * Copyright (c) 2010-2015 Ingo Schwarze @@ -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 69d81f5a..3fbedc81 100644 --- 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 * Copyright (c) 2010-2015 Ingo Schwarze @@ -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", -- cgit v1.2.3-56-ge451