From c9939e9971e983553a2f3f786d124427b6d4e16e Mon Sep 17 00:00:00 2001 From: Ingo Schwarze Date: Tue, 1 Jul 2014 22:37:15 +0000 Subject: 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. --- man_validate.c | 7 ++++-- mandoc.c | 4 +-- mandoc.h | 36 +++++++++++++-------------- mdoc.c | 6 ++--- mdoc_validate.c | 75 ++++++++++++++++++++++++++++++++++++--------------------- read.c | 22 ++++++++--------- 6 files changed, 87 insertions(+), 63 deletions(-) diff --git a/man_validate.c b/man_validate.c index 8e786842..579e91ff 100644 --- a/man_validate.c +++ b/man_validate.c @@ -1,4 +1,4 @@ -/* $Id: man_validate.c,v 1.93 2014/06/20 23:02:31 schwarze Exp $ */ +/* $Id: man_validate.c,v 1.94 2014/07/01 22:37:15 schwarze Exp $ */ /* * Copyright (c) 2008, 2009, 2010, 2011 Kristaps Dzonsons * Copyright (c) 2010, 2012, 2013, 2014 Ingo Schwarze @@ -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; } } diff --git a/mandoc.c b/mandoc.c index 1354e026..794af306 100644 --- a/mandoc.c +++ b/mandoc.c @@ -1,4 +1,4 @@ -/* $Id: mandoc.c,v 1.80 2014/06/20 17:24:00 schwarze Exp $ */ +/* $Id: mandoc.c,v 1.81 2014/07/01 22:37:15 schwarze Exp $ */ /* * Copyright (c) 2008, 2009, 2010, 2011 Kristaps Dzonsons * Copyright (c) 2011, 2012, 2013, 2014 Ingo Schwarze @@ -516,7 +516,7 @@ mandoc_normdate(struct mparse *parse, char *in, int ln, int pos) 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; diff --git a/mandoc.h b/mandoc.h index 6056ab5a..be2f9f10 100644 --- a/mandoc.h +++ b/mandoc.h @@ -1,4 +1,4 @@ -/* $Id: mandoc.h,v 1.124 2014/06/30 23:45:07 schwarze Exp $ */ +/* $Id: mandoc.h,v 1.125 2014/07/01 22:37:15 schwarze Exp $ */ /* * Copyright (c) 2010, 2011 Kristaps Dzonsons * Copyright (c) 2010-2014 Ingo Schwarze @@ -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 */ diff --git a/mdoc.c b/mdoc.c index 38ed0612..04e9d972 100644 --- a/mdoc.c +++ b/mdoc.c @@ -1,4 +1,4 @@ -/* $Id: mdoc.c,v 1.215 2014/06/20 17:24:00 schwarze Exp $ */ +/* $Id: mdoc.c,v 1.216 2014/07/01 22:37:15 schwarze Exp $ */ /* * Copyright (c) 2008, 2009, 2010, 2011 Kristaps Dzonsons * Copyright (c) 2010, 2012, 2013, 2014 Ingo Schwarze @@ -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_MAX] = { "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] = { diff --git a/mdoc_validate.c b/mdoc_validate.c index bb7025b9..32f141de 100644 --- a/mdoc_validate.c +++ b/mdoc_validate.c @@ -1,4 +1,4 @@ -/* $Id: mdoc_validate.c,v 1.216 2014/06/20 23:02:31 schwarze Exp $ */ +/* $Id: mdoc_validate.c,v 1.217 2014/07/01 22:37:15 schwarze Exp $ */ /* * Copyright (c) 2008-2012 Kristaps Dzonsons * Copyright (c) 2010-2014 Ingo Schwarze @@ -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 diff --git a/read.c b/read.c index 8183456b..097a62e8 100644 --- a/read.c +++ b/read.c @@ -1,4 +1,4 @@ -/* $Id: read.c,v 1.53 2014/06/30 23:45:08 schwarze Exp $ */ +/* $Id: read.c,v 1.54 2014/07/01 22:37:15 schwarze Exp $ */ /* * Copyright (c) 2008, 2009, 2010, 2011 Kristaps Dzonsons * Copyright (c) 2010-2014 Ingo Schwarze @@ -93,26 +93,26 @@ static const char * const mandocerrs[MANDOCERR_MAX] = { "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[MANDOCERR_MAX] = { "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", -- cgit v1.2.3-56-ge451