From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from krisdoz.my.domain (schwarze@localhost [127.0.0.1]) by krisdoz.my.domain (8.14.5/8.14.5) with ESMTP id s61MbG1C029597 for ; Tue, 1 Jul 2014 18:37:16 -0400 (EDT) Received: (from schwarze@localhost) by krisdoz.my.domain (8.14.5/8.14.3/Submit) id s61MbGDU005060; Tue, 1 Jul 2014 18:37:16 -0400 (EDT) Date: Tue, 1 Jul 2014 18:37:16 -0400 (EDT) Message-Id: <201407012237.s61MbGDU005060@krisdoz.my.domain> 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: Clean up the warnings related to document structure. X-Mailer: activitymail 1.26, http://search.cpan.org/dist/activitymail/ Content-Type: text/plain; charset=utf-8 Log Message: ----------- 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. Modified Files: -------------- mdocml: man_validate.c mandoc.c mandoc.h mdoc.c mdoc_validate.c read.c Revision Data ------------- Index: mandoc.c =================================================================== RCS file: /usr/vhosts/mdocml.bsd.lv/cvs/mdocml/mandoc.c,v retrieving revision 1.80 retrieving revision 1.81 diff -Lmandoc.c -Lmandoc.c -u -p -r1.80 -r1.81 --- mandoc.c +++ mandoc.c @@ -516,7 +516,7 @@ mandoc_normdate(struct mparse *parse, ch 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; Index: mdoc_validate.c =================================================================== RCS file: /usr/vhosts/mdocml.bsd.lv/cvs/mdocml/mdoc_validate.c,v retrieving revision 1.216 retrieving revision 1.217 diff -Lmdoc_validate.c -Lmdoc_validate.c -u -p -r1.216 -r1.217 --- mdoc_validate.c +++ mdoc_validate.c @@ -935,10 +935,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); } @@ -948,10 +950,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); } @@ -961,10 +965,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); } @@ -1664,9 +1670,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); } @@ -1889,7 +1896,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); } @@ -1898,14 +1906,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); } @@ -1913,6 +1923,7 @@ static int post_sh_head(POST_ARGS) { struct mdoc_node *n; + const char *goodsec; char *secname; enum mdoc_sec sec; @@ -1931,7 +1942,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. */ @@ -1974,10 +1986,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. */ @@ -1987,10 +2001,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 */ @@ -1999,12 +2015,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; @@ -2169,18 +2190,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; } @@ -2224,7 +2243,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); } @@ -2246,7 +2266,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 Index: mdoc.c =================================================================== RCS file: /usr/vhosts/mdocml.bsd.lv/cvs/mdocml/mdoc.c,v retrieving revision 1.215 retrieving revision 1.216 diff -Lmdoc.c -Lmdoc.c -u -p -r1.215 -r1.216 --- mdoc.c +++ mdoc.c @@ -35,7 +35,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", @@ -66,7 +66,7 @@ const char *const __mdoc_macronames[MDOC "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] = { Index: mandoc.h =================================================================== RCS file: /usr/vhosts/mdocml.bsd.lv/cvs/mdocml/mandoc.h,v retrieving revision 1.124 retrieving revision 1.125 diff -Lmandoc.h -Lmandoc.h -u -p -r1.124 -r1.125 --- mandoc.h +++ mandoc.h @@ -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 */ Index: read.c =================================================================== RCS file: /usr/vhosts/mdocml.bsd.lv/cvs/mdocml/read.c,v retrieving revision 1.53 retrieving revision 1.54 diff -Lread.c -Lread.c -u -p -r1.53 -r1.54 --- read.c +++ read.c @@ -93,26 +93,26 @@ static const char * const mandocerrs[MAN "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", @@ -176,7 +176,7 @@ static const char * const mandocerrs[MAN "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", Index: man_validate.c =================================================================== RCS file: /usr/vhosts/mdocml.bsd.lv/cvs/mdocml/man_validate.c,v retrieving revision 1.93 retrieving revision 1.94 diff -Lman_validate.c -Lman_validate.c -u -p -r1.93 -r1.94 --- man_validate.c +++ man_validate.c @@ -414,7 +414,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; } } -- To unsubscribe send an email to source+unsubscribe@mdocml.bsd.lv