From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from localhost (fantadrom.bsd.lv [local]); by fantadrom.bsd.lv (OpenSMTPD) with ESMTPA id 792f224b; for ; Mon, 23 Feb 2015 08:31:34 -0500 (EST) Date: Mon, 23 Feb 2015 08:31:34 -0500 (EST) Message-Id: <12219175070601303218.enqueue@fantadrom.bsd.lv> X-Mailinglist: mdocml-source Reply-To: source@mdocml.bsd.lv MIME-Version: 1.0 From: schwarze@mdocml.bsd.lv To: source@mdocml.bsd.lv Subject: mdocml: improve NAME section diagnostics; confusing messages reported by X-Mailer: activitymail 1.26, http://search.cpan.org/dist/activitymail/ Content-Type: text/plain; charset=utf-8 Log Message: ----------- improve NAME section diagnostics; confusing messages reported by Jan Stary Modified Files: -------------- mdocml: mandoc.1 mandoc.h mdoc.7 mdoc_validate.c read.c Revision Data ------------- Index: mdoc_validate.c =================================================================== RCS file: /home/cvs/mdocml/mdocml/mdoc_validate.c,v retrieving revision 1.281 retrieving revision 1.282 diff -Lmdoc_validate.c -Lmdoc_validate.c -u -p -r1.281 -r1.282 --- mdoc_validate.c +++ mdoc_validate.c @@ -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". - */ + hasnm = hasnd = 0; - if (NULL == (n = mdoc->last->child)) { - mandoc_msg(MANDOCERR_NAMESEC_BAD, mdoc->parse, - mdoc->last->line, mdoc->last->pos, "empty"); - return; + 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; + } } - 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]); - } - - 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 Index: mdoc.7 =================================================================== RCS file: /home/cvs/mdocml/mdocml/mdoc.7,v retrieving revision 1.251 retrieving revision 1.252 diff -Lmdoc.7 -Lmdoc.7 -u -p -r1.251 -r1.252 --- mdoc.7 +++ mdoc.7 @@ -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 Index: read.c =================================================================== RCS file: /home/cvs/mdocml/mdocml/read.c,v retrieving revision 1.127 retrieving revision 1.128 diff -Lread.c -Lread.c -u -p -r1.127 -r1.128 --- read.c +++ read.c @@ -109,7 +109,10 @@ static const char * const mandocerrs[MAN "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", Index: mandoc.1 =================================================================== RCS file: /home/cvs/mdocml/mdocml/mandoc.1,v retrieving revision 1.154 retrieving revision 1.155 diff -Lmandoc.1 -Lmandoc.1 -u -p -r1.154 -r1.155 --- mandoc.1 +++ mandoc.1 @@ -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 +child macro. +.It Sy "description not at the end of NAME" +.Pq mdoc +The NAME section does contain an .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, 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 Index: mandoc.h =================================================================== RCS file: /home/cvs/mdocml/mdocml/mandoc.h,v retrieving revision 1.200 retrieving revision 1.201 diff -Lmandoc.h -Lmandoc.h -u -p -r1.200 -r1.201 --- mandoc.h +++ mandoc.h @@ -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 */ -- To unsubscribe send an email to source+unsubscribe@mdocml.bsd.lv