mdocml: Introduce a new mandoc(1) message level, -W style, below -W

mdocml: Introduce a new mandoc(1) message level, -W style, below -W

[schwarze]

Log Message:
-----------
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"

Modified Files:
--------------
    mdocml:
        TODO
        main.c
        mandoc.1
        mandoc.h
        read.c

Revision Data
-------------
Index: read.c
===================================================================
RCS file: /home/cvs/mdocml/mdocml/read.c,v
retrieving revision 1.164
retrieving revision 1.165
diff -Lread.c -Lread.c -u -p -r1.164 -r1.165
--- read.c
+++ read.c
@@ -75,7 +75,7 @@ static	void	  mparse_parse_buffer(struct
 
 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
 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[MAN
 
 static	const char * const	mandoclevels[MANDOCLEVEL_MAX] = {
 	"SUCCESS",
-	"RESERVED",
+	"STYLE",
 	"WARNING",
 	"ERROR",
 	"UNSUPP",
Index: mandoc.h
===================================================================
RCS file: /home/cvs/mdocml/mdocml/mandoc.h,v
retrieving revision 1.215
retrieving revision 1.216
diff -Lmandoc.h -Lmandoc.h -u -p -r1.215 -r1.216
--- mandoc.h
+++ 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 */
@@ -43,6 +43,8 @@ enum	mandoclevel {
  */
 enum	mandocerr {
 	MANDOCERR_OK,
+
+	MANDOCERR_STYLE, /* ===== start of style suggestions ===== */
 
 	MANDOCERR_WARNING, /* ===== start of warnings ===== */
 
Index: TODO
===================================================================
RCS file: /home/cvs/mdocml/mdocml/TODO,v
retrieving revision 1.236
retrieving revision 1.237
diff -LTODO -LTODO -u -p -r1.236 -r1.237
--- TODO
+++ 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 **
@@ -559,8 +547,6 @@ are mere guesses, and some may be wrong.
   from kristaps@  Sat, 09 Aug 2014 13:51:36 +0200
 
 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
 
Index: main.c
===================================================================
RCS file: /home/cvs/mdocml/mdocml/main.c,v
retrieving revision 1.289
retrieving revision 1.290
diff -Lmain.c -Lmain.c -u -p -r1.289 -r1.290
--- main.c
+++ 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 *ar
 			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 *ar
 			return 0;
 		}
 	}
-
 	return 1;
 }
 
Index: mandoc.1
===================================================================
RCS file: /home/cvs/mdocml/mdocml/mandoc.1,v
retrieving revision 1.184
retrieving revision 1.185
diff -Lmandoc.1 -Lmandoc.1 -u -p -r1.184 -r1.185
--- mandoc.1
+++ mandoc.1
@@ -146,13 +146,14 @@ to be reported on the standard error out
 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
--
 To unsubscribe send an email to source+unsubscribe@mdocml.bsd.lv