summaryrefslogtreecommitdiffstats
path: root/mandoc.1
diff options
context:
space:
mode:
authorIngo Schwarze <schwarze@openbsd.org>2017-05-16 19:06:30 +0000
committerIngo Schwarze <schwarze@openbsd.org>2017-05-16 19:06:30 +0000
commit8f6135a7ad22bd59bffe447c62c75f571fb67076 (patch)
treea4bcd3bca0202a5deb49e1573de489b2b1526d47 /mandoc.1
parent023edf4ec5ce0ca4ca8353eda4442288245a4ee4 (diff)
downloadmandoc-8f6135a7ad22bd59bffe447c62c75f571fb67076.tar.gz
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"
Diffstat (limited to 'mandoc.1')
-rw-r--r--mandoc.141
1 files changed, 30 insertions, 11 deletions
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