Introduce a new mandoc(1) message level, -W style, below -W warning.

Switch -W all from meaning -W warning to meaning -W style.
The meaning of -T lint does *not* change, it still implies -W warning.
No messages on the new level yet, but they will come.

Usually, i do not lightly make the user interface larger.
But this has been planned for years, and EXIT STATUS 1
was reserved for it all the time.  The message system
is now stable enough to finally implement it.

jmc@ regarding the concept: "really good idea"

5 files changed, 49 insertions, 38 deletions

diff --git a/TODO b/TODO
index 2a7677ff..ba87d2d4 100644
--- a/TODO
+++ b/TODO
@@ -61,18 +61,6 @@ are mere guesses, and some may be wrong.
   reported by brad@  Sat, 15 Jan 2011 15:45:23 -0500
   loc ***  exist ***  algo ***  size **  imp *
 
-- .ta (tab settings)
-  #1 most important issue naddy@ Mon, 16 Feb 2015 20:59:17 +0100
-  ircbug(1) gnats(1) reported by brad@  Sat, 15 Jan 2011 15:50:51 -0500
-  also Tcl_NewStringObj(3) via wiz@  Wed, 5 Mar 2014 22:27:43 +0100
-  also posix2time(3) Carsten Kunze  Mon, 1 Dec 2014 13:03:10 +0100
-  loc **  exist ***  algo **  size **  imp ***
-
-- .ti (temporary indent)
-  found by naddy@ in xloadimage(1) [devel/libvstr] vstr(3)
-  found by bentley@ in nmh(1)  Mon, 23 Apr 2012 13:38:28 -0600
-  loc **  exist **  algo **  size *  imp ** (parser reorg helps a lot)
-
 - .while and .shift
   found by jca@ in ratpoison(1)  Sun, 30 Jun 2013 12:01:09 +0200
   loc *  exist **  algo **  size **  imp **
@@ -560,8 +548,6 @@ are mere guesses, and some may be wrong.
 
 Several areas can be cleaned up to make mandoc even faster.  These are
 
-- improve hashing mechanism for macros (quite important: performance)
-
 - the PDF file is HUGE: this can be reduced by using relative offsets
 
 ************************************************************************
diff --git a/main.c b/main.c
index 696c556f..6e100e51 100644
--- a/main.c
+++ b/main.c
@@ -968,15 +968,16 @@ static int
 woptions(struct curparse *curp, char *arg)
 {
 	char		*v, *o;
-	const char	*toks[7];
+	const char	*toks[8];
 
 	toks[0] = "stop";
 	toks[1] = "all";
-	toks[2] = "warning";
-	toks[3] = "error";
-	toks[4] = "unsupp";
-	toks[5] = "fatal";
-	toks[6] = NULL;
+	toks[2] = "style";
+	toks[3] = "warning";
+	toks[4] = "error";
+	toks[5] = "unsupp";
+	toks[6] = "fatal";
+	toks[7] = NULL;
 
 	while (*arg) {
 		o = arg;
@@ -986,15 +987,18 @@ woptions(struct curparse *curp, char *arg)
 			break;
 		case 1:
 		case 2:
-			curp->wlevel = MANDOCLEVEL_WARNING;
+			curp->wlevel = MANDOCLEVEL_STYLE;
 			break;
 		case 3:
-			curp->wlevel = MANDOCLEVEL_ERROR;
+			curp->wlevel = MANDOCLEVEL_WARNING;
 			break;
 		case 4:
-			curp->wlevel = MANDOCLEVEL_UNSUPP;
+			curp->wlevel = MANDOCLEVEL_ERROR;
 			break;
 		case 5:
+			curp->wlevel = MANDOCLEVEL_UNSUPP;
+			break;
+		case 6:
 			curp->wlevel = MANDOCLEVEL_BADARG;
 			break;
 		default:
@@ -1002,7 +1006,6 @@ woptions(struct curparse *curp, char *arg)
 			return 0;
 		}
 	}
-
 	return 1;
 }
 
diff --git a/mandoc.1 b/mandoc.1
index b1d80414..a4afd123 100644
--- a/mandoc.1
+++ b/mandoc.1
@@ -146,13 +146,14 @@ to be reported on the standard error output and to affect the exit status.
 The
 .Ar level
 can be
