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.

diff --git a/man_validate.c b/man_validate.c
index 8e7868425fe605123fe1c42f670980b3937a2890..579e91ffaac719313c9bd28b8fc8f4dd23e5606f 100644 (file)
--- 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 <kristaps@bsd.lv>
  * Copyright (c) 2010, 2012, 2013, 2014 Ingo Schwarze <schwarze@openbsd.org>
@@ -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 1354e02683e9fc64269bc0b70b1db1977167a9dd..794af306159551beb2707ec9fb8362f8f903c58d 100644 (file)
--- 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 <kristaps@bsd.lv>
  * Copyright (c) 2011, 2012, 2013, 2014 Ingo Schwarze <schwarze@openbsd.org>
@@ -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 6056ab5a63a042c513200562e1621485785c7294..be2f9f1028e2188fe3dcdf439d223e7909b90153 100644 (file)
--- 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 <kristaps@bsd.lv>
  * Copyright (c) 2010-2014 Ingo Schwarze <schwarze@openbsd.org>
@@ -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 38ed0612e8a35bc4f1b88a9eb698c4f6a6cf68e0..04e9d9724864e1881dfb1ce71e1d557f78d9e26f 100644 (file)
--- 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 <kristaps@bsd.lv>
  * Copyright (c) 2010, 2012, 2013, 2014 Ingo Schwarze <schwarze@openbsd.org>
@@ -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 bb7025b91045cc6f8a1a3ef648f38f893aa1b42c..32f141de8c943a8b05aaf74cb030853d34a4b0fb 100644 (file)
--- 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 <kristaps@bsd.lv>
  * Copyright (c) 2010-2014 Ingo Schwarze <schwarze@openbsd.org>
@@ -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 8183456b33aa1099b98b17ec2b5abe7df2031c4b..097a62e8abad0bb41b6bf8d79918fc268897e84f 100644 (file)
--- 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 <kristaps@bsd.lv>
  * Copyright (c) 2010-2014 Ingo Schwarze <schwarze@openbsd.org>
@@ -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",