+.Cm style ,
 .Cm warning ,
 .Cm error ,
 or
 .Cm unsupp ;
 .Cm all
 is an alias for
-.Cm warning .
+.Cm style .
 By default,
 .Nm
 is silent.
@@ -594,27 +595,32 @@ option:
 .Pp
 .Bl -tag -width Ds -compact
 .It 0
-No warnings or errors occurred, or those that did were ignored because
-they were lower than the requested
+No style suggestions, warnings or errors occurred, or those that
+did were ignored because they were lower than the requested
 .Ar level .
+.It 1
+At least one style suggestion occurred, but no warning or error, and
+.Fl W Cm style
+was specified.
 .It 2
 At least one warning occurred, but no error, and
 .Fl W Cm warning
+or
+.Fl W Cm style
 was specified.
 .It 3
 At least one parsing error occurred,
 but no unsupported feature was encountered, and
 .Fl W Cm error
-or
-.Fl W Cm warning
-was specified.
+or a lower
+.Ar level
+was requested.
 .It 4
 At least one unsupported feature was encountered, and
-.Fl W Cm unsupp ,
-.Fl W Cm error
-or
-.Fl W Cm warning
-was specified.
+.Fl W Cm unsupp
+or a lower
+.Ar level
+was requested.
 .It 5
 Invalid command line arguments were specified.
 No input files have been read.
@@ -714,9 +720,22 @@ rendering can be produced.
 Documents causing warnings may render poorly when using other
 formatting tools instead of
 .Nm .
+.It Cm style
+An input file uses dubious or discouraged style.
+This is not a complaint about the syntax, and probably neither
+formatting nor portability are in danger.
+While great care is taken to avoid false positives on the higher
+message levels, the
+.Cm style
+level tries to reduce the probability that issues go unnoticed,
+so it may occasionally issue bogus suggestions.
+Please use your good judgement to decide whether any particular
+.Cm style
+suggestion really justifies a change to the input file.
 .El
 .Pp
 Messages of the
+.Cm style ,
 .Cm warning ,
 .Cm error ,
 and
diff --git a/mandoc.h b/mandoc.h
index be0693f3..6fc0d5cc 100644
--- a/mandoc.h
+++ b/mandoc.h
@@ -28,7 +28,7 @@
  */
 enum	mandoclevel {
 	MANDOCLEVEL_OK = 0,
-	MANDOCLEVEL_RESERVED,
+	MANDOCLEVEL_STYLE, /* style suggestions */
 	MANDOCLEVEL_WARNING, /* warnings: syntax, whitespace, etc. */
 	MANDOCLEVEL_ERROR, /* input has been thrown away */
 	MANDOCLEVEL_UNSUPP, /* input needs unimplemented features */
@@ -44,6 +44,8 @@ enum	mandoclevel {
 enum	mandocerr {
 	MANDOCERR_OK,
 
+	MANDOCERR_STYLE, /* ===== start of style suggestions ===== */
+
 	MANDOCERR_WARNING, /* ===== start of warnings ===== */
 
 	/* related to the prologue */
diff --git a/read.c b/read.c
index dfa10e56..8dd543ff 100644
--- a/read.c
+++ b/read.c
@@ -75,7 +75,7 @@ static	void	  mparse_parse_buffer(struct mparse *, struct buf,
 
 static	const enum mandocerr	mandoclimits[MANDOCLEVEL_MAX] = {
 	MANDOCERR_OK,
-	MANDOCERR_WARNING,
+	MANDOCERR_STYLE,
 	MANDOCERR_WARNING,
 	MANDOCERR_ERROR,
 	MANDOCERR_UNSUPP,
@@ -86,6 +86,7 @@ static	const enum mandocerr	mandoclimits[MANDOCLEVEL_MAX] = {
 static	const char * const	mandocerrs[MANDOCERR_MAX] = {
 	"ok",
 
+	"generic style suggestion",
 	"generic warning",
 
 	/* related to the prologue */
@@ -241,7 +242,7 @@ static	const char * const	mandocerrs[MANDOCERR_MAX] = {
 
 static	const char * const	mandoclevels[MANDOCLEVEL_MAX] = {
 	"SUCCESS",
-	"RESERVED",
+	"STYLE",
 	"WARNING",
 	"ERROR",
 	"UNSUPP",